iOS/tvOS/macOS 1.6.6 Migration Guide¶

This document is intended for projects migrating from the old iOS SDK / macOS SDK to SDK 1.6.6 and later. Starting from 1.6.6, the main SDK for Apple platforms is unified as GuanceSDK, shared by iOS, tvOS, and macOS.

Overview of Changes¶

• The main SDK library is unified as GuanceSDK.
• datakit-macos is no longer maintained separately; macOS capabilities are merged into the current SDK repository.
• Session Replay is provided as a standalone product GuanceSessionReplay, supporting iOS only.
• Widget Extension is provided as a standalone product GuanceWidgetExtension, for iOS Widget Extension Targets only.
• iOS, tvOS, and macOS share the main SDK; APIs not supported on a particular platform will be declared with availability attributes.

Minimum system versions are defined by the release package configuration:

• iOS 12.0+
• tvOS 12.0+
• macOS 10.14+

Installation Migration¶

CocoaPods¶

Old main SDK:

pod 'FTMobileSDK'

Migrate to:

pod 'GuanceSDK'

For Session Replay:

pod 'GuanceSDK/SessionReplay'

For Widget Extension data collection, integrate only in the Widget Extension Target. New integrations should use the WidgetExtension subspec:

target 'YourWidgetExtension' do
  pod 'GuanceSDK/WidgetExtension'
end

If your old project originally used pod 'FTMobileSDK', :subspecs => ['Extension'], after upgrading to GuanceSDK, you can continue using the compatibility subspec:

target 'YourWidgetExtension' do
  pod 'GuanceSDK', :subspecs => ['Extension']
end

Compatibility notes:

• GuanceSDK includes the main SDK capabilities by default.
• GuanceSDK/SessionReplay supports iOS only.
• GuanceSDK/WidgetExtension is for iOS Widget Extension Targets only.
• The old GuanceSDK/FTSessionReplay and GuanceSDK/Extension are kept as compatibility aliases. pod 'GuanceSDK', :subspecs => ['Extension'] can also continue to integrate Widget Extension capabilities. New integrations should use SessionReplay and WidgetExtension.
• macOS Targets should not integrate the SessionReplay or WidgetExtension subspec.

Swift Package Manager¶

SPM product names have been updated to the new brand product names:

After adding the Swift Package in Xcode, select the corresponding product for your Target:

• App Target: GuanceSDK
• iOS Session Replay Target: GuanceSessionReplay
• Widget Extension Target: GuanceWidgetExtension

Swift import:

import GuanceSDK

For Session Replay:

import GuanceSessionReplay

Framework / XCFramework¶

Framework product names have been updated:

Objective-C is recommended to use the new entry header:

#import <GuanceSDK/GuanceSDK.h>

Compatibility entries are still available:

#import <GuanceSDK/FTMobileSDK.h>
#import <GuanceSDK/FTMobileAgent.h>

Session Replay recommended entry header by integration method:

// CocoaPods
#import <GuanceSDK/FTSessionReplay.h>

// Framework / XCFramework
#import <GuanceSessionReplay/FTSessionReplay.h>

// Swift Package Manager
@import GuanceSessionReplay;

API Migration¶

Initialization Configuration¶

New code is recommended to migrate from FTMobileConfig to FTSDKConfig.

Old approach:

FTMobileConfig *config = [[FTMobileConfig alloc] initWithDatakitUrl:datakitUrl];
[FTMobileAgent startWithConfigOptions:config];

New approach:

FTSDKConfig *config = [[FTSDKConfig alloc] initWithDatakitUrl:datakitUrl];
[FTMobileAgent startWithConfigOptions:config];

Notes:

• FTMobileConfig is still usable now, and inherits from FTSDKConfig.
• FTMobileConfig is deprecated; new code should use FTSDKConfig.
• FTMobileAgent can still be used as the entry point; new code can also use the compatibility alias FTSDKAgent.

Sampling Rate Parameter Naming¶

samplerate has been adjusted to the standard camelCase sampleRate.

Affected configurations:

• FTRumConfig
• FTTraceConfig
• FTLoggerConfig

Old approach:

FTRumConfig *rumConfig = [[FTRumConfig alloc] initWithAppid:appId];
rumConfig.samplerate = 100;

FTTraceConfig *traceConfig = [[FTTraceConfig alloc] init];
traceConfig.samplerate = 100;

FTLoggerConfig *loggerConfig = [[FTLoggerConfig alloc] init];
loggerConfig.samplerate = 100;

New approach:

FTRumConfig *rumConfig = [[FTRumConfig alloc] initWithAppid:appId];
rumConfig.sampleRate = 100;

FTTraceConfig *traceConfig = [[FTTraceConfig alloc] init];
traceConfig.sampleRate = 100;

FTLoggerConfig *loggerConfig = [[FTLoggerConfig alloc] init];
loggerConfig.sampleRate = 100;

Notes:

• samplerate is still usable now, but deprecated.
• sampleRate and samplerate map to the same value.
• For SDK versions below 1.6.6, continue to use samplerate.

Session Replay¶

Session Replay related public types still use the FT prefix, for example:

FTSessionReplayConfig *config = [[FTSessionReplayConfig alloc] init];
config.sampleRate = 100;

Old code may use different paths depending on the integration method:

#import <FTMobileSDK/FTRumSessionReplay.h>
// or
#import <FTSessionReplay/FTRumSessionReplay.h>

New code should select the entry header by integration method:

@import GuanceSessionReplay;

Widget Extension¶

The Widget Extension component should be integrated only in the Widget Extension Target.

CocoaPods example. New integrations should use the WidgetExtension subspec:

target 'YourWidgetExtension' do
  pod 'GuanceSDK/WidgetExtension'
end

When upgrading an old project, if it originally used pod 'FTMobileSDK', :subspecs => ['Extension'], you can continue to keep the subspec form:

target 'YourWidgetExtension' do
  pod 'GuanceSDK', :subspecs => ['Extension']
end

Swift Package Manager example:

// Add the product to the Widget Extension Target:
// GuanceWidgetExtension```

Objective-C import by integration method:

| Integration Method | Objective-C import |
| --- | --- |
| CocoaPods | `#import <GuanceSDK/GuanceWidgetExtension.h>` |
| Swift Package Manager | `@import GuanceWidgetExtension;` |
| Framework / XCFramework | `#import <GuanceWidgetExtension/GuanceWidgetExtension.h>` |
Swift Package Manager example:

```objc
@import GuanceWidgetExtension;

Framework / XCFramework example:

#import <GuanceWidgetExtension/GuanceWidgetExtension.h>

macOS Considerations¶

macOS has been merged into the main SDK and is currently in Alpha status. When migrating macOS projects:

• Do not integrate GuanceSessionReplay.
• Do not integrate GuanceWidgetExtension.
• Not all iOS features are guaranteed to be supported.
• For APIs marked with API_UNAVAILABLE(macos), remove the calls or isolate them with conditional compilation.

Example:

#if !TARGET_OS_OSX
rumConfig.viewTrackingHandler = handler;
#endif

Recommended Migration Steps¶

1. First update the dependency name: switch the CocoaPods / SPM / Framework product to GuanceSDK.
2. Update imports: for Objective-C, prefer the new entry headers; for Swift, use the corresponding product module's import entry.
3. Replace FTMobileConfig with FTSDKConfig in new code.
4. Replace samplerate with sampleRate.
5. Confirm separately if the iOS Target needs GuanceSessionReplay.
6. Confirm separately if the Widget Extension Target needs GuanceWidgetExtension.
7. For macOS Targets, check unavailable APIs and adjust code based on availability.

Compatibility Notes¶

To reduce migration costs, the following old entries are still compatible for now:

• FTMobileSDK.h
• FTMobileAgent.h
• FTMobileConfig
• samplerate
• FTSessionReplay.h

These compatibility entries may be removed in future major versions. New code is recommended to use the new integration products, entry headers, and standard naming.