跳到主要内容
版本：v3

单纯 TapTap 用户认证

如果你仅仅只需要接入 TapTap 这一种登录方式，确认不使用 TDS 其他云服务，可以看本篇文档。请注意，如果刚开始只选择接入「TapTap 登录」，后面又需要使用其他云服务的话，后期可能有一定的升级成本。

使用原来 TapSDK v1.x 版本的开发者，也可以参考 1.x 升级 3.x 指南 完成 TapSDK 的升级。

环境要求​

  • Unity 2019.4 或更高版本
  • iOS 11 或更高版本，Xcode 版本 14.1 或更高版本
  • Android 5.0（API level 21）或更高版本

权限说明​

集成前准备​

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

SDK 获取​

单纯接入「TapTap 登录」，需要依赖 TapLogin 和 TapCommon 模块。请先 下载 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"

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

"dependencies":{
    "com.taptap.tds.login":"https://github.com/TapTap/TapLogin-Unity.git#3.29.4",
    "com.taptap.tds.common":"https://github.com/TapTap/TapCommon-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_Login.unitypackage TapTap 登录，必选。

  3. 如果当前项目已集成 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>

提示

如果是手动下载 unitypackage 进行 SDK 导入，需要将 Assets/TapTap/Common/Plugins/iOS/TapTap.Common.dll 设置为只支持 iOS。

iOS 配置​

在 Assets/Plugins/iOS/Resource 目录下创建 TDS-Info.plist 文件，复制以下代码并且替换其中的 ClientId。如果游戏使用了 TapTap 内嵌动态或数据分析服务，需要配置相关权限并替换授权文案：

提示

复制使用以下内容时，请删除空行以及注释，以免出现 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>
    <!--使用内嵌动态服务，需要相册、相机、麦克风权限-->
    <key>NSPhotoLibraryUsageDescription</key>
    <string>说明为何应用需要此项权限</string>
    <key>NSCameraUsageDescription</key>
    <string>说明为何应用需要此项权限</string>
    <key>NSMicrophoneUsageDescription</key>
    <string>说明为何应用需要此项权限</string>
    <!--使用数据分析服务需要 IDFA 权限。如应用程序不想弹框，可以设置 TapDB.AdvertiserIDCollectionEnabled(false)-->
    <key>NSUserTrackingUsageDescription</key>
    <string>说明为何应用需要此项权限</string>
</dict>
</plist>

初始化​

信息

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

单纯 TapTap 登录初始化时需要区分适用于中国大陆还是其他国家或地区。

// 适用于中国大陆
TapLogin.Init(string clientID);

// 适用于其他国家或地区
TapLogin.Init(string clientID, bool isCn, bool roundCorner);

参数说明

参数描述
clientIDTapTap 开发者中心对应应用的 Client ID
isCn中国大陆为 true，其他国家或地区为 false
roundCorner网页登录时边框是否使用圆角，使用圆⻆边框为 true，使用直⻆边框为 false

TapTap 登录并获取登录结果​

提示

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

try
{
    // 在 iOS、Android 系统下，会唤起 TapTap 客户端或以 WebView 方式进行登录
    // 在 Windows、macOS 系统下显示二维码（默认）和跳转链接（需配置）
    var accessToken = await TapLogin.Login();
    Debug.Log($"TapTap 登录成功 accessToken: {accessToken.ToJson()}");
}
catch (Exception e)
{
    if (e is TapException tapError)  // using TapTap.Common
    {
        Debug.Log($"encounter exception:{tapError.code} message:{tapError.message}");
        if (tapError.code == (int)TapErrorCode.ERROR_CODE_BIND_CANCEL) // 取消登录
        {
            Debug.Log("登录取消");
        }
    }
}

// 获取 TapTap Profile  可以获得当前用户的一些基本信息，例如名称、头像。
var profile = await TapLogin.FetchProfile();
Debug.Log($"TapTap 登录成功 profile: {profile.ToJson()}");

这里获取的 TapTapAccount 根据游戏申请的授权范围有所差异。

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

参数说明
accessToken用户访问凭证
openid通过用户信息和游戏信息生成的用户唯一标识，每个玩家在每个游戏中的 openid 都是不一样的
unionid通过用户信息加上厂商信息生成的用户唯一标识，一个玩家在同一个厂商的所有游戏中 unionid 都是一样的，不同厂商下 unionid 不同
name玩家在 TapTap 平台的昵称
avatar玩家在 TapTap 平台的头像 url
email用户在 TapTap 平台注册使用的邮箱

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

信息

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

开发者可以合理使用这些信息。

参见TapTap OAuth 接口文档。

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

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

// 获取登录状态
try 
{
    var accesstoken = await TapLogin.GetAccessToken();
    Debug.Log("已登录");
    // 直接进入游戏
} 
catch (Exception e)
{
    Debug.Log("当前未登录");
    // 开始登录
}

// 获取用户信息
await TapLogin.GetProfile();

// 获取实时更新的用户信息
await TapLogin.FetchProfile();

登出​

TapLogin.Logout();

Unity PC 登录配置​

Unity SDK 自 3.5.2 起支持在 Windows、macOS 下让玩家扫码或跳转网页浏览器完成 TapTap 登录。

SDK 默认支持扫码登录，跳转浏览器登录需要额外配置。

升级到内建账户系统​

前面说过，如果前期开发时只把「TapTap 登录」作为一个第三方渠道进行了接入，后期要使用内建账户系统，或者老的 v1.x 版本的游戏要升级到 3.x 版本并使用其他服务，这时候会有「一定的开发成本」。这里我们就来具体说说这种情况下该如何处理。

  1. 首先按照前述初始化和一键完成 TapTap 登录的提示，完成内建账户系统的 TapTap 用户登录，这时候开发者可以得到一个 TDSUser 实例。

  2. 登录成功后获得当前授权用户的 Profile 信息。请注意，这里的 Profile 信息和游戏之前得到的 Profile 信息应该是完全一样的，游戏开发者应该可以据此找到游戏服务器上持久化保存的玩家信息，也可以将当前的 TDSUser 与原来的游戏玩家信息绑定在一起。对于游戏来说，最后是否需要将 TDSUser 与游戏内玩家账户进行绑定，是完全由开发者自己决定的：

    • 不绑定是可行的，因为 TapSDK 内部会缓存当前用户的登录状态，需要的时候总能得到之前登录的 TDS 账户；
    • 绑定带来的好处则是使用上更加简单，同时也可以将 TDS 账户信息扩展到更多的第三方平台。