Skip to content

iOS/tvOS/macOS App Integration


Collect metrics data from iOS, tvOS, and macOS apps to analyze the performance of apps on Apple platforms visually.

Reading Path

Prerequisites

SDK 1.6.8+ requires iOS 15, tvOS 15, macOS 12 or later. For upgrade requirements, see Upgrade to 1.6.8; for product renaming and legacy deployment requirements, see Upgrade to 1.6.6.

Note

If the RUM Headless service is enabled, the prerequisites are automatically configured and you can integrate the app directly.

When deploying in a local environment, complete the following data receiver configurations; when using public DataWay, you do not need to deploy DataKit yourself.

macOS Alpha Notes

In SDK 1.6.6 and later, the TrueWatchSDK main SDK covers iOS, tvOS, and macOS. macOS is currently an Alpha version, and not all iOS features are guaranteed to be supported. Before integrating macOS, verify core flows such as initialization, RUM, Log, Trace, and data synchronization in a test environment first. Widget Extension does not support macOS; for the integration and capability boundaries of macOS Electron Session Replay, see macOS Electron Monitoring.

App Integration

  1. Go to RUM > Create App and select the iOS, tvOS, or macOS app type;
  2. Enter the app name;
  3. Enter the app ID;
  4. Under "Select Access Method", select Agent Auto-Access or Manual Access, then complete "Access Configuration".

Select Access Method

On the app configuration page, select "Agent Auto-Access" or "Manual Access", then complete "Access Configuration". For existing apps, you can go directly to the configuration page to continue integration.

Access Method Use Cases Entry Point
Agent Auto-Access Want a coding assistant to analyze the project and complete SDK integration Copy the prompt generated in the console and give it to the coding assistant in the app code repository for execution
Manual Access Want to install the SDK and configure parameters yourself Confirm the data reporting method, then complete configuration according to this document and Quick Start

Agent Auto-Access

  1. On the current app's configuration page, select "Agent Auto-Access".
  2. Copy the complete prompt under "Access Configuration" and make sure it uses the current app's access information.
  3. Open the coding assistant in the app code repository, paste the prompt, and let the Agent analyze the project and complete SDK configuration according to the integration guide.
  4. Build and run the app, trigger actions such as page views, and confirm in the current app's Explorer that data is received.

If the page indicates that the personal API Key or temporary authorization code is not ready, follow the prompts to complete it and then copy the prompt again.

Manual Access

On the app configuration page, select "Manual Access" and confirm the data reporting method:

  • Public DataWay: receives RUM data directly; no need to install the DataKit collector.
  • Local environment deployment: receives RUM data after the prerequisites are met.

Complete SDK installation, initialization, and verification according to Installation and Quick Start. If SDK configuration already exists, review and reuse it first to avoid duplicate initialization.

Installation

tvOS

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

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

CocoaPods Future Maintenance Notes

According to the official CocoaPods announcement, CocoaPods plans to switch trunk to read-only after December 2, 2026 and will no longer accept new Podspecs. Published Pod versions and existing builds will not become invalid immediately, but obtaining new versions, compatibility fixes, and security updates through CocoaPods may be limited in the future. Therefore, when integrating or upgrading the SDK for the first time, prefer integrating via Swift Package Manager.

Using Xcode UI

  1. In Xcode, select File -> Add Package Dependency....

  2. In the search field on the displayed page, enter https://github.com/TrueWatchTech/datakit-ios.git.

  3. After Xcode resolves the package, select the dependency version rule; Up to Next Major Version is recommended.

    Select the project to add it to, click Add Package, and wait for loading to complete.

  4. After package resolution is complete, select the products to add to each Target in the Package Products list, and click Add Package.

    TrueWatchSDK: add to the main project Target; supports iOS, tvOS, and macOS. macOS is currently an Alpha version.

    TrueWatchWidgetExtension: only add to the iOS Widget Extension Target.

Using Package.swift

If your project itself is a Swift Package, add the SDK as a dependency by adding dependencies in 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 in 1.4.0-beta.1 and later. In SDK 1.6.6 and later, the SPM product names have been adjusted to TrueWatchSDK, TrueWatchWidgetExtension, and TrueWatchSessionReplay. For migration from old product names, see Migration Guide.

  1. Configure the Cartfile.

    github "TrueWatchTech/datakit-ios" == [latest_version]
    
  2. Update dependencies.

    Depending on your target platform (iOS, tvOS, or macOS), run the corresponding carthage update command and add the --use-xcframeworks parameter to generate XCFrameworks:

    • For the iOS platform:

      carthage update --platform iOS --use-xcframeworks
      
    • For the tvOS platform:

      carthage update --platform tvOS --use-xcframeworks
      
    • For the macOS platform:

      carthage update --platform macOS --use-xcframeworks
      

    The generated xcframework is used in the same way as a regular Framework. Add the compiled library to the project.

    TrueWatchSDK: add to the main project Target; supports iOS, tvOS, and macOS. macOS is currently an Alpha version.

    TrueWatchWidgetExtension: only add to the iOS Widget Extension Target.

  3. Add -ObjC under TARGETS -> Build Setting -> Other Linker Flags.

  4. When integrating with Carthage, the supported SDK versions are:

    TrueWatchSDK: >=1.6.6

    TrueWatchWidgetExtension: >=1.6.6

CocoaPods Usage Notes

According to the official CocoaPods announcement, CocoaPods plans to switch trunk to read-only after December 2, 2026 and will no longer accept new Podspecs. For new projects or projects adjusting their dependency management approach, prefer the Swift Package Manager method above to integrate the SDK.

  1. Configure the Podfile.

    • Using a 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
      
    • Using a 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
      
    • Download the code repository for local use

      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 containing TrueWatchSDK.podspec.

      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: change to the specified version; it is recommended to keep it consistent with SDK_VERSION in Sources/Agent/Core/FTSDKVersion.h.

      s.source: tag => s.version

Widget Extension compatible syntax:

SDK 1.6.6 and later recommends using TrueWatchSDK/WidgetExtension. If an old project previously used pod 'FTMobileSDK', :subspecs => ['Extension'], it can continue to use the compatible subspec after upgrading to TrueWatchSDK:

target 'yourWidgetExtensionName' do
  pod 'TrueWatchSDK', :subspecs => ['Extension']
end
  1. Run pod install in the Podfile directory to install the SDK.

Compatibility Notes: In SDK 1.6.6 and later, the main Pod name is TrueWatchSDK. The old FTMobileSDK integration method applies to versions earlier than 1.6.6; when upgrading to 1.6.6 or later, see Migration Guide to adjust the dependency name.

Add Header Files

#import <TrueWatchSDK/TrueWatchSDK.h>
import TrueWatchSDK

Detailed Configuration Entry Points

Advanced Scenarios

FAQ

About Crash Log Analysis

In Debug and Release modes during development, the thread backtraces captured during a Crash are symbolized. However, release packages do not include symbol tables. Key backtraces of the abnormal thread display image names and are not converted into valid code symbols. The relevant information in the obtained crash log consists of hexadecimal memory addresses and cannot locate the crashing code. Therefore, the hexadecimal memory addresses need to be resolved 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 is located in the same directory.
  • If you have archived the project, select Organizer from the Window menu in Xcode, and then select the corresponding archive. Right-click the archive, select Show in Finder”, and locate the corresponding .xcarchive file in Finder. Right-click the .xcarchive file, select Show Package Contents, and then go to the dSYMs folder to find the corresponding dSYM file.

Why is no dSYM file generated after Xcode compilation?

Xcode Release builds generate a dSYM file by default, while Debug builds do not. The corresponding Xcode settings are 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 files when Bitcode is enabled?

When uploading your Bitcode app to App Store, select the option in the submission dialog to declare generation of symbol files (dSYM files):

  • Before configuring the symbol table file, download the dSYM file corresponding to that version from App Store to your local machine, and then use a script to process and upload the symbol table file according to the input parameters.
  • You no longer need to integrate the script into the Xcode project Target, and do not use locally generated dSYM files to generate the symbol table file, because the symbol table information in locally compiled dSYM files is hidden. If you upload a locally compiled dSYM file, the restored result will be symbols such as "__hiden#XXX".

How to retrieve the dSYM file corresponding to an app released to App Store?

Distribution options when uploading the app to App Store Connect dSYM file
Don’t include bitcode
Upload symbols
Retrieve via Xcode
Include bitcode
Upload symbols
Retrieve via iTunes Connect
Retrieve via Xcode; you need to use .bcsymbolmap for deobfuscation.
Include bitcode
Don’t upload symbols
Retrieve via Xcode; you need to use .bcsymbolmap for deobfuscation.
Don’t include bitcode
Don’t upload symbols
Retrieve via Xcode
Retrieve via Xcode
  1. Xcode -> Window -> Organizer

  2. Select the Archives tab

  3. Find the released archive, right-click the corresponding archive, and select Show in Finder

  4. Right-click the located archive file and select Show Package Contents

  5. Select the dSYMs directory; the dSYM file downloaded is inside

Retrieve via iTunes Connect
  1. Log in to App Store Connect;
  2. Go to "My Apps"
  3. In "App Store" or "TestFlight", select a version, click "Build Metadata", and on this page click the "Download dSYM" button to download the dSYM file
.bcsymbolmap Deobfuscation

When you locate the dSYM file through Xcode, you can see the BCSymbolMaps directory

Open Terminal and use the following command for deobfuscation:

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

Add Global Variables to Avoid Field Conflicts

To avoid conflicts between custom fields and SDK data, it is recommended to add a project abbreviation prefix to tag names, for example, custom_tag_name. For key values used in the project, see the source code. When a global variable in the SDK has the same name as a RUM or Log variable, RUM or Log overrides the global variable in the SDK.