正版验证开发指南

tip

从 TapSDK 3.30.0 版本开始支持使用 TapTap PC 端完成正版验证和使用 DLC 功能，使用前需接入启动校验，具体参考 TapTap PC 端集成 文档

正版验证适用于在 TapTap 上架的付费下载游戏。 游戏集成 TapSDK 的正版验证之后，当玩家启动游戏时（包含卸载后再次安装），SDK 会前往 TapTap 查询玩家是否已购买游戏：

• 如已购买，则可正常进入游戏。
• 如查询到未购买，在 Android 端将出现「游戏未激活，请前往 TapTap 购买此游戏」弹窗，玩家必须选择「打开 TapTap」购买之后才能游玩；在 PC 端调用启动校验时会返回失败

权限说明

Unity

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" />

iOS

UE4

SDK 获取

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

Unity

SDK 可以通过 Unity Package Manager 导入或手动导入，二者任选其一。请根据项目需要选择。

方法一：使用 Unity Package Manager

NPMJS 安装

从 3.25.0 版本开始，TapSDK 支持了 NPMJS 安装，优势是只需要配置版本号，并且支持嵌套依赖。

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

"dependencies":{
  "com.taptap.tds.dlc":"3.30.1",
    "com.taptap.tds.common":"3.30.1",
}

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

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

GitHub 安装

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

"dependencies":{
  "com.taptap.tds.common":"https://github.com/TapTap/TapCommon-Unity.git#3.30.1",
    "com.taptap.tds.dlc":"https://github.com/TapTap/TapLicense-Unity.git#3.30.1",
    "com.leancloud.storage":"https://github.com/leancloud/csharp-sdk-upm.git#storage-2.3.0", 
}

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

方法二：手动导入

1. 在 下载页 找到 TapSDK Unity 下载地址，下载 TapSDK-UnityPackage.zip 。

2. 在 Unity 项目中依次转到 Assets > Import Packages > Custom Packages，从解压后的 TapSDK-UnityPackage.zip 中，选择希望在游戏中使用的 TapSDK 包导入，其中：

• TapTap_Common.unitypackage TapSDK 基础库，必选。
• TapTap_License.unitypackage TapTap 正版验证库，必选。

3. 从 LeanCloud-SDK 下载页 中下载并解压 LeanCloud-SDK-Storage-Unity.zip，然后将 Plugins 文件夹拖拽至 Unity 即可。

Android

将 SDK 包导入到项目 project/app/libs 目录下。打开项目的 project/app/build.gradle 文件，添加：

repositories{
  flatDir {  
      dirs 'libs'  
  }  
}  
dependencies {
  implementation name:'TapCommon_3.30.1', ext:'aar'
  implementation name:'TapLicense_3.30.1', ext:'aar'
}

iOS

// 暂不支持

UE4

将插件 ** TapLicense ** 、** TapCommon ** 拷贝到项目的插件目录，并在项目模块的 ** build.cs ** 文件中添加依赖：

PublicDependencyModuleNames.AddRange(new string[] { 
    "Json",
    "JsonUtilities",
    "SlateCore",           
    "TapCommon",
    "TapLicense",
});

付费下载

设置授权回调

Unity

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

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

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

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

Android

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

iOS

// 暂不支持

UE4

// 需要引入 `License` 库
#include "TapLicense.h"

// 默认情况下 SDK 会弹出不可由玩家手动取消的弹窗来避免未授权玩家进入游戏，如果需要回调来触发流程，请添加如下代码
FTapLicense::SetLicenseCallback(FSimpleDelegate::CreateLambda([]() {
    // 本体授权成功
}), FSimpleDelegate::CreateLambda([]()
{
    // 本体授权失败, 仅当 PC 端用户完成退款时触发
}));

检查是否购买游戏

Unity

TapLicense.Check();
TapLicense.Check(true);

Android

TapLicenseHelper.check(Activity activity);
TapLicenseHelper.check(Activity activity, boolean forceCheck);

iOS

// 暂不支持

UE4

FTapLicense::Check();
FTapLicense::Check(true);

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

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

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 回调包含查询回调和购买回调，设置方式如下：

Unity

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

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

TapLicense.SetDLCCallback(new MyTapDLCCallback());

Android

TapLicenseHelper.setDLCCallback(new DLCManager.InventoryCallback() {
    @Override
    public boolean onQueryCallBack(int i, HashMap<String, Integer> queryList) {
        // 查询回调
        return false;
    }

    @Override
    public void onOrderCallBack(String s, int i) {
        // 购买回调
    }
});

iOS

// 暂不支持

UE4

FTapLicense::SetDLCCallback(
    FTapLicense::FDLCQueryDelegate::CreateLambda(
        [](FTapLicense::EQueryResult Code, const FTapLicense::Map& QueryList) {
            // 查询回调
            switch (Code) {
            case FTapLicense::EQueryResult::OK: 
                //查询成功
                break;
            case FTapLicense::EQueryResult::Error:
                //查询失败
                break;
            case FTapLicense::EQueryResult::NotInstallTapTap:
                //sdk有相应处理，正常不需要开发者做处理，仅在 Android 端触发
                break;
            }
        }),
    FTapLicense::FDLCOrderDelegate::CreateLambda([](const FString& Sku, FTapLicense::EOrderStatus Status) {
        // 购买回调
        // 在 Android 端当用户购买成功/失败时触发
        // 在 PC 端当用户在 TapTap PC 端完成商品购买或退款时触发，与是否调用购买接口无关
    })
);

tip

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

TapLicense.QueryDLC(string[] skuIds);

Android

TapLicenseHelper.queryDLC(Activity activity, String[] skuIds);

iOS

// 暂不支持

UE4

FTapLicense::QueryDLC(const TArray<FString>& DLCList);

购买商品

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

Unity

TapLicense.PurchaseDLC(string skuId);

Android

TapLicenseHelper.purchaseDLC(Activity activity, String skuIds);

iOS

// 暂不支持

UE4

FTapLicense::PurchaseDLC(const FString& DLC);

skuId

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

如何测试

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