macOS Application Integration¶

By collecting metric data from iOS, tvOS, and macOS applications, analyze the performance of Apple platform applications in a visual way.

Reading Path¶

First integration: See Quick Start
Complete integration: Continue reading this article
Upgrade from versions before 1.6.6: See Migration Guide
Initialization parameters: See SDK Initialization, RUM Configuration, Log Configuration, Trace Configuration
Custom capabilities: See Custom Tag Usage, Custom Track Rules, Data Masking
Advanced scenarios: See the dedicated pages under the "Advanced Scenarios" group
Troubleshooting: See Troubleshooting

Prerequisites¶

Note

If the RUM Headless service has been enabled, the prerequisites are already configured, and you can directly integrate the application.

Install DataKit;
Configure RUM Collector;
Configure DataKit to be publicly accessible and install the IP geolocation database.

macOS Alpha Description

In SDK versions 1.6.6 and above, the TrueWatchSDK main SDK covers iOS, tvOS, and macOS. Among them, macOS is currently an Alpha version, and it is not guaranteed that all iOS features are supported. Before integrating macOS, please verify the core links such as initialization, RUM, Log, Trace, and data synchronization in a test environment. Session Replay and Widget Extension are not supported on macOS.

Application Integration¶

Go to RUM > Create Application, select iOS, tvOS, or macOS application type;
Enter the application name;
Enter the application ID;
Select the application integration method:
- Public DataWay: Directly receive RUM data without installing the DataKit collector.
- Local environment deployment: Receive RUM data after meeting the prerequisites.

Installation¶

Source code: https://github.com/TrueWatchTech/datakit-ios

Demo: https://github.com/TrueWatchTech/truewatch-app-demo

CocoaPods Future Maintenance Notice

Since CocoaPods official plans to switch trunk to read-only after December 2, 2026, and no longer accept new Podspecs. Published Pod versions and existing builds will not immediately become invalid, but subsequent access to new versions, compatibility fixes, and security updates via CocoaPods may be limited. Therefore, when integrating or upgrading the SDK for the first time, it is recommended to use the Swift Package Manager method first.

Swift Package ManagerCarthageCocoaPods

Using Xcode UI

Select PROJECT -> Package Dependency, click the + under the Packages section.
In the popup page, enter https://github.com/TrueWatchTech/datakit-ios.git in the search box.
After Xcode successfully retrieves the package, the SDK configuration page will be displayed.

Dependency Rule: It is recommended to select Up to Next Major Version.

Add To Project: Select the supported project.

After filling in the configuration, click the Add Package button and wait for the loading to complete.
In the popup Choose Package Products for datakit-ios, select the Target to which the SDK needs to be added, click the Add Package button, and the SDK is now added successfully.

TrueWatchSDK: Add to the main project Target, supports iOS, tvOS, macOS. Among them, macOS is an Alpha version.

TrueWatchWidgetExtension: Only add to the iOS Widget Extension Target.

Using Package.swift

If your project is managed by SPM, add the SDK as a dependency, add dependencies to Package.swift.

// Main project
dependencies: [
.package(url: "https://github.com/TrueWatchTech/datakit-ios.git",
.upToNextMajor(from: "[latest_version]"))
]

Add dependencies for your Targets:

targets: [
    .target(
        name: "YourTarget",
        dependencies: [
            .product(name: "TrueWatchSDK", package: "TrueWatchSDK"),
        ]),
    .target(
        name: "YourWidgetExtensionTarget",
        dependencies: [
            .product(name: "TrueWatchWidgetExtension", package: "TrueWatchSDK"),
        ]),
    ]

Note: Swift Package Manager is supported from 1.4.0-beta.1 and above. In SDK versions 1.6.6 and above, SPM product names have been adjusted to TrueWatchSDK, TrueWatchWidgetExtension, TrueWatchSessionReplay. For migration of old product names, please refer to Migration Guide.

Configure the Cartfile file.

github "TrueWatchTech/datakit-ios" == [latest_version]

Update dependencies.

Execute the corresponding carthage update command according to your target platform (iOS, tvOS, or macOS), and add the --use-xcframeworks parameter to generate XCFrameworks:
- For iOS platform:
```
carthage update --platform iOS --use-xcframeworks
```
- For tvOS platform:
```
carthage update --platform tvOS --use-xcframeworks
```
- For macOS platform:
```
carthage update --platform macOS --use-xcframeworks
```
The generated xcframework is used like a regular Framework. Add the compiled library to your project.

TrueWatchSDK: Add to the main project Target, supports iOS, tvOS, macOS. Among them, macOS is an Alpha version.

TrueWatchWidgetExtension: Only add to the iOS Widget Extension Target.
In TARGETS -> Build Setting -> Other Linker Flags, add -ObjC.
SDK version support for Carthage integration:

TrueWatchSDK: >=1.6.6

TrueWatchWidgetExtension: >=1.6.6

CocoaPods Applicability Note

Since CocoaPods official plans to switch trunk to read-only after December 2, 2026, and no longer accept new Podspecs. For new projects or projects that are adjusting their dependency management approach, please use the Swift Package Manager method above to integrate the SDK first.

Configure the Podfile file.

Use Dynamic Library

use_frameworks!
def shared_pods
  pod 'TrueWatchSDK', '[latest_version]'
  # If you need to collect widget Extension data
  pod 'TrueWatchSDK/WidgetExtension', '[latest_version]'
end

# Main project
target 'yourProjectName' do
  shared_pods
end

# Widget Extension
target 'yourWidgetExtensionName' do
  shared_pods
end

Use Static Library

use_modular_headers!
# Main project
target 'yourProjectName' do
  pod 'TrueWatchSDK', '[latest_version]'
end
# Widget Extension
target 'yourWidgetExtensionName' do
  pod 'TrueWatchSDK/WidgetExtension', '[latest_version]'
end

Use the code library downloaded locally

Podfile file:

use_modular_headers!
# Main project
target 'yourProjectName' do
  pod 'TrueWatchSDK', :path => '[folder_path]'
end
# Widget Extension
target 'yourWidgetExtensionName' do
  pod 'TrueWatchSDK/WidgetExtension', :path => '[folder_path]'
end

folder_path: The path to the folder where TrueWatchSDK.podspec is located.

TrueWatchSDK.podspec file:

Modify s.version and s.source in the TrueWatchSDK.podspec file.

Pod::Spec.new do |s|
  s.name         = "TrueWatchSDK"
  s.version      = "[latest_version]"
s.source       = { :git => "https://github.com/TrueWatchTech/datakit-ios.git", :tag => s.version }
end

s.version: Modify to the specified version, it is recommended to be consistent with SDK_VERSION in Sources/Agent/Core/FTSDKVersion.h.

s.source: tag => s.version

Widget Extension Compatibility Writing:

For SDK versions 1.6.6 and above, it is recommended to use TrueWatchSDK/WidgetExtension. If the old project previously used pod 'FTMobileSDK', :subspecs => ['Extension'], after upgrading to TrueWatchSDK, the compatible subspec can still be used:

target 'yourWidgetExtensionName' do
  pod 'TrueWatchSDK', :subspecs => ['Extension']
end

Execute pod install in the Podfile directory to install the SDK.

Compatibility Note: In SDK versions 1.6.6 and above, the main Pod name is TrueWatchSDK. The old FTMobileSDK integration method is applicable to versions before 1.6.6; when upgrading to version 1.6.6 or above, please refer to Migration Guide to adjust the dependency name.

Add Header File¶

Objective-CSwift

#import <TrueWatchSDK/TrueWatchSDK.h>

import TrueWatchSDK

Detailed Configuration Entry¶

Advanced Scenarios¶

FAQ¶

About Crash Log Analysis¶

In Debug and Release modes during development, the thread backtrace captured when a Crash occurs is symbolicated. However, the release package does not contain the symbol table, and the key backtrace of the exception thread will display the image name but will not be converted into valid code symbols. The relevant information in the obtained crash log is all hexadecimal memory addresses, which cannot locate the crashing code. Therefore, it is necessary to parse the hexadecimal memory addresses into the corresponding classes and methods.

How to Find the dSYM File After Compilation or Packaging¶

In Xcode, the dSYM file is usually generated together with the compiled .app file and located in the same directory.
If the project has been archived, you can select Organizer from the Window menu in Xcode, then select the corresponding archive file. Right-click the archive file and select Show in Finder. In Finder, find the corresponding .xcarchive file. Right-click the .xcarchive file, select Show Package Contents, then enter the dSYMs folder to find the corresponding dSYM file.

No dSYM File Generated After Xcode Compilation?¶

Xcode Release compilation generates dSYM files by default, while Debug compilation does not generate them by default. The corresponding Xcode configuration is as follows:

Build Settings -> Code Generation -> Generate Debug Symbols -> Yes

Build Settings -> Build Option -> Debug Information Format -> DWARF with dSYM File

How to Upload Symbol Table When Bitcode is Enabled?¶

When you upload your bitcode App to the App Store, check the declaration for generating symbol files (dSYM files) in the submission dialog:

Before configuring the symbol table file, you need to download the dSYM file corresponding to the version from the App Store back to the local machine, then use a script to process and upload the symbol table file based on the input parameters.
You do not need to integrate the script into the Xcode project's Target, nor use the locally generated dSYM file to generate the symbol table file, because the symbol table information in the locally compiled dSYM file is hidden. If you upload the dSYM file generated by local compilation, the restored result will be symbols like "__hiden#XXX".

How to Retrieve the dSYM File Corresponding to an App Published to the App Store?¶

Distribution options uploaded to App Store Connect	dSym file
Don’t include bitcode Upload symbols	Retrieved via Xcode
Include bitcode Upload symbols	Retrieved via iTunes Connect Retrieved via Xcode, requires obfuscation handling using `.bcsymbolmap`.
Include bitcode Don’t upload symbols	Retrieved via Xcode, requires obfuscation handling using `.bcsymbolmap`.
Don’t include bitcode Don’t upload symbols	Retrieved via Xcode

Retrieve via Xcode¶

Xcode -> Window -> Organizer
Select the Archives tab
Find the published archive package, right-click the corresponding archive package, and select Show in Finder
Right-click the located archive file, select Show Package Contents
Select the dSYMs directory, which contains the downloaded dSYM file

Retrieve via iTunes Connect¶

Log in to App Store Connect;
Enter "My Apps"
Select a version in "App Store" or "TestFlight", click "Build Metadata", on this page, click the button "Download dSYM" to download the dSYM file

Obfuscation Handling with .bcsymbolmap¶

When finding the dSYM file via Xcode, you can see the BCSymbolMaps directory

Open the terminal and use the following command for obfuscation handling

xcrun dsymutil -symbol-map <BCSymbolMaps_path> <.dSYM_path>

Add Global Variables to Avoid Conflicting Fields¶

To avoid conflicts between custom fields and SDK data, it is recommended to add a prefix of project abbreviation to tag names, for example custom_tag_name, the key value used in the project can be queried in the source code. When a global variable in the SDK has the same name as a variable in RUM or Log, RUM and Log will override the global variable in the SDK.