版本：v4

正版验证开发指南

正版验证适用于在 TapTap 上架的付费下载游戏。

游戏集成 TapSDK 的正版验证之后，当玩家第一次启动游戏时（包含卸载后再次安装），SDK 会前往 TapTap 查询玩家是否已购买游戏：

如已购买，则可正常进入游戏。
如查询到未购买，将出现「游戏未激活，请前往 TapTap 购买此游戏」弹窗，玩家必须选择「打开 TapTap」购买之后才能游玩。

SDK 获取

可以在下载页获得 TapSDK，添加以下依赖：

Unity
Android Java
Android Kotlin

接入外部依赖

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":{
    undefined
    "com.taptap.sdk.core":"4.5.0",
    "com.taptap.sdk.license":"4.5.0",
}

但需要注意的是，需在 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.0",
   "com.taptap.sdk.license":"https://github.com/taptap/TapSDKLicense-Unity.git#4.5.0", 
 }

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

本地文件导入

在下载页下载下列模块对应 unitypackage 文件，并在 Unity 项目中依次通过 Assets > Import Packages > Custom Packages 进行导入，包括：
- TapTap_Common.unitypackage TapSDK 基础库，必选。
- TapTap_License.unitypackage TapTap 正版验证库，必选。
如果当前项目已集成 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.0'
    implementation 'com.taptap.sdk:tap-license:4.5.0'
}

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

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

app module 的 build.gradle 添加对应依赖：

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

SDK 初始化

Unity
Android Java
Android Kotlin

TapTapSdkOptions 详细参数见入门指南#快速开始

using TapSDK.Core;

// 核心配置 详细参数见 [TapTapSDK]
TapTapSdkOptions coreOptions = new TapTapSdkOptions();
// TapSDK 初始化
TapTapSDK.Init(coreOptions);

TapTapSdkOptions 详细参数见入门指南#快速开始

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);

TapTapSdkOptions 详细参数见入门指南#快速开始

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

TapTapSdk.init(
  context = context,
  sdkOptions = TapTapSdkOptions(
      clientId = clientId,
      clientToken = clientToken,
      region = TapTapRegion.CN,
      preferredLanguage = TapTapLanguage.ZH_HANS,
      enableLog = false
  )
)

正版验证

权限说明

Unity
Android Java
Android Kotlin

该模块需要访问设备中已安装的 Tap 客户端信息，在 Android 11 且工程 targetVersion > 29 时需要开发者在应用 AndroidManifest.xml 中添加如下配置：

 <queries>
    <package android:name="com.taptap" />
    <package android:name="com.taptap.pad" />
    <package android:name="com.taptap.global" />
</queries>

该模块将在应用中添加如下权限：

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

该模块需要访问设备中已安装的 Tap 客户端信息，在 Android 11 且工程 targetVersion > 29 时需要开发者在应用 AndroidManifest.xml 中添加如下配置：

 <queries>
    <package android:name="com.taptap" />
    <package android:name="com.taptap.pad" />
    <package android:name="com.taptap.global" />
</queries>

该模块将在应用中添加如下权限：

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

测试模式设置

测试模式开启后，可以模拟线上正版验证流程，方便进行调试。

测试模式需要在 License 其他功能调用之前开启。

信息

切记在上线前关闭测试模式

Unity
Android Java
Android Kotlin

// 需要引入 `License` 库
using TapSDK.License;

// 设置是否开启测试环境
TapTapLicense.SetTestEnvironment(bool isTest);

import com.taptap.sdk.license.TapTapLicense;

// 设置是否开启测试环境
TapTapLicense.setTestEnvironment(activity, true);

import com.taptap.sdk.license.TapTapLicense

// 设置是否开启测试环境
TapTapLicense.setTestEnvironment(activity: Activity, true: Boolean)

设置授权回调

可注册多个回调，

Unity
Android Java
Android Kotlin

// 需要引入 `License` 库
using TapSDK.License;

// 默认情况下 SDK 会弹出不可由玩家手动取消的弹窗来避免未授权玩家进入游戏，如果需要回调来触发流程，请添加如下代码
TapTapLicense.RegisterLicenseCallBack(ITapLicenseCallback callback);


public interface ITapLicenseCallback
{
    // 授权成功回调
    void OnLicenseSuccess();
}

import com.taptap.sdk.license.TapTapLicense;
import com.taptap.sdk.license.TapTapLicenseCallback;

// 默认情况下 SDK 会弹出不可由玩家手动取消的弹窗来避免未授权玩家进入游戏，如果需要回调来触发流程，请添加如下代码
TapTapLicense.registerLicenseCallback(new TapTapLicenseCallback() {
    @Override
    public void onLicenseSuccess() {
        // 授权成功
    }
});

import com.taptap.sdk.license.TapTapLicense
import com.taptap.sdk.license.TapTapLicenseCallback

// 默认情况下 SDK 会弹出不可由玩家手动取消的弹窗来避免未授权玩家进入游戏，如果需要回调来触发流程，请添加如下代码
TapTapLicense.registerLicenseCallback(object : TapTapLicenseCallback {
    override fun onLicenseSuccess() {
        // your code
    }
})

检查是否购买游戏

Check 方法中参数默认值为 false，表示为 SDK 首次触发以及在距离首次触发的第 5 天之后再一次会通过 TapTap 客户端来确认当前登录用户是否购买游戏，如果使用 true 的话，则每次接口调用都会通过 TapTap 客户端来确认当前登录用户是否购买过游戏。

Unity
Android Java
Android Kotlin

using TapSDK.License;

// 普通检查
TapTapLicense.CheckLicense();

// 强制检查
TapTapLicense.CheckLicense(true);

import com.taptap.sdk.license.TapTapLicense;

// 普通检查
TapTapLicense.checkLicense(activity);
// 强制检查
TapTapLicense.checkLicense(activity, true);

import com.taptap.sdk.license.TapTapLicense

// forceCheck参数可不传，默认为false
TapTapLicense.checkLicense(activity: Activity, forceCheck: Boolean)

Android 11 及更高版本的适配

Android 11（API level 30）之后加强了隐私保护策略，引入了大量变更和限制，其中一个重要变更——软件包可见性，将会导致第三方应用无法拉起 TapTap 客户端，从而影响 TapTap 相关功能的正常使用，包括但不限于更新唤起 TapTap、购买验证等功能。

如果没有完成适配，Android 版本为 11 及更高版本的客户端打开游戏会提示「本游戏需要最新版 TapTap 服务支持」，无法正常进入游戏。异常呈现如下图所示：

图片描述

对此提供如下两种适配方案：

方案一：

编译时将 targetSdkVersion 改为 29（目前设置成 >= 30 会触发该问题）。

方案二：

将 gradle build tools 改为 4.1.0+：

classpath 'com.android.tools.build:gradle:4.1.0'

在 AndroidManifest.xml 里添加 <queries> 标签中的内容：

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
       package="string">
 
   <application
      . . .
   </application>

   <!--添加如下 queries 标签的内容，直接在 manifest 标签下-->
   <queries>
      <package android:name="com.taptap" />
      <package android:name="com.taptap.pad" />
      <package android:name="com.taptap.global" />
   </queries>
</manifest>

DLC

权限说明

Unity
Android Java
Android Kotlin

该模块需要访问设备中已安装的 Tap 客户端信息，在工程 targetVersion > 29 时需要开发者在应用 AndroidManifest.xml 中添加如下配置：

 <queries>
    <package android:name="com.taptap" />
    <package android:name="com.taptap.pad" />
    <package android:name="com.taptap.global" />
</queries>

该模块需要访问设备中已安装的 Tap 客户端信息，在工程 targetVersion > 29 时需要开发者在应用 AndroidManifest.xml 中添加如下配置：

 <queries>
    <package android:name="com.taptap" />
    <package android:name="com.taptap.pad" />
    <package android:name="com.taptap.global" />
</queries>

测试模式设置

测试模式开启后，可以模拟线上 DLC 的查询与购买，方便进行调试。

测试模式需要在 License 其他功能调用之前开启。

信息

切记在上线前关闭测试模式

Unity
Android Java
Android Kotlin

// 需要引入 `License` 库
using TapSDK.License;

// 设置是否开启测试环境
TapTapLicense.SetTestEnvironment(isTest);

import com.taptap.sdk.license.TapTapLicense;
// 设置是否开启测试环境
TapTapLicense.setTestEnvironment(activity, true);

// 设置是否开启测试环境
TapTapLicense.setTestEnvironment(activity: Activity, true: Boolean)

DLC 查询和购买

可以在下载页获得 TapSDK，添加以下依赖：

Unity
Android Java
Android Kotlin

接入外部依赖

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":{
    undefined
    "com.taptap.sdk.license":"4.5.0",
    "com.taptap.sdk.core":"4.5.0",
}

但需要注意的是，需在 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.0",
   "com.taptap.sdk.license":"https://github.com/taptap/TapSDKLicense-Unity.git#4.5.0", 
 }

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

本地文件导入

在下载页下载下列模块对应 unitypackage 文件，并在 Unity 项目中依次通过 Assets > Import Packages > Custom Packages 进行导入，包括：
- TapTap_Common.unitypackage TapSDK 基础库，必选。
- TapTap_License.unitypackage TapTap 正版验证库，必选。
如果当前项目已集成 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>

app module 的 build.gradle 添加对应依赖：

dependencies {
    implementation 'com.taptap.sdk:tap-core:latest.release
    implementation 'com.taptap.sdk:tap-license:latest.release
}

app module 的 build.gradle 添加对应依赖：

dependencies {
    implementation 'com.taptap.sdk:tap-core:latest.release
    implementation 'com.taptap.sdk:tap-license:latest.release
}

DLC 回调设置

DLC 回调包含查询回调和购买回调。

Unity
Android Java
Android Kotlin

using TapSDK.License;

public class MyTapDLCCallback:ITapDlcCallback
{
    public void OnQueryCallBack(TapLicenseQueryCode code, Dictionary<string, object> queryList)
    {
        // 查询回调
    }

    public void OnOrderCallBack(string sku, TapLicensePurchasedCode status)
    {
        // 购买回调
    }
}

TapTapLicense.RegisterDLCCallback(new MyTapDLCCallback());

import com.taptap.sdk.license.TapTapDLCCallback;
import com.taptap.sdk.license.TapTapLicense;

TapTapLicense.registerDLCCallback(new TapTapDLCCallback() {
    @Override
    public void onQueryResult(int resultCode, @Nullable HashMap<String, Integer> resultList) {
        // 查询回调
    }

    @Override
    public void onPurchaseResult(@NonNull String skuId, int status) {
        // 购买回调
    }
});

import com.taptap.sdk.license.TapTapLicense
import com.taptap.sdk.license.TapTapDLCCallback

TapTapLicense.registerDLCCallback(object : TapTapDLCCallback {
    override fun onQueryResult(resultCode: Int, resultList: HashMap<String, Int>?) {
        // 查询回调
    }

    override fun onPurchaseResult(skuId: String, status: Int) {
        // 购买回调
    }

})

DLC 查询

对应的查询回调会返回具体的查询结果，查询成功时会返回当前 Tap 玩家是否已经购买过对应商品，在查询回调中返回的键值对类型参数 skuIds 中可以获取，该参数 key 为查询的商品 skuid，value 表示该商品当前查询用户的购买状态：0 表示未购买，1 表示已购买。

Unity
Android Java
Android Kotlin

TapTapLicense.QueryDLC(string[] skuIds);

import com.taptap.sdk.license.TapTapLicense;

List<String> skuList = new ArrayList<>();
skuList.add("skuId1");
skuList.add("skuId2");
TapTapLicense.queryDLC(activity, skuList);

import com.taptap.sdk.license.TapTapLicense

TapTapLicense.queryDLC(activity: Activity, skuIds: List<String>)

DLC 购买

Unity
Android Java
Android Kotlin

TapTapLicense.PurchaseDLC(string skuId);

import com.taptap.sdk.license.TapTapLicense;

TapTapLicense.purchaseDLC(activity, "skuId");

import com.taptap.sdk.license.TapTapLicense

TapTapLicense.purchaseDLC(activity: Activity, skuId: String)

参数说明

TapLicenseQueryCode

回调	回调值	说明
QUERY_RESULT_OK	0	查询成功
QUERY_RESULT_NOT_INSTALL_TAPTAP	1	检查测试机未安装 TapTap 客户端
QUERY_RESULT_ERR	2	查询失败
ERROR_CODE_UNDEFINED	80000	未知错误

skuId

请前往 DLC 商品查看如何创建 DLC 商品并获得 skuid。

如何测试

SDK 开启测试模式

在 License 模块初始化后，调用 TapTapLicense.setTestEnvironment(activity:Activity, true:Boolean) 开启/关闭测试模式。

填写测试包名、测试用户

在开发者中心 > 游戏服务 > 正版验证添加测试包名，同时将测试用户的 TapTap ID 加入测试白名单。

完成支付

加入测试白名单的用户将正常拉起 TapTap 的支付功能，请正常操作完成购买。

提示

测试用户所使用的 TapTap 请确保是最新正式版本。
测试环境的购买仅为了模拟正式环境的购买流程，并不会产生真正的付款订单。
单个测试用户在测试环境下仅可完成 1 次订单支付。如需重复测试，请从白名单中移除此测试账号后再加入。
在正式上线前，请关闭测试环境。

SDK 获取​

接入外部依赖​

添加 SDK 依赖​

远程依赖​

1. NPMJS 接入​

2. GitHub 接入​

本地文件导入​

SDK 初始化​

正版验证​

权限说明​

测试模式设置​

设置授权回调​

检查是否购买游戏​

Android 11 及更高版本的适配​

DLC​

权限说明​

测试模式设置​

DLC 查询和购买​

接入外部依赖​

添加 SDK 依赖​

远程依赖​

1. NPMJS 接入​

2. GitHub 接入​

本地文件导入​

DLC 回调设置​

DLC 查询​

DLC 购买​

参数说明​

TapLicenseQueryCode​

skuId​

如何测试​

SDK 开启测试模式​

填写测试包名、测试用户​

完成支付​

SDK 获取

接入外部依赖

添加 SDK 依赖

远程依赖

1. NPMJS 接入

2. GitHub 接入

本地文件导入

SDK 初始化

正版验证

权限说明

测试模式设置

设置授权回调

检查是否购买游戏

Android 11 及更高版本的适配

DLC

权限说明

测试模式设置

DLC 查询和购买

接入外部依赖

添加 SDK 依赖

远程依赖

1. NPMJS 接入

2. GitHub 接入

本地文件导入

DLC 回调设置

DLC 查询

DLC 购买

参数说明

TapLicenseQueryCode

skuId

如何测试

SDK 开启测试模式

填写测试包名、测试用户

完成支付