版本：v4

TapSDK 集成

本文介绍如何快速接入 TapSDK 。

环境要求

Unity
Android Java
Android Kotlin
iOS Swift
iOS Objective-C

Unity 2019.4 或更高版本，Target API Level 33 及以下
iOS 11 或更高版本，Xcode 版本 15.3 或更高版本
Android 5.0（API level 21）或更高版本

编译工具链

Unity & Android 一般通过 Gradle & AGP 进行构建，所以对于 Unity & Android 项目，需要确保 Gradle 和 AGP 的版本兼容，TapSDK 对 Gradle 和 AGP 的版本要求如下：

最低版本要求：

GRADLE_VERSION: 6.1.1+
AGP_VERSION: 4.0.1+

项目配置

Unity
Android Java
Android Kotlin
iOS Swift
iOS Objective-C

第一步：添加 SDK 所需的外部依赖

SDK 内部使用了部分第三方库，开发者接入时需先确保 SDK 外部依赖库已正常接入，具体设置如下：

SDK 使用的 JSON 解析库为 Newtonsoft-json，如果当前工程已接入该依赖库，则不需额外处理，否则需在 Packages/manifest.json 添加如下依赖：

"com.unity.nuget.newtonsoft-json":"3.2.1"

SDK 使用 com.google.external-dependency-manager 管理 Android、iOS 依赖，如果当前工程已接入该依赖库，则不需额外处理，否则需在 Packages/manifest.json 添加如下依赖：

{
   "dependencies": {
      "com.google.external-dependency-manager": "1.2.179"
   },
   "scopedRegistries": [
      {
         "name": "package.openupm.com",
         "url": "https://package.openupm.com",
         "scopes": [
            "com.google.external-dependency-manager"
         ]
      }
  ]
}

第二步：添加 SDK 依赖

SDK 支持 Unity Package Manager 及本地文件导入两种集成方式，开发者根据需求选择其中一种即可，推荐使用远程依赖。

远程依赖

SDK 支持通过 NPMJS 及 GitHub 两种方式，开发者选择其中一种即可。

1. NPMJS 接入

在项目的 Packages/manifest.json 文件中添加以下依赖：

"dependencies":{
  "com.taptap.sdk.core":"4.5.7",
}

但需要注意的是，需在 Packages/manifest.json 中 dependencies 同级下声明 scopedRegistries：

"scopedRegistries":[
  {
    "name": "NPMJS",
    "url": "https://registry.npmjs.org/",
    "scopes": ["com.taptap"]
  }
]

2. GitHub 接入

在项目的 Packages/manifest.json 文件中添加以下依赖：

"dependencies":{
 "com.taptap.sdk.core":"https://github.com/taptap/TapSDKCore-Unity.git#4.5.7", 
}

在 Unity 顶部菜单中选择 Window > Package Manager 可查看已经安装在项目中的包。

本地文件导入

在下载页下载下列模块对应 unitypackage 文件，并在 Unity 项目中依次通过 Assets > Import Packages > Custom Packages 进行导入，包括：

TapSDK_Core.unitypackage TapTapSDK 核心模块，必选。

如果当前项目已集成 Newtonsoft.Json 依赖，则忽略该步骤，否则在 NuGet.org Newtonsoft.Json 页面中通过点击右侧「Download package」下载库文件，并将下载的文件后缀从.nupkg 修改为 .zip，同时解压该文件并复制内部的 Newtonsoft.Json.dll 文件拷贝到工程 Assets 的 Plugins 目录下，另外为了避免导出 IL2CPP 平台时删除必要数据，需在 Assets 目录下创建 link.xml 文件（如果已有该文件，则添加如下内容），其内容如下：

<linker>
  <assembly fullname="System.Core">
    <type fullname="System.Linq.Expressions.Interpreter.LightLambda" preserve="all" />
  </assembly>
</linker>

项目根目录的 build.gradle 添加仓库地址：

allprojects {
  repositories {
      google()
      mavenCentral()
  }
}

app module 的 build.gradle 添加对应模块依赖（如：登录以及内嵌动态）：

dependencies {
  implementation 'com.taptap.sdk:tap-core:4.5.7'
}

在 AndroidManifest.xml 添加网络权限：

<uses-permission android:name="android.permission.INTERNET"></uses-permission>

旧版 Android 额外配置

如果 targetSdkVersion < 29，还需要添加如下配置：
- manifest 节点添加 xmlns:tools="http://schemas.android.com/tools"
- application 节点添加 tools:remove="android:requestLegacyExternalStorage"

项目根目录的 build.gradle 添加仓库地址：

allprojects {
  repositories {
      google()
      mavenCentral()
  }
}

app module 的 build.gradle 添加对应模块依赖（如：登录以及内嵌动态）：

dependencies {
  implementation 'com.taptap.sdk:tap-core:4.5.7'
}

在 AndroidManifest.xml 添加网络权限：

<uses-permission android:name="android.permission.INTERNET"></uses-permission>

旧版 Android 额外配置

如果 targetSdkVersion < 29，还需要添加如下配置：
- manifest 节点添加 xmlns:tools="http://schemas.android.com/tools"
- application 节点添加 tools:remove="android:requestLegacyExternalStorage"

iOS 提供通过添加 cocoaPods 远程依赖和使用本地文件导入两种集成方式，推荐使用远程依赖方式。

远程依赖

在工程 Podfile 文件中对应模块下添加依赖：

 pod 'TapTapCoreSDK', '~> 4.5.5'

执行 Pod install 下载对应依赖文件

本地文件依赖

在下载页下载如下文件：

tapsdkcorecpp.xcframework 基础库
TapTapBasicToolsSDK.xcframework 基础库
TapTapCoreSDK.xcframework 核心库
TapTapGidSDK.xcframework 基础库
TapTapNetworkSDK.xcframework 基础库
THEMISLite.xcframework 基础库

在工程中添加 framework 静态库，注意添加时选择 Embed 方式为 Do Not Embed

配置编译选项

在 Build Setting 中的 Other Link Flag 中添加 -ObjC 和 -Wl -ld_classic。
在 Build Setting 中的 Always Embed Swift Standard Libraries 设置为 YES，即始终引入 Swift 标准库，避免 App 启动时报错「无法找到 Swift 标准库之类」。如果项目中找不到，可以建立一个空 Swift 文件，Xcode 会自动建立桥接关系。
在 Build Setting 中的 Swift Compiler - Language/Swift Language Version 选择 Swift 5。

iOS 提供通过添加 cocoaPods 远程依赖和使用本地文件导入两种集成方式，推荐使用远程依赖方式。

远程依赖

在工程 Podfile 文件中对应模块下添加依赖：

 pod 'TapTapCoreSDK', '~> 4.5.5'

执行 Pod install 下载对应依赖文件

本地文件依赖

在下载页下载如下文件：

tapsdkcorecpp.xcframework 基础库
TapTapBasicToolsSDK.xcframework 基础库
TapTapCoreSDK.xcframework 核心库
TapTapGidSDK.xcframework 基础库
TapTapNetworkSDK.xcframework 基础库
THEMISLite.xcframework 基础库

在工程中添加 framework 静态库，注意添加时选择 Embed 方式为 Do Not Embed

配置编译选项

在 Build Setting 中的 Other Link Flag 中添加 -ObjC 和 -Wl -ld_classic。
在 Build Setting 中的 Always Embed Swift Standard Libraries 设置为 YES，即始终引入 Swift 标准库，避免 App 启动时报错「无法找到 Swift 标准库之类」。如果项目中找不到，可以建立一个空 Swift 文件，Xcode 会自动建立桥接关系。
在 Build Setting 中的 Swift Compiler - Language/Swift Language Version 选择 Swift 5。

初始化

初始化 TapSDK 时需传入 Client ID、区域等应用配置信息。

新版 TapSDK 提供统一初始化，业务模块（如：成就登录等）无需单独初始化。

Unity
Android Java
Android Kotlin
iOS Swift
iOS Objective-C

using TapSDK.Core;

// 核心配置
TapTapSdkOptions coreOptions = new TapTapSdkOptions
{
   // 客户端 ID，开发者后台获取
   clientId = clientId,
   // 客户端令牌，开发者后台获取
   clientToken = clientToken,
   // 地区，CN 为国内，Overseas 为海外
   region = TapTapRegionType.CN,
   // 语言，默认为 Auto，默认情况下，国内为 zh_Hans，海外为 en
   preferredLanguage = TapTapLanguageType.zh_Hans,
   // 是否开启日志，Release 版本请设置为 false
   enableLog = true
};
// TapSDK 初始化
TapTapSDK.Init(coreOptions);


// 当需要添加其他模块的初始化配置项，例如合规认证、成就等， 请使用如下 API
TapTapSdkBaseOptions[] otherOptions = new TapTapSdkBaseOptions[]
{
    // 其他模块配置项
};
TapTapSDK.Init(coreOptions, otherOptions);

请确保 TapSDK 的初始化在主线程（UI 线程）中执行。

import com.taptap.sdk.core.TapTapRegion;
import com.taptap.sdk.core.TapTapSdk;
import com.taptap.sdk.core.TapTapSdkOptions;

/* 必选配置 */
// 开发者中心对应 Client ID
String clientId = "";
// 开发者中心对应 Client Token
String clientToken = "";
// 是否开启 log，建议 Debug 开启，Release 关闭，默认关闭 log
boolean enableLog = BuildConfig.DEBUG;

TapTapSdkOptions tapSdkOptions = new TapTapSdkOptions(
       clientId, // 游戏 Client ID
       clientToken, // 游戏 Client Token
       TapTapRegion.CN // 游戏可玩区域: [TapTapRegion.CN]=国内 [TapTapRegion.GLOBAL]=海外
);
tapSdkOptions.setEnableLog(enableLog);
// 初始化 TapSDK
TapTapSdk.init(context, tapSdkOptions);

请确保 TapSDK 的初始化在主线程（UI 线程）中执行。

TapTapSdk.init(
    this,
    TapTapSdkOptions(
        clientId, // 游戏 Client ID
        clientToken, // 游戏 Client Token
        region, // 游戏可玩区域: [TapTapRegion.CN]=国内 [TapTapRegion.GLOBAL]=海外
        channel, // 分包渠道名称
        gameVersion, // 游戏版本号
        autoIAPEventEnabled, // 是否自动上报 GooglePlay 内购支付成功事件 仅 [TapTapRegion.GLOBAL] 生效
        overrideBuiltInParameters, // 自定义字段是否能覆盖内置字段
        properties, // 自定义属性，启动首个预置事件（device_login）会带上这些属性
        oaidCert, // OAID 证书, 用于上报 OAID 仅 [TapTapRegion.CN] 生效
        enableLog, // 是否开启 log，建议 Debug 开启，Release 关闭，默认关闭 log
        preferredLanguage, // TapSDK 首选语言 默认为 TapTapLanguage.AUTO
    ),
    TapTapAchievementOptions(enableToast = true), // 成就初始化配置
    TapTapComplianceOptions(showSwitchAccount = true, useAgeRange = true) // 合规认证初始化配置
)

import TapTapCoreSDK

let options = TapTapSdkOptions()
options.clientId = "your_client_id" // 必须，开发者中心对应 Client ID
options.clientToken = "your_client_token" // 必须，开发者中心对应 Client Token
options.region = .CN // .CN：中国大陆，.overseas：其他国家或地区
options.enableLog = true // 是否开启 log，建议 Debug 开启，Release 关闭，默认关闭 log
options.preferredLanguage = TapLanguageType.auto // 语言设置，默认跟随系统，当系统语言不支持时，国内为中文，海外为英文

// 初始化 SDK
TapTapSDK.initWith(options)


// 当需要添加其他模块的初始化配置项，例如合规认证、成就等，可调用如下 API
var otherOptions:[TapTapSdkBaseOptions] = []

// 添加其他模块初始化配置项
// otherOptions.append(moduleOptions) moduleOptions 为其他模块初始化配置项

// 初始化 SDK
TapTapSDK.initWith(options, otherOptions: otherOptions)

#import "TapTapCoreSDK/TapTapSDK.h"

// 核心配置项
TapTapSdkOptions *options = [[TapTapSdkOptions alloc] init];
options.clientId = @"your_clientId"; // 必须，开发者中心对应 Client ID
options.clientToken = @"your_client_token"; // 必须，开发者中心对应 Client Token
options.region = TapTapRegionTypeCN; // CN：中国大陆，overseas：其他国家或地区
options.enableLog = YES; // 是否开启 log，建议 Debug 开启，Release 关闭，默认关闭 log
options.preferredLanguage = TapLanguageType_Auto; // 语言设置，默认跟随系统，当系统语言不支持时，国内为中文，海外为英文

// 初始化 SDK
[TapTapSDK initWithOptions:options];

// 当需要添加其他模块的初始化配置项，例如合规认证、成就等，可调用如下 API
NSMutableArray *otherOptins = [[NSMutableArray alloc] init];

// 添加其他模块初始化配置项
[otherOptins addObject:moduleOptions]; // moduleOptions 为其他模块初始化配置项

// 初始化 SDK
[TapTapSDK initWithOptions:options otherOptions:otherOptins];

初始化的时候，必须填入 client_id 以及 client_token

client_id、client_token 信息可在 开发者中心 > 你的游戏 > 游戏服务 > 应用配置 查看。

接入功能

TapSDK 提供了众多功能。请在初始化 SDK 后，根据项目需要，参考相应功能的文档，接入相应功能。绝大多数游戏都会接入 TapTap 登录，所以我们推荐从这一功能开始。

配置签名证书

Android 和 iOS 应用需要在 TapTap 开发者中心进入你的游戏，依次选择 游戏服务 > 应用配置 > 签名证书配置 配置应用的相关信息（如下图所示），否则 Android 应用测试登录功能时会返回 signature not match 报错信息，iOS 会返回 sdk_not_matched 报错信息，无法正常使用 TapTap 登录功能。

Android 签名处填写 MD5 值，详情可参考：如何获取 MD5 值。

接下来，就可以打包应用，测试 TapTap 登录功能了。

Android 代码混淆

TapSDK 已经做了混淆处理，再次混淆会导致不可预期的错误，请在项目的混淆脚本中添加如下配置，跳过对 TapSDK 的混淆操作：

-keep class com.taptap.**{*;}

-keep class com.tapsdk.**{*;}

打包

Android 或 iOS 请按通常的 Android APK 或者 iOS 应用打包流程操作即可。这里介绍一下 Unity 打包流程：

打包 APK

第一步，配置 package name 和签名文件：

第二步，检查 File > Build Settings > Player Settings > Other Settings > Target API Level 版本，当 API Level 小于 29 时，需要配置 manifest，在 application 节点添加：

tools:remove="android:requestLegacyExternalStorage"

这是因为 SDK 内部默认配置了 android:requestLegacyExternalStorage = true，当 targetSdkVersion < 29 时会报错 Android resource linking failed。

导出 Xcode 工程

需要配置 icon 和 BundleID：

常见的编译报错

mergeJavaResource task 错误

如图：

这类编译错误通常是由于开发者使用的 AGP（com.android.tools.build:gradle:${agp_version}）版本过低，无法正确处理 Kotlin Multiplatform 构建生成的 AAR 中特有的文件。解决方案：将 Gradle 升级到 6.1.1 或更高版本，同时将 AGP 升级到 4.0.1 或更高版本。

环境要求​

编译工具链​

项目配置​

第一步：添加 SDK 所需的外部依赖​

第二步：添加 SDK 依赖​

远程依赖​

1. NPMJS 接入​

2. GitHub 接入​

本地文件导入​

初始化​

接入功能​

配置签名证书​

Android 代码混淆​

打包​

打包 APK​

导出 Xcode 工程​

常见的编译报错​

mergeJavaResource task 错误​