iOS

环境要求

• 国内最低 iOS 11.0，海外最低 iOS 15.0。
• XCode 26 或更高版本。

接入方式

XDSDK iOS 原生接入支持 SPM 和 framework 压缩包两种方式，推荐优先使用 SPM 接入。

通过 SPM 集成

1. 在 Xcode 中打开项目，选择 File > Add Package Dependencies...。
2. 在搜索框中填入 XDSDK SPM 仓库地址：
   • 可以访问 GitHub 时使用：https://github.com/xindong/XDSDK-SPM
   • 无法稳定访问 GitHub 时使用国内托管地址：https://gitcode.com/XDSDK/XDSDK-SPM
3. 选择需要接入的版本，具体版本请以更新日志中的当前 XDSDK 版本为准。
4. 在 Add to Target 中选择游戏 App Target，并按需勾选需要的 Package Product。
5. 将 前文中的 XDConfig.json 文件 导入到 Xcode 工程中。
6. 在 App Target 中添加 SPM 提供的 Run Script Build Phases，用于复制 SDK 资源并根据 XDConfig.json 自动配置 Info.plist 参数。

SPM 仓库内置了脚本用于自动完成部分 Xcode 配置，请直接从 SPM checkout 目录调用脚本，不需要复制脚本到游戏工程。

复制资源

在 App Target > Build Phases 中添加 Run Script Phase，命名为 Copy XDSDK Resources，用于复制 SDK bundle 资源：

SCRIPT_PATH="${BUILD_DIR%/Build/*}/SourcePackages/checkouts/XDSDK-SPM/Scripts/copy_xdsdk_resources.sh"
if [[ -f "$SCRIPT_PATH" ]]; then
    bash "$SCRIPT_PATH"
else
    echo "warning: XDSDK SPM resource script not found at $SCRIPT_PATH"
fi

请将该 Phase 放在 Build Phases 末尾（位于 Embed Frameworks / [CP] Embed Pods Frameworks 之后），取消勾选 Based on dependency analysis，并在 Build Settings 中将 User Script Sandboxing（ENABLE_USER_SCRIPT_SANDBOXING）设置为 NO。

自动配置 Info.plist

添加 Run Script Phase，命名为 Configure XDSDK Info.plist，用于读取 XDConfig.json 并自动写入 CFBundleURLTypes、LSApplicationQueriesSchemes 以及 Facebook 所需的顶层字段：

SCRIPT_PATH="${BUILD_DIR%/Build/*}/SourcePackages/checkouts/XDSDK-SPM/Scripts/configure_xdsdk_info_plist.py"
if [[ -f "$SCRIPT_PATH" ]]; then
    /usr/bin/env python3 "$SCRIPT_PATH"
else
    echo "warning: XDSDK SPM info-plist script not found at $SCRIPT_PATH"
fi

请将该 Phase 放在 Compile Sources 之前，取消勾选 Based on dependency analysis，并将 User Script Sandboxing 设置为 NO。脚本默认从 ${SRCROOT}/${PRODUCT_NAME}/XDConfig.json 读取配置；如果配置文件放在其他路径，请在 Run Script 环境变量中设置 XDSDK_CONFIG_PATH=/absolute/path/XDConfig.json。

提示

使用 SPM 自动配置脚本后，如需调整脚本生成的配置，请修改 XDConfig.json，不要手动编辑对应的 Info.plist 字段。

备注

• GitHub 与 GitCode 托管的是同一套 XDSDK SPM 依赖，选择其中一个可稳定访问的地址即可。
• 如果使用 Google 登录或 Firebase 埋点，请在 Firebase 后台下载 GoogleService-Info.plist 并添加到项目中。

通过 Framework 集成

请联系平台同事获取最新的 SDK 压缩包，解压后选择需要的 framework 和 bundle 导入到您的 project 中。

1. 下载的压缩包解压后分为两部分 ThirdSDK 和 XDSDK，其中所有的 framework 均为动态库，导入后请设置为 Embed & Sign，具体说明如下：

必选项：
- XDAccountSDK.framework  登录
- XDPaymentSDK.framework  支付
- XDCommonSDK.framework   基础库
- XDTapSDK4WrapperSDK.framework  TapSDK 封装库
- TapTapMomentResource.bundle TapTap 资源包
- TapTapLoginResource.bundle TapTap 资源包
- TapTapComplianceResource.bundle TapTap 资源包
- TapTapAchievementResource.bundle TapTap 资源包

可选项：
XDCNWrapper.framework 国内三方 SDK ，按需添加
XDGlobalWrapper.framework 海外三方 SDK ，按需添加

2. 将 前文中的 XDConfig.json 文件 导入到 XCode 工程中。

备注

• 如果使用 Google 登录或 Firebase 埋点，请在 Firebase 后台下载 GoogleService-Info.plist 并添加到项目中。

Xcode 项目配置

添加系统依赖库

请检查项目中是否已自动添加以下依赖项：

LocalAuthentication.framework
AuthenticationServices.framework
SystemConfiguration.framework
Accelerate.framework
SafariServices.framework
Webkit.framework
CoreTelephony.framework
Security.framework
libc++.tdb
AVFoundation.framework
AdServices.framework

AdServices.framework -> 需要在 Build Phases - Link Binary With Libraries 中设置为 Optional 若运行时遇到相关依赖库加载报错，可改为 Optional 尝试（AuthenticationServices.framework iOS 12 以上才支持，请改为 Optional ）。

配置编译选项

在 Build Setting 中的 Other Link Flag 中添加 -ObjC。

配置 URL Types 与 Schemes

如果通过 SPM 接入且已添加 Configure XDSDK Info.plist 脚本，CFBundleURLTypes、LSApplicationQueriesSchemes 等字段会由脚本根据 XDConfig.json 自动写入，无需手动维护。

通过 Framework 接入或未使用脚本时，需要手动配置 URL Types（详细内容请咨询平台同事），并在应用的 info.plist 中配置以下 LSApplicationQueriesSchemes：

<key>LSApplicationQueriesSchemes</key>
<array>
	<string>sinaweibo</string>
	<string>weibosdk</string>
	<string>weibosdk2.5</string>
	<string>weibosdk3.3</string>
	<string>mqqopensdkapiV2</string>
	<string>mqq</string>
	<string>mqqapi</string>
	<string>tim</string>
	<string>mqqopensdknopasteboard</string>
	<string>weixin</string>
	<string>weixinULAPI</string>
	<string>weixinURLParamsAPI</string>
	<string>tapsdk</string>
	<string>tapiosdk</string>
	<string>fbapi</string>
	<string>fb-messenger-share-api</string>
	<string>lineauth2</string>
	<string>twitterauth</string>
	<string>xhsdiscover</string>
	<string>douyinopensdk</string>
	<string>douyinliteopensdk</string>
	<string>douyinsharesdk</string>
	<string>snssdk1128</string>
	<string>taptap</string>
	<string>tiktokopensdk</string>
	<string>tiktoksharesdk</string>
	<string>snssdk1180</string>
	<string>snssdk1233</string>
	<string>instagram</string>
	<string>kwai</string>
	<string>kwaiAuth2</string>
	<string>kwaiopenapi</string>
	<string>KwaiBundleToken</string>
	<string>kwai.clip.multi</string>
	<string>KwaiSDKMediaV2</string>
	<string>ksnebula</string>
</array>

配置权限列表

SDK 涉及到的权限请求如下：

权限说明	配置方式	备注
相机权限	在 info.plist 中配置 NSCameraUsageDescription 及描述文案。如：请允许 xxx 获取并使用您的相机。	客服页面可能需要拍摄相关照片或视频
麦克风权限	在 info.plist 中配置 NSMicrophoneUsageDescription 及描述文案。如：请允许 xxx 获取并使用您的麦克风。	客服页面可能需要拍摄相关视频
相册权限	在 info.plist 中配置 NSPhotoLibraryAddUsageDescription 及描述文案。如：请允许 xxx 获取并使用您的相册。	客服页面可能需要访问照片

配置 IDFA

如果您的应用需要打开 IDFA，则需要：

1. 在 XDConfig.json 中将 idfa_enabled 设置为 true。
2. 在应用中导入下列系统库：

   AdSupport.framework
   AppTrackingTransparency.framework -> 需要在 Build Phases - Link Binary With Libraries 中设置为 Optional

3. 在 info.plist 中配置 NSUserTrackingUsageDescription 及对应的文案。

做完上述配置后应用会在您调用初始化时自动尝试请求获取 IDFA 权限，此时会弹出系统的隐私权限请求弹窗。

配置 App 所需能力

如果您的 APP 具有苹果登录、微信分享、推送等功能，需要在项目的 Target 下，点击 + Capabilities 按钮，添加自己所需的功能，具体开启方式如下图：

AppDelegate 配置

在项目中实现了 UIApplicationDelegate 协议的类中引入头文件，并将系统回调转发给 SDK：

#import <XDCommonSDK/XDCommonSDK.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // ...其他初始化代码

    [XDGSDK application:application didFinishLaunchingWithOptions:launchOptions];
    return YES;
}

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [XDGSDK application:application didRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
}

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options {
    [XDGSDK application:app openURL:url options:options];
    return YES;
}

- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler {
    [XDGSDK application:application continueUserActivity:userActivity restorationHandler:restorationHandler];
    return YES;
}

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    [XDGSDK application:application didReceiveRemoteNotification:userInfo fetchCompletionHandler:completionHandler];
}

@end

提示

请确保在 didFinishLaunchingWithOptions 中尽早调用 [XDGSDK application:application didFinishLaunchingWithOptions:launchOptions]，其余回调方法也需要正确转发，否则可能影响登录、支付、推送等功能。