iOS/tvOS/macOS 1.6.6 迁移指南¶

本文适用于从旧版 iOS SDK / macOS SDK 迁移到 SDK 1.6.6 及以上版本的项目。1.6.6 起，Apple 平台主 SDK 统一为 GuanceSDK，iOS、tvOS、macOS 共用同一主 SDK。

变更概览¶

• 主 SDK 库统一为 GuanceSDK。
• datakit-macos 不再单独维护，macOS 能力合并到当前 SDK 仓库。
• Session Replay 作为独立产品 GuanceSessionReplay 提供，仅支持 iOS。
• Widget Extension 作为独立产品 GuanceWidgetExtension 提供，仅用于 iOS Widget Extension Target。
• iOS、tvOS、macOS 共用主 SDK；不支持某个平台的 API 会通过可用性标记声明。

最低系统版本由发布包配置定义：

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

安装迁移¶

CocoaPods¶

旧版主 SDK：

pod 'FTMobileSDK'

迁移为：

pod 'GuanceSDK'

如需 Session Replay：

pod 'GuanceSDK/SessionReplay'

如需 Widget Extension 数据采集，仅在 Widget Extension Target 中集成。新接入推荐使用 WidgetExtension subspec：

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

如果旧项目原来使用 pod 'FTMobileSDK', :subspecs => ['Extension']，升级到 GuanceSDK 后也可以继续使用兼容 subspec：

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

兼容说明：

• GuanceSDK 默认包含主 SDK 能力。
• GuanceSDK/SessionReplay 仅支持 iOS。
• GuanceSDK/WidgetExtension 仅用于 iOS Widget Extension Target。
• 旧的 GuanceSDK/FTSessionReplay、GuanceSDK/Extension 作为兼容别名保留；pod 'GuanceSDK', :subspecs => ['Extension'] 也可以继续集成 Widget Extension 能力。新接入建议使用 SessionReplay 与 WidgetExtension。
• macOS Target 不要集成 SessionReplay 或 WidgetExtension subspec。

Swift Package Manager¶

SPM 产品名已调整为新的品牌产品名：

在 Xcode 添加 Swift Package 后，根据 Target 选择对应产品：

• App Target：GuanceSDK
• iOS Session Replay 所在 Target：GuanceSessionReplay
• Widget Extension Target：GuanceWidgetExtension

Swift import：

import GuanceSDK

如需 Session Replay：

import GuanceSessionReplay

Framework / XCFramework¶

Framework 产品名已调整：

Objective-C 推荐使用新的入口头文件：

#import <GuanceSDK/GuanceSDK.h>

兼容入口仍可使用：

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

Session Replay 推荐入口按集成方式选择：

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

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

// Swift Package Manager
@import GuanceSessionReplay;

API 迁移¶

初始化配置¶

新代码建议从 FTMobileConfig 迁移到 FTSDKConfig。

旧写法：

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

新写法：

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

说明：

• FTMobileConfig 当前仍可使用，并继承自 FTSDKConfig。
• FTMobileConfig 已废弃，新代码建议使用 FTSDKConfig。
• FTMobileAgent 仍可继续作为启动入口；新代码也可以使用兼容别名 FTSDKAgent。

采样率参数命名¶

samplerate 已调整为标准驼峰命名 sampleRate。

受影响配置：

• FTRumConfig
• FTTraceConfig
• FTLoggerConfig

旧写法：

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;

新写法：

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;

说明：

• samplerate 当前仍可使用，但已废弃。
• sampleRate 与 samplerate 映射到同一个值。
• SDK 1.6.6 以下版本请继续使用 samplerate。

Session Replay¶

Session Replay 相关公共类型仍使用 FT 前缀，例如：

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

旧写法可能因集成方式不同而使用不同路径：

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

新写法按集成方式选择入口头文件：

@import GuanceSessionReplay;

Widget Extension¶

Widget Extension 组件应只在 Widget Extension Target 中单独集成。

CocoaPods 示例。新接入推荐使用 WidgetExtension subspec：

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

旧项目升级时，如果原来使用 pod 'FTMobileSDK', :subspecs => ['Extension']，也可以继续保留 subspec 形式：

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

Swift Package Manager 示例：

// 将产品添加到 Widget Extension Target：
// GuanceWidgetExtension```

Objective-C import 按集成方式选择：

| 集成方式 | Objective-C import |
| --- | --- |
| CocoaPods | `#import <GuanceSDK/GuanceWidgetExtension.h>` |
| Swift Package Manager | `@import GuanceWidgetExtension;` |
| Framework / XCFramework | `#import <GuanceWidgetExtension/GuanceWidgetExtension.h>` |
Swift Package Manager 示例：

```objc
@import GuanceWidgetExtension;

Framework / XCFramework 示例：

#import <GuanceWidgetExtension/GuanceWidgetExtension.h>

macOS 注意事项¶

macOS 已合并到主 SDK，当前为 Alpha 版本。迁移 macOS 项目时：

• 不要集成 GuanceSessionReplay。
• 不要集成 GuanceWidgetExtension。
• 不承诺所有 iOS 功能都支持。
• 对标记为 API_UNAVAILABLE(macos) 的 API，应移除调用或通过条件编译隔离。

示例：

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

推荐迁移步骤¶

1. 先更新依赖名称：将 CocoaPods / SPM / Framework 产品切换到 GuanceSDK。
2. 更新 import：Objective-C 优先使用新的入口头文件，Swift 使用对应产品模块的 import 入口。
3. 新代码将 FTMobileConfig 替换为 FTSDKConfig。
4. 将 samplerate 替换为 sampleRate。
5. 单独确认 iOS Target 是否需要 GuanceSessionReplay。
6. 单独确认 Widget Extension Target 是否需要 GuanceWidgetExtension。
7. macOS Target 检查不可用 API，并根据可用性调整代码。

兼容说明¶

为降低迁移成本，以下旧入口当前仍可兼容使用：

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

这些兼容入口可能会在未来大版本中移除。新代码建议使用新的集成产品、入口头文件与标准命名。