Skip to content

Quick Start

This document provides the shortest integration path for the macOS RUM SDK to help you complete verifiable data reporting with minimal steps.

The application supports automatic access with Agent and manual access. The following steps describe the minimal configuration for manual access.

Prerequisites

Before you begin, complete the following preparations:

  1. Create a macOS application in Real User Monitoring (RUM) and obtain the RUM App ID
  2. Confirm the reporting URL and authentication method
  3. Local environment deployment: prepare datakitUrl
  4. Public DataWay: prepare datawayUrl and clientToken
  5. Confirm that SDK installation has been completed in the project, using CocoaPods or Swift Package Manager

Integration Steps

  1. Install FTMacOSSDK in the project
  2. Initialize FTSDKConfig before the application starts
  3. Initialize FTRumConfig and enable collection of View, Action, Resource, crashes, and freezes
  4. Keep debug logging enabled, run the application, and trigger a window switch or network request
  5. Confirm in the console and on the Guance platform that data has been reported successfully

Install the SDK

For installation methods, refer directly to Application Access.

If you only want to verify quickly, we recommend using CocoaPods or Swift Package Manager first.

Minimal Initialization Example

Because the viewDidLoad method of the first displayed view NSViewController and the windowDidLoad method of NSWindowController are called earlier than AppDelegate applicationDidFinishLaunching, to avoid anomalies in lifecycle collection for the first view, we recommend initializing the SDK in main.m or main.swift.

// main.m file
#import "FTMacOSSDK.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.enableTrackAppCrash = YES;
        rumConfig.enableTrackAppANR = YES;
        rumConfig.enableTrackAppFreeze = YES;
        rumConfig.enableTraceUserAction = YES;
        rumConfig.enableTraceUserView = YES;
        rumConfig.enableTraceUserResource = YES;
        rumConfig.errorMonitorType = FTErrorMonitorAll;
        rumConfig.deviceMetricsMonitorType = FTDeviceMetricsMonitorAll;
        [[FTSDKAgent sharedInstance] startRumWithConfigOptions:rumConfig];
    }
    return NSApplicationMain(argc, argv);
}
import Cocoa
import FTMacOSSDK

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.enableTraceUserAction = true
rumConfig.enableTrackAppANR = true
rumConfig.enableTraceUserView = true
rumConfig.enableTraceUserResource = true
rumConfig.enableTrackAppCrash = true
rumConfig.enableTrackAppFreeze = true
rumConfig.errorMonitorType = .all
rumConfig.deviceMetricsMonitorType = .all
rumConfig.monitorFrequency = .rare
FTSDKAgent.sharedInstance().startRum(withConfigOptions: rumConfig)

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

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

Optional: Initialize Log and Trace

If you also need log collection or distributed tracing, continue by adding the following initialization:

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

FTTraceConfig *traceConfig = [[FTTraceConfig alloc] init];
traceConfig.enableAutoTrace = YES;
traceConfig.enableLinkRumData = YES;
[[FTSDKAgent sharedInstance] startTraceWithConfigOptions:traceConfig];
let loggerConfig = FTLoggerConfig()
loggerConfig.enableCustomLog = true
loggerConfig.enableLinkRumData = true
FTSDKAgent.sharedInstance().startLogger(withConfigOptions: loggerConfig)

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

Verify the Integration

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

If you need further troubleshooting, see Troubleshooting.

Next Steps

Feedback

Is this page helpful?