iOS/tvOS Application Integration¶

By collecting metrics data from various iOS applications, analyze the performance of each iOS application in a visual way.

Reading Path¶

First-time integration: Start with Quick Start
Complete integration: Continue reading this article
Initialization parameters: Refer to SDK Initialization, RUM Configuration, Log Configuration, Trace Configuration
Custom capabilities: Refer to Custom Tag Usage, Custom Collection Rules, Data Collection Masking
Advanced scenarios: Refer to specialized pages under the "Advanced Scenarios" group
Troubleshooting: Refer to Troubleshooting

Prerequisites¶

Note

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

Install DataKit;
Configure the RUM Collector;
Configure DataKit to be accessible via the public network and install the IP Geolocation Database.

Application Integration¶

Go to RUM > Create > iOS;
Enter the application name;
Enter the application ID;
Select the application integration method:
- Public DataWay: Directly receives RUM data without installing the DataKit collector.
- Local environment deployment: Receives RUM data after meeting the prerequisites.

Installation¶

Source Code Address: https://github.com/GuanceCloud/datakit-ios

Demo: https://github.com/GuanceDemo/guance-app-demo

CocoaPodsCarthageSwift Package Manager

Configure the Podfile file.

Using Dynamic Library

use_frameworks!
def shared_pods
  pod 'FTMobileSDK', '[latest_version]'
  # If widget Extension data collection is needed
  pod 'FTMobileSDK', :subspecs => ['Extension']
end

# Main project
target 'yourProjectName' do
  shared_pods
end

# Widget Extension
target 'yourWidgetExtensionName' do
  shared_pods
end

Using Static Library

use_modular_headers!
# Main project
target 'yourProjectName' do
  pod 'FTMobileSDK', '[latest_version]'
end
# Widget Extension
target 'yourWidgetExtensionName' do
  pod 'FTMobileSDK', :subspecs => ['Extension']
end

Using the library downloaded locally

Podfile file:

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

folder_path: The path to the folder containing the FTMobileSDK.podspec file.

FTMobileSDK.podspec file:

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

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

s.version: Modify to the specified version, recommended to be consistent with SDK_VERSION in FTMobileSDK/FTMobileAgent/Core/FTMobileAgentVersion.h.

s.source: tag => s.version

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

Configure the Cartfile file.

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

Update dependencies.

Depending on your target platform (iOS or tvOS), execute the corresponding carthage update command 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
```
The generated xcframework is used in the same way as a regular Framework. Add the compiled library to your project.

FTMobileAgent: Add to the main project Target, supports iOS and tvOS platforms.

FTMobileExtension: Add to the Widget Extension Target.
Add -ObjC to TARGETS -> Build Setting -> Other Linker Flags.
SDK version support when using Carthage integration:

FTMobileAgent: >=1.3.4-beta.2

FTMobileExtension: >=1.4.0-beta.1

Using Xcode UI

Select PROJECT -> Package Dependency, click the + under the Packages section.
In the pop-up page, enter https://github.com/GuanceCloud/datakit-ios.git in the search box.
After Xcode successfully fetches the package, it will display the SDK configuration page.

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 pop-up window Choose Package Products for datakit-ios, select the Target to which you need to add the SDK, click the Add Package button. The SDK is now successfully added.

FTMobileSDK: Add to the main project Target

FTMobileExtension: Add to the Widget Extension Target

Using Package.swift

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

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

Add dependencies for your Targets

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

Note: Swift Package Manager is supported from version 1.4.0-beta.1 and above.

Add Header File¶

Objective-CSwift

//CocoaPods, SPM
#import "FTMobileSDK.h"
//Carthage
#import <FTMobileSDK/FTMobileSDK.h>

import FTMobileSDK

Detailed Configuration Entries¶

Advanced Scenarios¶

Frequently Asked Questions¶

About Crash Log Analysis¶

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

How to Find the dSYM File After Compilation or Packaging¶

In Xcode, the dSYM file is typically generated along with the compiled .app file and located in the same directory.
If you have archived the project, you can select Organizer from the Window menu in Xcode, then choose the corresponding archive file. Right-click the archive file, select Show in Finder, locate the corresponding .xcarchive file in Finder. Right-click the .xcarchive file, select Show Package Contents, then navigate to the dSYMs folder to find the corresponding dSYM file.

XCode Does Not Generate dSYM File After Compilation?¶

XCode Release compilation generates dSYM files by default, while Debug compilation does not by default. The corresponding Xcode configurations 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 Table When BitCode is Enabled?¶

When you upload your bitcode App to the App Store, check the option to declare the generation of symbol files (dSYM files) in the submission dialog:

Before configuring the symbol table file, you need to download the corresponding dSYM file for that version from the App Store to your local machine, then use a script to process and upload the symbol table file based on input parameters.
There is no need to integrate the script into the Target of the Xcode project, nor should you 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 using the locally compiled dSYM file, the restored results will be symbols like "__hiden#XXX".

How to Retrieve the dSYM File Corresponding to an App Already Published to the 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, requires using `.bcsymbolmap` for deobfuscation.
Include bitcode Don’t upload symbols	Retrieve via Xcode, requires using `.bcsymbolmap` for deobfuscation.
Don’t include bitcode Don’t upload symbols	Retrieve 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 the Show in Finder operation
Right-click the located archive file, select the Show Package Contents operation
Select the dSYMs directory. The dSYM file downloaded is located inside this directory.

Retrieve via iTunes Connect¶

Log in to App Store Connect;
Go to "My Apps"
Under "App Store" or "TestFlight", select a specific version, click "Build Metadata". On this page, click the "Download dSYM" button to download the dSYM file.

.bcsymbolmap Deobfuscation Processing¶

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

Open the terminal and use the following command for deobfuscation processing

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 project abbreviation prefix to tag names, for example, df_tag_name. The key values used in the project can be queried from the source code. When the same variable appears in the SDK global variables and RUM/Log, RUM/Log will override the global variable in the SDK.