Version: v4

Unity 集成（多平台）

本文介绍如何在 Unity 项目中快速接入 TapSDK 。

环境要求

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

编译工具链

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

GRADLE_VERSION: 6.1.1+
AGP_VERSION: 4.0.1+

SDK 获取

info

游戏 适用地区 在开启应用配置时选定。

TapTap 开发者中心适用地区为中国大陆。
出海游戏请前往 TapTap.io 开发者中心 开启游戏服务，适用地区为其他国家或地区。

集成 SDK 时，因 SDK 内部使用了第三方库，所以需同时添加 SDK 的外部依赖和添加 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.9.5",
}

但需要注意的是，需在 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/tapsdk-unity-dist.git?path=/Core#4.9.5",
}

说明：自 4.7.2 起，Unity Packages 仓库已统一为大仓 tapsdk-unity-dist，所有包通过目录区分并使用 ?path= 指定子目录、# 指定版本标签。例如 Core 模块：
"com.taptap.sdk.core": "https://github.com/taptap/tapsdk-unity-dist.git?path=/Core#4.7.2"

在 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>

初始化

新版 SDK 采用统一初始化机制，初始化时需设置 Client ID、clientToken、区域等应用配置信息，完成后即可直接使用所有业务模块（如登录、成就等），无需对各模块分别初始化。

using TapSDK.Core;

// 核心配置
TapTapSdkOptions coreOptions = new TapTapSdkOptions
{
   // 客户端 ID，开发者后台获取
   clientId = "clientId",
   // 客户端令牌，开发者后台获取
   clientToken = "clientToken",
   // 地区，CN 为国内，Overseas 为海外
   region = TapTapRegionType.CN,
   // 客户端 PC 平台公钥，开发者后台获取，仅接入 TapTap PC 客户端需要
   clientPublicKey = "pubKey",
   // 屏幕方向：0-竖屏 1-横屏，仅移动端生效
   screenOrientation = 1,
   // 是否开启日志，Release 版本请设置为 false
   enableLog = true
  
};
// TapSDK 初始化
TapTapSDK.Init(coreOptions);


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

初始化具体参数如下：

参数名	是否必填	说明
clientId	是	客户端 ID，开发者后台获取
clientToken	是	客户端令牌，开发者后台获取
clientPublicKey	否	客户端 PC 平台公钥，开发者后台获取，仅接入 TapTap PC 客户端需要
region	否	地区，默认国内
screenOrientation	否	屏幕方向：0-竖屏 1-横屏，仅移动端生效，默认为横屏
enableLog	否	是否开启日志，默认关闭，建议开发阶段开启，上线前关闭
preferredLanguage	否	语言，默认自动获取系统语言
gameVersion	否	应用版本号，默认读取应用的版本号

移动端工程配置

Android

生成 APK 文件前，需确保工程中有以下配置：

配置 package name 和签名文件：

检查 File > Build Settings > Player Settings > Other Settings > Target API Level 版本，当 API Level 小于 29 时，为兼容 SDK 内部默认配置的 requestLegacyExternalStorage 属性，需要在 AndroidManifest.xml 文件的 application 节点添加如下配置：

tools:remove="android:requestLegacyExternalStorage"

iOS

导出 XCode 工程前需配置 icon 和 BundleID：

常见问题

编译报错 mergeJavaResource task

如图：

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

运行时报错签名不匹配或 `signature not match`

检查 TapTap 开发者后台配置的应用包名和签名信息是否和当前工程设置一致

编译报错 `Android resource linking failed`

SDK 内部默认配置了 android:requestLegacyExternalStorage = true，当 targetSdkVersion < 29 时，游戏需要在 AndroidManifest.xml 文件的 application 节点添加如下配置：

tools:remove="android:requestLegacyExternalStorage"

环境要求​

编译工具链​

SDK 获取​

添加外部依赖​

添加 SDK 依赖​

远程依赖​

1. NPMJS 接入​

2. GitHub 接入​

本地文件导入​

初始化​

移动端工程配置​

Android​

iOS​

常见问题​

编译报错 mergeJavaResource task​

运行时报错签名不匹配或 signature not match​

编译报错 Android resource linking failed​