Skip to content

Quick Start

This document provides the shortest integration path for the iOS/tvOS/macOS RUM SDK, helping you complete a verifiable data upload with minimal steps.

Prerequisites

Before starting, complete the following preparations:

  1. Create an iOS, tvOS, or macOS application in RUM and obtain the RUM App ID
  2. Confirm the upload address and authentication method:
  3. Local environment deployment: Prepare datakitUrl
  4. Public DataWay: Prepare datawayUrl and clientToken
  5. Confirm that the project has completed the SDK installation; Swift Package Manager is recommended, and CocoaPods and Carthage are also compatible

Integration Steps

  1. Install GuanceSDK in the project
  2. Initialize FTSDKConfig when the application starts
  3. Initialize FTRumConfig and enable View, Action, Resource, crash, and lag collection
  4. Enable debug logs, run the application, and trigger a page open or network request
  5. Confirm in the console and the Guance platform that the data has been successfully uploaded

Install the SDK

For installation methods, please refer directly to App Access.

If you only want to quickly verify, it is recommended to use Swift Package Manager first; only choose CocoaPods or Carthage when there are existing dependency management constraints.

Minimal Initialization Example

iOS/tvOS is usually initialized in AppDelegate. In macOS, the viewDidLoad method of the first displayed NSViewController or the windowDidLoad method of NSWindowController is called earlier than the AppDelegate applicationDidFinishLaunching. To avoid abnormal collection of the first view's lifecycle, it is recommended to perform SDK initialization in main.m or main.swift.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // For local environment deployment, use [[FTSDKConfig alloc] initWithDatakitUrl:datakitUrl]
    FTSDKConfig *config = [[FTSDKConfig alloc] initWithDatawayUrl:datawayUrl clientToken:clientToken];
    config.enableSDKDebugLog = YES;
    [FTMobileAgent startWithConfigOptions:config];

    FTRumConfig *rumConfig = [[FTRumConfig alloc] initWithAppid:appid];
    rumConfig.enableTraceUserView = YES;
    rumConfig.enableTraceUserAction = YES;
    rumConfig.enableTraceUserResource = YES;
    rumConfig.enableTrackAppFreeze = YES;
    rumConfig.enableTrackAppCrash = YES;
    rumConfig.enableTrackAppANR = YES;
    [[FTMobileAgent sharedInstance] startRumWithConfigOptions:rumConfig];
    return YES;
}

// main.m file
#import <Cocoa/Cocoa.h>
#import <GuanceSDK/GuanceSDK.h>
int main(int argc, const char * argv[]) {
    @autoreleasepool {
        // For local environment deployment, use [[FTSDKConfig alloc] initWithDatakitUrl:datakitUrl]
        FTSDKConfig *config = [[FTSDKConfig alloc] initWithDatawayUrl:datawayUrl clientToken:clientToken];
        config.enableSDKDebugLog = YES;
        [FTSDKAgent startWithConfigOptions:config];

        FTRumConfig *rumConfig = [[FTRumConfig alloc] initWithAppid:appid];
        rumConfig.enableTraceUserView = YES;
        rumConfig.enableTraceUserAction = YES;
        rumConfig.enableTraceUserResource = YES;
        rumConfig.enableTrackAppFreeze = YES;
        rumConfig.enableTrackAppCrash = YES;
        rumConfig.enableTrackAppANR = YES;
        rumConfig.errorMonitorType = FTErrorMonitorAll;
        rumConfig.deviceMetricsMonitorType = FTDeviceMetricsMonitorAll;
        [[FTSDKAgent sharedInstance] startRumWithConfigOptions:rumConfig];
    }
    return NSApplicationMain(argc, argv);
}

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // For local environment deployment, use FTSDKConfig(datakitUrl: datakitUrl)
    let config = FTSDKConfig(datawayUrl: datawayUrl, clientToken: clientToken)
    config.enableSDKDebugLog = true
    FTMobileAgent.start(withConfigOptions: config)

    let rumConfig = FTRumConfig(appid: appid)
    rumConfig.enableTraceUserView = true
    rumConfig.enableTraceUserAction = true
    rumConfig.enableTraceUserResource = true
    rumConfig.enableTrackAppFreeze = true
    rumConfig.enableTrackAppCrash = true
    rumConfig.enableTrackAppANR = true
    FTMobileAgent.sharedInstance().startRum(withConfigOptions: rumConfig)
    return true
}

import Cocoa
import GuanceSDK
let delegate = AppDelegate()
NSApplication.shared.delegate = delegate

// For local environment deployment, use FTSDKConfig(datakitUrl: datakitUrl)
let config = FTSDKConfig(datawayUrl: datawayUrl, clientToken: clientToken)
config.enableSDKDebugLog = true
FTSDKAgent.start(withConfigOptions: config)

let rumConfig = FTRumConfig(appid: appid)
rumConfig.enableTraceUserView = true
rumConfig.enableTraceUserAction = true
rumConfig.enableTraceUserResource = true
rumConfig.enableTrackAppFreeze = true
rumConfig.enableTrackAppCrash = true
rumConfig.enableTrackAppANR = true
rumConfig.errorMonitorType = .all
rumConfig.deviceMetricsMonitorType = .all
FTSDKAgent.sharedInstance().startRum(withConfigOptions: rumConfig)

_ = NSApplicationMain(CommandLine.argc, CommandLine.unsafeArgv)

When using Swift, first create the main.swift file and remove @main or @NSApplicationMain from AppDelegate.swift.

The above example meets the minimum RUM integration and enables crash and lag detection by default; if using local environment deployment, replace initWithDatawayUrl:clientToken: / FTSDKConfig(datawayUrl:clientToken:) with initWithDatakitUrl: / FTSDKConfig(datakitUrl:). FTMobileConfig is still compatible for now, but new code is recommended to use FTSDKConfig. macOS is currently an Alpha version, and not all iOS features are guaranteed to be supported.

Optional: Initialize Log and Trace

If you also need log collection or tracing, you can add the following initialization:

FTLoggerConfig *loggerConfig = [[FTLoggerConfig alloc] init];
loggerConfig.enableCustomLog = YES;
loggerConfig.enableLinkRumData = YES;
[[FTMobileAgent sharedInstance] startLoggerWithConfigOptions:loggerConfig];

FTTraceConfig *traceConfig = [[FTTraceConfig alloc] init];
traceConfig.enableAutoTrace = YES;
traceConfig.enableLinkRumData = YES;
[[FTMobileAgent sharedInstance] startTraceWithConfigOptions:traceConfig];

let loggerConfig = FTLoggerConfig()
loggerConfig.enableCustomLog = true
loggerConfig.enableLinkRumData = true
FTMobileAgent.sharedInstance().startLogger(withConfigOptions: loggerConfig)

let traceConfig = FTTraceConfig()
traceConfig.enableAutoTrace = true
traceConfig.enableLinkRumData = true
FTMobileAgent.sharedInstance().startTrace(withConfigOptions: traceConfig)

Verify Integration Success

  1. Keep enableSDKDebugLog = YES/true enabled, run the application
  2. Open a page, or initiate a URLSession network request
  3. In the Xcode console, confirm that SDK initialization and data synchronization related logs appear
  4. Return to the Guance console, confirm that the corresponding RUM data has appeared in the application

If further troubleshooting is needed, please check Troubleshooting.

Next Steps

Feedback

Is this page helpful?