Skip to main content
Version: v4

开发指南

权限说明​

准备集成 SDK​

  1. 参考 准备工作 创建应用、开启应用配置；
  2. 参考 快速开始 配置包名与签名证书；

SDK 获取​

第一步：添加 SDK 所需的外部依赖​

SDK 内部使用了部分第三方库，开发者接入时需先确保 SDK 外部依赖库已正常接入，具体设置如下：

  1. SDK 使用的 JSON 解析库为 Newtonsoft-json，如果当前工程已接入该依赖库，则不需额外处理，否则需在 Packages/manifest.json 添加如下依赖：
"com.unity.nuget.newtonsoft-json":"3.2.1"
  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":{
   "com.taptap.sdk.core":"4.8.2",
   "com.taptap.sdk.login":"4.8.2",
}

但需要注意的是，需在 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/tapsdk-unity-dist.git?path=/Core#4.8.2",
   "com.taptap.sdk.login":"https://github.com/taptap/tapsdk-unity-dist.git?path=/Login#4.8.2",
}

说明：自 4.7.2 起，Unity Packages 仓库已统一为大仓 tapsdk-unity-dist，所有包通过目录区分并使用 ?path= 指定子目录、# 指定版本标签。例如 Core 模块：

"com.taptap.sdk.core": "https://github.com/taptap/tapsdk-unity-dist.git?path=/Core#4.7.2"

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

本地文件导入​

  1. 在 下载页 下载下列模块对应 unitypackage 文件，并在 Unity 项目中依次通过 Assets > Import Packages > Custom Packages 进行导入，包括：
  • TapSDK_Core.unitypackage TapTapSDK 核心模块，必选。
  • TapSDK_Login.unitypackage TapTapSDK 登录模块，必选。
  1. 如果当前项目已集成 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>

iOS 配置​

在 Assets/Plugins/iOS/Resource 目录下创建 TDS-Info.plist 文件，复制以下代码并且替换其中的 ClientId。

tip

复制使用以下内容时，请删除空行以及注释，以免出现 XML 解析时报错，ApplicationException: expected a key node。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>taptap</key>
    <dict>
        <key>client_id</key>
        <string>ClientId</string>
    </dict>
</dict>
</plist>

SDK 初始化​

info

游戏 适用地区 在开启应用配置时选定。

TapTap 登录模块依赖于 TapTapSDK 初始化，具体参考 TapSDK 集成

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

登录​

tip

当用户启动游戏时，可以先检查用户登录状态，如果玩家已经登录，则不显示登录按钮，让玩家直接进入游戏。

using TapSDK.Login;
using System.Threading.Tasks;

try
{
    // 定义授权范围
    List<string> scopes = new List<string>
    {
        TapTapLogin.TAP_LOGIN_SCOPE_PUBLIC_PROFILE
    };
    // 发起 Tap 登录
    var userInfo = await TapTapLogin.Instance.LoginWithScopes(scopes.ToArray());
    Debug.Log($"登录成功，当前用户 ID：{userInfo.unionId}");
}
catch (TaskCanceledException)
{
    Debug.Log("用户取消登录");
}
catch (Exception exception)
{
    Debug.Log($"登录失败，出现异常：{exception}");
}

不同的授权范围​

TapTap 授权登录接口支持选择不同的授权范围且支持任意组合，但必须包含 public_profile 和 basic_info 中的一个，不然无法获得 openId 和 unionId。TapTap 授权登录接口可以传递 String 类型的数组作为参数，开发者可以根据自己业务需求添加不同的权限为数组的元素。

权限说明
public_profile获得 openId、unionId、用户昵称、用户头像
user_friends获得访问 TapTap 好友相关数据的权限
basic_info获得 openId 和 unionId
tip

若游戏发起 TapTap 授权登录时只请求 basic_info 的权限，则用户可享受无感登录的特性，即用户不需要手动确认授权即可自动授权完成登录。

获取用户信息​

TapTap 用户登录成功之后，开发者可以通过如下方式获取到 TapTap 授权结果的详细信息：

using TapSDK.Login;
using System.Threading.Tasks;

TapTapAccount taptapAccount = await TapTapLogin.Instance.GetCurrentTapAccount();
AccessToken accessToken = taptapAccount.accessToken;
string openId = taptapAccount.openId;

其中 taptapAccount 可能会包含如下信息：

参数说明
accessToken玩家在 TapTap 平台的用户 token 信息
name玩家在 TapTap 平台的昵称
avatar玩家在 TapTap 平台的头像 url
openId通过用户信息和游戏信息生成的用户唯一标识，每个玩家在每个游戏中的 openId 都是不一样的
unionId通过用户信息加上厂商信息生成的用户唯一标识，一个玩家在同一个厂商的所有游戏中 unionId 都是一样的，不同厂商下 unionId 不同

openId 和 unionId 使用标准的 Base64（带 Padding）编码，包含的字符有 A-Za-z0-9+/=。openId 和 unionId 长度最大值为 50 个字符。

info

由于 unionId 与游戏所属厂商有强关联性，因此 unionId 适用于如下场景：厂商使用测试服进行付费删档等测试，正式服需要对于之前参与测试的老玩家进行返利等操作。因为同一个玩家在同一个厂商下的所有游戏中的 unionId 不变。 一个游戏在厂商转移后同一个用户的 unionId 会发生改变，如果游戏使用了 unionId，TDS 技术支持会在转移前通过工单和游戏开发者确认相关数据的处理方案，保证迁移前后用户数据不错乱。

检查登录状态和用户信息​

登录状态和用户信息存在本地缓存中，重新登录将会重置，登出将会清除。

using TapSDK.Login;

try {
    TapTapAccount account = await TapTapLogin.Instance.GetCurrentTapAccount();
    if (account == null) {
        // 用户未登录
    } else {
        // 用户已登录
    }
} catch (Exception e) {
    Debug.Log($"获取用户信息失败 {e.Message}");
}

登出​

using TapSDK.Login;

TapTapLogin.Instance.Logout();

Unity PC 登录配置​

由于接入了 TapTap PC 端的游戏与未接入游戏在登录交互流程上存在明显差异，请开发者根据游戏的接入方式，选择对应的登录处理流程。

TapTap PC 端登录​

tip

接入 TapTap PC 端时， 初始化参数需要额外配置且需要添加启动校验，具体参考 TapTap PC 端集成 文档

在使用 TapTap PC 端登录时，SDK 将以静默方式进行登录流程，不会弹出 UI 窗口。由于该流程为异步操作，建议开发者在发起登录前显示加载（Loading）弹窗，并在登录流程完成后关闭该弹窗，以提升用户体验。

普通 PC 登录​

tip

SDK 默认支持扫码登录，跳转浏览器登录需要额外配置，具体参考以下两节。

PC 登录

Windows 平台​

如果想要在 Windows 使用跳转网页浏览器登录功能，需要在注册表添加相应配置：

Windows Registry Editor Version 5.00

[HKEY_CLASSES_ROOT\open-taptap-{client_id}]
@="{游戏名称}"
"URL Protocol"="{程序.exe 安装路径}"

[HKEY_CLASSES_ROOT\open-taptap-{client_id}]
@="{游戏名称}"

[HKEY_CLASSES_ROOT\open-taptap-{client_id}]

[HKEY_CLASSES_ROOT\open-taptap-{client_id}\Shell\Open]

[HKEY_CLASSES_ROOT\open-taptap-{client_id}\Shell\Open\Command]
@="\"{程序.exe 安装路径}\" \"%1\""

macOS 平台​

在 macOS 平台下，SDK 会自动配置 CFBundleURLTypes。

请通过以下步骤确认配置无误：

  • 在 Unity 下打开 BuildSetting 选择 PC、Mac & Linux Standalone Platform，Target Platform 选择 macOS。
  • 勾选 Create XCode Project，选择输出 XCode 工程进行编译。
  • 打开输出的 XCode Project，选择 Target，点击 Info，展开 URL Types，检查是否自动添加以下 URL Scheme：TapWeb : open-taptap-{clientId}，如未添加，则手动添加：
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string>TapWeb</string>
        <key>CFBundleURLSchemes</key>
        <array>
          <string>open-taptap-{client_id}</string>
        </array>
    </dict>
</array>