iOS/tvOS Application Integration¶

By collecting metric data from various iOS applications, analyze the performance of each iOS application in a visualized manner.

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 Desensitization
Advanced scenarios: Refer to specialized pages under the "Advanced Scenarios" section
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 publicly accessible and install the IP Geolocation library.

Application Integration¶

Navigate 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 Repository: https://github.com/GuanceCloud/datakit-ios

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

Swift Package ManagerCarthageCocoaPods

Using Xcode UI

Select PROJECT -> Package Dependency, click the + under the Packages section.
In the pop-up page's search box, enter https://github.com/GuanceCloud/datakit-ios.git.
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 the SDK needs to be added, click the Add Package button. At this point, the SDK has been 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.

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 the iOS platform:
```
carthage update --platform iOS --use-xcframeworks
```
- For the 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 the project.

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

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

FTMobileAgent: >=1.3.4-beta.2

FTMobileExtension: >=1.4.0-beta.1

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

Download the code repository locally for use

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.

Adding Header Files¶

Objective-CSwift

#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, the published package does not contain 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 consists of 16-bit hexadecimal memory addresses, which cannot locate the crashing code. Therefore, it is necessary to parse the 16-bit hexadecimal memory addresses into corresponding classes and methods.

How to Find the dSYM File After Compilation or Packaging¶

In Xcode, dSYM files are typically generated alongside the compiled .app file and are 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, 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. 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 box in the submission dialog to declare the generation of symbol files (dSYM files):

Before configuring the symbol table file, you need to download the dSYM file corresponding to 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 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 using locally compiled dSYM files, the restored results will be symbols similar to "__hiden#XXX".

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

Distribution options for App uploaded 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 de-obfuscation processing using `.bcsymbolmap`.
Include bitcode Don’t upload symbols	Retrieve via Xcode, requires de-obfuscation processing using `.bcsymbolmap`.
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, select the Show in Finder operation
Right-click the located archive file, select the Show Package Contents operation
Select the dSYMs directory, the dSYM files are located within this directory

Retrieve via iTunes Connect¶

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

.bcsymbolmap De-obfuscation Processing¶

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

Open the terminal and use the following command for de-obfuscation processing

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

Adding 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, custom_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 as in RUM or Log, RUM and Log will override the global variables in the SDK.