正版验证开发指南

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

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

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

付费下载

权限说明

Unity
Android
iOS
UE4

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

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

Unity
Android
iOS
UE4

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

方法一：使用 Unity Package Manager

从 3.29.1 版本开始， SDK 修改 JSON 解析库为 Newtonsoft-json，如果当前工程已接入该依赖库，则不需额外处理，否则需在 Packages/manifest.json 添加如下依赖：

"com.unity.nuget.newtonsoft-json":"3.2.1"

NPMJS 安装

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

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

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

但需要注意的是，要在 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.29.2",
    "com.taptap.tds.dlc":"https://github.com/TapTap/TapLicense-Unity.git#3.29.2", 
    }

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

方法二：手动导入

在下载页找到 TapSDK Unity 下载地址，下载 TapSDK-UnityPackage.zip 。
在 Unity 项目中依次转到 Assets > Import Packages > Custom Packages，从解压后的 TapSDK-UnityPackage.zip 中，选择希望在游戏中使用的 TapSDK 包导入，其中：
- 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>

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

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

// 暂不支持

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

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

测试模式设置

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

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

信息

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

Unity
Android
iOS
UE4

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

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

// 设置是否开启测试环境
TapLicenseHelper.setTestEnvironment(boolean isTest, Activity activity);

// 暂不支持

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

// 设置是否开启测试环境
FTapLicense::SetTestEnvironment(bool bIsTest);

设置授权回调

Unity
Android
iOS
UE4

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

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

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

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

// 暂不支持

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

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

检查是否购买游戏

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

Unity
Android
iOS
UE4

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

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

// 暂不支持

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

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
iOS
UE4

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

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

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

// 设置是否开启测试环境
TapLicenseHelper.setTestEnvironment(boolean isTest, Activity activity);

// 暂不支持

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

// 设置是否开启测试环境
FTapLicense::SetTestEnvironment(bool bIsTest);

DLC 查询和购买

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

Unity
Android
iOS
UE4

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

方法一：使用 Unity Package Manager

"com.unity.nuget.newtonsoft-json":"3.2.1"

NPMJS 安装

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

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

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

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

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

GitHub 安装

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

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

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

方法二：手动导入

在下载页找到 TapSDK Unity 下载地址，下载 TapSDK-UnityPackage.zip 。
在 Unity 项目中依次转到 Assets > Import Packages > Custom Packages，从解压后的 TapSDK-UnityPackage.zip 中，选择希望在游戏中使用的 TapSDK 包导入，其中：
- 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>

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

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

// 暂不支持

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

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

DLC 回调设置

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

Unity
Android
iOS
UE4

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

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

TapLicense.SetDLCCallback(new MyTapDLCCallback());

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

// 暂不支持

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有相应处理，正常不需要开发者做处理
                break;
            }
        }),
    FTapLicense::FDLCOrderDelegate::CreateLambda([](const FString& Sku, FTapLicense::EOrderStatus Status) {
        // 购买回调
    })
);

DLC 查询

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

Unity
Android
iOS
UE4

TapLicense.QueryDLC(string[] skuIds);

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

// 暂不支持

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

DLC 购买

Unity
Android
iOS
UE4

TapLicense.PurchaseDLC(string skuId);

TapLicenseHelper.purchaseDLC(Activity activity, String skuIds);

// 暂不支持

FTapLicense::PurchaseDLC(const FString& DLC);

参数说明

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 模块初始化后，调用 TapLicenseHelper.setTestEnvironment(boolean testEnvironment, Activity activity) 开启/关闭测试模式。

填写测试包名、测试用户

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

完成支付

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

提示

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

付费下载​

权限说明​

SDK 获取​

方法一：使用 Unity Package Manager​

NPMJS 安装​

GitHub 安装​

方法二：手动导入​

测试模式设置​

设置授权回调​

检查是否购买游戏​

Android 11 及更高版本的适配​

DLC​

权限说明​

测试模式设置​

DLC 查询和购买​

方法一：使用 Unity Package Manager​

NPMJS 安装​

GitHub 安装​

方法二：手动导入​

DLC 回调设置​

DLC 查询​

DLC 购买​

参数说明​

TapLicenseQueryCode​

skuId​

如何测试​

SDK 开启测试模式​

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

完成支付​

付费下载

权限说明

SDK 获取

方法一：使用 Unity Package Manager

NPMJS 安装

GitHub 安装

方法二：手动导入

测试模式设置

设置授权回调

检查是否购买游戏

Android 11 及更高版本的适配

DLC

权限说明

测试模式设置

DLC 查询和购买

方法一：使用 Unity Package Manager

NPMJS 安装

GitHub 安装

方法二：手动导入

DLC 回调设置

DLC 查询

DLC 购买

参数说明

TapLicenseQueryCode

skuId

如何测试

SDK 开启测试模式

填写测试包名、测试用户

完成支付