跳到主要内容
版本:v3

正版验证开发指南

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

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

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

付费下载

权限说明

SDK 获取

可以在 下载页 获得 TapSDK,添加以下依赖:

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.4",
"com.taptap.tds.common":"3.29.4",
}

但需要注意的是,要在 Packages/manifest.jsondependencies 同级下声明 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.4",
"com.taptap.tds.dlc":"https://github.com/TapTap/TapLicense-Unity.git#3.29.4",
}

在 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. 如果当前项目已集成 Newtonsoft.Json 依赖,则忽略该步骤,否则在 NuGet.org Newtonsoft.Json 页面中通过点击右侧 「Download package」 下载库文件,并将下载的文件后缀从.nupkg 修改为 .zip,同时解压该文件并复制内部的 Newtonsoft.Json.dll 文件拷贝到工程 AssetsPlugins 目录下,另外为了避免导出 IL2CPP 平台时删除必要数据,需在 Assets 目录下创建 link.xml 文件(如果已有该文件,则添加如下内容),其内容如下:

<linker>
<assembly fullname="System.Core">
<type fullname="System.Linq.Expressions.Interpreter.LightLambda" preserve="all" />
</assembly>
</linker>

测试模式设置

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

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

信息

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

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

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

设置授权回调

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

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

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

检查是否购买游戏

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

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

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 的查询与购买,方便进行调试。

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

信息

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

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

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

DLC 查询和购买

可以在 下载页 获得 TapSDK,添加以下依赖:

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.4",
"com.taptap.tds.common":"3.29.4",
}

但需要注意的是,要在 Packages/manifest.jsondependencies 同级下声明 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.4",
"com.taptap.tds.dlc":"https://github.com/TapTap/TapLicense-Unity.git#3.29.4",
"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. 如果当前项目已集成 Newtonsoft.Json 依赖,则忽略该步骤,否则在 NuGet.org Newtonsoft.Json 页面中通过点击右侧 「Download package」 下载库文件,并将下载的文件后缀从.nupkg 修改为 .zip,同时解压该文件并复制内部的 Newtonsoft.Json.dll 文件拷贝到工程 AssetsPlugins 目录下,另外为了避免导出 IL2CPP 平台时删除必要数据,需在 Assets 目录下创建 link.xml 文件(如果已有该文件,则添加如下内容),其内容如下:

<linker>
<assembly fullname="System.Core">
<type fullname="System.Linq.Expressions.Interpreter.LightLambda" preserve="all" />
</assembly>
</linker>

DLC 回调设置

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

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

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

TapLicense.SetDLCCallback(new MyTapDLCCallback());

DLC 查询

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

TapLicense.QueryDLC(string[] skuIds);

DLC 购买

TapLicense.PurchaseDLC(string skuId);

参数说明

TapLicenseQueryCode
回调回调值说明
QUERY_RESULT_OK0查询成功
QUERY_RESULT_NOT_INSTALL_TAPTAP1检查测试机未安装 TapTap 客户端
QUERY_RESULT_ERR2查询失败
ERROR_CODE_UNDEFINED80000未知错误
skuId
请前往 DLC 商品查看如何创建 DLC 商品并获得 skuid。

如何测试

SDK 开启测试模式

在 License 模块初始化后,调用 TapLicenseHelper.setTestEnvironment(boolean testEnvironment, Activity activity) 开启/关闭测试模式。

填写测试包名、测试用户

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

完成支付

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

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