跳到主要内容
版本：v4

TapSDK 集成

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

环境要求​

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

项目配置​

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

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

  1. SDK 使用的 JSON 解析库为 Newtonsoft-json，如果当前工程已接入该依赖库，则不需额外处理，否则需在 Packages/manifest.json 添加如下依赖：
"com.unity.nuget.newtonsoft-json":"3.2.1"
  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.4",
}

但需要注意的是，需在 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.4", 
}

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

本地文件导入​

  1. 在 下载页 下载下列模块对应 unitypackage 文件，并在 Unity 项目中依次通过 Assets > Import Packages > Custom Packages 进行导入，包括：
  • TapSDK_Core.unitypackage TapTapSDK 核心模块，必选。
  1. 如果当前项目已集成 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>

初始化​

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

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

using TapSDK.Core;

// 核心配置
TapTapSdkOptions coreOptions = new TapTapSdkOptions
{
   // 客户端 ID，开发者后台获取
   clientId = clientId,
   // 客户端令牌，开发者后台获取
   clientToken = clientToken,
   // 地区，CN 为国内，Overseas 为海外
   region = TapTapRegionType.Overseas,
   // 语言，默认为 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);

初始化的时候，必须填入 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：

重打包​

META-INF/services 合并错误导致的初始化失败问题​

提示

TapSDK 初始化框架的实现依赖了 auto-service ， 通过 auto-service 生成 META-INF/services/xxx 文件（服务实现类），然后靠 Java 的 service loader 去加载

问题表象往往是初始化失败，但本质原因是游戏开发者重打包的时候，没有正确合并 META-INF 文件夹下的文件。

类型一：重打包的时候 exclude 了 META-INF/services/com.taptap.sdk.internal.service.ITapAutoService 文件​

这类问题居多，即开发者往往直接不处理 META-INF/services 下的所有文件（exclude），导致 SDK 初始化失败。

类型二：合并 META-INF/services/com.taptap.sdk.internal.service.ITapAutoService 错误​

即开发者意识到需要处理 META-INF/services 下的文件，但在合并的时候出现了错误，导致 SDK 初始化失败。 这类问题往往是因为开发者重打包的时候采取的是 override（覆盖）而非 merge（合并）策略， 即遇到多个 aar 里包含同名文件 META-INF/services/com.taptap.sdk.internal.service.ITapAutoService 时，只保留了一个，导致 SDK 初始化失败。

错误的合并，如图：

正确的合并，如图：