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 TrueWatchSDK, shared by iOS, tvOS, and macOS.

Overview of Changes¶

• The main SDK library is unified as TrueWatchSDK.
• datakit-macos is no longer maintained separately; macOS capabilities are merged into the current SDK repository.
• Session Replay is provided as a standalone product TrueWatchSessionReplay, supporting iOS only.
• Widget Extension is provided as a standalone product TrueWatchWidgetExtension, 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 'TrueWatchSDK'

For Session Replay:

pod 'TrueWatchSDK/SessionReplay'

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

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

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

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

Compatibility notes:

• TrueWatchSDK includes the main SDK capabilities by default.
• TrueWatchSDK/SessionReplay supports iOS only.
• TrueWatchSDK/WidgetExtension is for iOS Widget Extension Targets only.
• The old TrueWatchSDK/FTSessionReplay and TrueWatchSDK/Extension are kept as compatibility aliases. pod 'TrueWatchSDK', :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: TrueWatchSDK
• iOS Session Replay Target: TrueWatchSessionReplay
• Widget Extension Target: TrueWatchWidgetExtension

Swift import:

import TrueWatchSDK

For Session Replay:

import TrueWatchSessionReplay

Framework / XCFramework¶

Framework product names have been updated:

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

#import <TrueWatchSDK/TrueWatchSDK.h>

Compatibility entries are still available:

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

Session Replay recommended entry header by integration method:

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

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

// Swift Package Manager
@import TrueWatchSessionReplay;

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 TrueWatchSessionReplay;

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 'TrueWatchSDK/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 'TrueWatchSDK', :subspecs => ['Extension']
end

Swift Package Manager example:

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

Objective-C import by integration method:

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

```objc
@import TrueWatchWidgetExtension;

Framework / XCFramework example:

#import <TrueWatchWidgetExtension/TrueWatchWidgetExtension.h>

macOS Considerations¶

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

• Do not integrate TrueWatchSessionReplay.
• Do not integrate TrueWatchWidgetExtension.
• 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 TrueWatchSDK.
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 TrueWatchSessionReplay.
6. Confirm separately if the Widget Extension Target needs TrueWatchWidgetExtension.
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.