正版验证开发指南

集成前准备

1. 参考 开发者中心配置 创建应用、配置包名与签名证书
2. 参考集成指南（Unity、Android）完成对应平台或引擎的基础接入

PC 端接入

在 Windows 平台，开发者还需接入启动校验。同时，由于游戏购买状态和 DLC 功能依赖 TapTap PC 端处理，建议在启动校验成功后添加TapTap PC 端状态监听，并在状态异常时引导玩家检查网络或重新通过 TapTap PC 端启动游戏。

权限说明

Android

该模块需要访问设备中已安装的 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" />

SDK 获取

Unity

远程依赖

NPMJS 方式：在 Packages/manifest.json 中添加：

"dependencies":{
  "com.taptap.sdk.core":"4.10.5",
  "com.taptap.sdk.license":"4.10.5"
}

GitHub 方式：在 Packages/manifest.json 中添加：

"dependencies":{
  "com.taptap.sdk.core":"https://github.com/taptap/tapsdk-unity-dist.git?path=/Core#4.10.5",
  "com.taptap.sdk.license":"https://github.com/taptap/tapsdk-unity-dist.git?path=/License#4.10.5"
}

本地文件导入

在 下载页 下载并导入以下 unitypackage 文件：

• TapSDK_Core.unitypackage (TapTapSDK 核心模块，必选)
• TapSDK_License.unitypackage（TapTapSDK 正版验证模块，必选）

Android

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

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

正版验证

设置授权回调

在 PC 端，游戏需确保在启动校验成功后注册该回调。

Unity

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

// 注册回调
TapTapLicense.RegisterLicenseCallBack(ITapLicenseCallback callback);


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

    // 授权失败回调，仅当 PC 端用户完成退款时触发
    void OnLicenseFailed();
}

Android Java

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

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

Android Kotlin

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

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

在 Android 和 PC 端，该回调中各方法的触发时机和表现会有不同，具体如下：

回调方法	Android 端	PC 端
授权成功 OnLicenseSuccess	当开发者通过 SDK 检查玩家购买状态且结果为已购买时触发，每次检查触发一次	1. 当开发者通过 SDK 检查玩家购买状态且结果为已购买时触发，每次调用触发一次； 2. 当玩家在任意场景下重新完成购买时，SDK 主动触发一次
授权失败 OnLicenseFailed	不会触发 当开发者通过 SDK 检查玩家购买状态且结果为未购买时，SDK 会主动弹出无法取消的提示窗口来阻止玩家进入游戏	1. 当开发者通过 SDK 检查玩家购买状态且结果为未购买时触发，每次调用触发一次； 2. 当玩家在任意场景下完成退款时，SDK 主动触发一次

检查是否购买游戏

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

在 PC 端 Check 方法中参数无效，SDK 始终会通过 TapTap PC 端完成校验。

Unity

using TapSDK.License;

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

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

Android Java

import com.taptap.sdk.license.TapTapLicense;

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

Android Kotlin

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 会触发该问题）。

方案二：

1. 将 gradle build tools 改为 4.1.0+：

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

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

提示

请确保：

• DLC 商品已正确创建并审核通过，否则 DLC 查询和购买不会成功。DLC 商品配置事项详见 DLC 商品文档。
• 商店资料（路径：商店 - 游戏资料 - 商店资料）中填写 APK 包名并处于已上线状态。

设置查询和购买回调

DLC 回调包含查询回调和购买回调，在 PC 端，游戏需确保在启动校验成功后注册该回调。

Unity

using TapSDK.License;

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

    public void OnOrderCallBack(string sku, TapLicensePurchasedCode status)
    {
        // 购买回调
        // 在 Android 端当用户购买成功/失败时触发
        // 在 PC 端当用户在 TapTap PC 端完成商品购买或退款时触发
    }
}

TapTapLicense.RegisterDLCCallback(new MyTapDLCCallback());

Android Java

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) {
        // 购买回调
    }
});

Android Kotlin

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) {
        // 购买回调
    }

})

提示

Android 端：购买回调仅在主动调用购买商品接口时触发

PC 端：任何在 TapTap 客户端完成支付或退款操作均会触发购买回调，与是否调用购买商品接口无关。

回调参数说明

查询回调中参数 TapLicenseQueryCode 表示查询结果, 取值范围如下：

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

当查询成功时，参数 queryList 为键值对类型的具体数据，其中 key 为查询的商品 skuid，value 表示该商品的购买状态：0 表示未购买，1 表示已购买。

购买回调中参数 sku 为购买的商品 skuid，参数 TapLicensePurchaseCode 为购买结果，取值范围如下：

回调	回调值	说明
DLC_NOT_PURCHASED	0	未完成支付
DLC_PURCHASED	1	支付成功
DLC_RETURN_ERROR	-1	支付异常

查询购买状态

通过商品 skuId 数组批量查询多个商品购买状态，结果通过查询回调返回。

Unity

TapTapLicense.QueryDLC(string[] skuIds);

Android Java

import com.taptap.sdk.license.TapTapLicense;

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

Android Kotlin

import com.taptap.sdk.license.TapTapLicense

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

购买商品

提示

由于购买时 SDK 需获取商品的完整配置，开发者需确保已通过查询购买状态接口获得该商品的状态

通过商品 skuId 发起购买，结果通过购买回调返回。

Unity

TapTapLicense.PurchaseDLC(string skuId);

Android Java

import com.taptap.sdk.license.TapTapLicense;

TapTapLicense.purchaseDLC(activity, "skuId");

Android Kotlin

import com.taptap.sdk.license.TapTapLicense

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

skuId

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

如何测试

完成 SDK 接入后，买断制游戏白名单中的用户即可自测。详细自测流程参考接入与自测