跳到主要内容
版本：v3

接入 TapTap 登录

接入 TapTap 登录有两种方式：

  1. 基于内建账户系统接入 TapTap 登录；（不推荐）
  2. 单纯 TapTap 用户认证。（推荐）

第一种方式一般适用于以下场景：

  • 希望直接使用 TapSDK 提供的账户系统
  • 希望将更多第三方账号（比如 QQ、微信、Apple 等）绑定到玩家账号上
  • 希望使用 TapSDK 的好友、成就等基于内建账户系统的服务和功能
提示

内建账户系统：需要游戏侧进行自定义 API 域名绑定，需要游戏进行备案；此外，如果游戏需要兼容 Android 7.1 以下版本设备，需自行购买 SSL 证书并进行手动管理。因此，推荐使用 单独 TapTap 用户认证方式。

相反，如果你的游戏自己实现了账户系统，也不打算使用排行榜、云存档、成就功能，那么可以考虑使用第二种方式。

首先介绍第一种方式，然后介绍第二种方式。

无论使用哪种方式，首先都需要在 开发者中心 > 游戏服务 > 功能接入 开启「TapTap 登录」。

环境要求​

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

权限说明​

集成前准备​

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

SDK 获取​

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

但需要注意的是，要在 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.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",
    "com.taptap.tds.bootstrap":"https://github.com/TapTap/TapBootstrap-Unity.git#3.29.4",
    "com.leancloud.realtime":"https://github.com/leancloud/csharp-sdk-upm.git#realtime-2.3.0",
    "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_Bootstrap.unitypackage 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>

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 应用​

用户无 TapTap 应用时，默认会通过 WebView 登录。

  1. 打开 info.plist，添加如下配置（请替换 clientID 为你在控制台获取的 Client ID）：

    <key>CFBundleURLTypes</key>
    <array>
        <dict>
            <key>CFBundleTypeRole</key>
            <string>Editor</string>
            <key>CFBundleURLName</key>
            <string>taptap</string>
            <key>CFBundleURLSchemes</key>
            <array>
                <!-- 这里注意下，中括号需要去掉，最终是 Client ID 前拼接上 `tt` 的形式，例如：ttFwFdCxxxxxxxQDQwQN -->
                <string>tt[clientID]</string>
            </array>
        </dict>
    </array>

    <key>LSApplicationQueriesSchemes</key>
    <array>
      <string>tapiosdk</string>
      <string>tapsdk</string>
      <string>taptap</string>
    </array>

SDK 初始化​

初始化 TapSDK 时需传入 Client ID、区域等应用配置信息。

using TapTap.Bootstrap; // 命名空间
using TapTap.Common; // 命名空间

var config =  new TapConfig.Builder()
    .ClientID("your_client_id") // 必须，开发者中心对应 Client ID
    .ClientToken("your_client_token") // 必须，开发者中心对应 Client Token
    .ServerURL("https://your_server_url") // 必须，开发者中心 > 你的游戏 > 游戏服务 > 基本信息 > 域名配置 > API
    .RegionType(RegionType.CN) // 非必须，CN 表示中国大陆，IO 表示其他国家或地区
    .ConfigBuilder();
TapBootstrap.Init(config);

初始化的时候，必须填入 client_id、client_token 和 server_url，其中：

  • client_id、client_token 信息可在 开发者中心 > 你的游戏 > 游戏服务 > 应用配置 查看。

  • server_url 请使用 HTTPS 协议，参考文档关于 域名 的说明。

检查登录状态​

SDK 会在本地缓存当前用户的登录信息，所以如果一个玩家在游戏内登录之后，下次启动用户通过调用如下方法可以得到之前登录的账户实例。 缓存不会自动清除。此时玩家无需再次登录，可以直接进入游戏，实现静默登录。

如果玩家在游戏内进行了登出或者玩家手动清除了游戏的存储数据，则本地缓存的登录信息也会被删除，下次进入游戏时调用如下方法会返回一个 null 对象，玩家需要登录之后再进入游戏。

var currentUser = await TDSUser.GetCurrent();
if (null == currentUser)
{
    Debug.Log("当前未登录");
    // 开始登录
}
else
{
    Debug.Log("已登录");
    // 进入游戏
}

一键完成 TapTap 登录​

对于「TapTap 用户登录」，TapSDK 提供了特别的支持，以帮助开发者以最便捷的方式和最少的时间完成接入。

你可以直接调用 TDSUser.loginWithTapTap 方法来一键登录，例如：

try
{
    // 在 iOS、Android 系统下会唤起 TapTap 客户端或以 WebView 方式进行登录
    // 在 Windows、macOS 系统下显示二维码（默认）和跳转链接（需配置）
    var tdsUser = await TDSUser.LoginWithTapTap();
    Debug.Log($"login success:{tdsUser}");
    // 获取 TDSUser 属性
    var objectId = tdsUser.ObjectId;     // 用户唯一标识
    var nickname = tdsUser["nickname"];  // 昵称
    var avatar = tdsUser["avatar"];      // 头像
}
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 客户端或以 WebView 方式开始登录流程，用户授权之后 SDK 使用 TapTap OAuth 授权结果完成 TDS 内建账户系统的登录。

TDSUser 即是当前玩家的账户，登录成功之后开发者可以：

  • 通过访问 objectId 得到玩家在账户系统的 id（用户唯一标识），可用于游戏服务端内玩家与 TDS 内建账户的绑定或匹配。
  • 通过访问 nickname 属性来获得 TapTap 账号的用户名。
  • 通过访问 avatar 属性来获得 TapTap 账号的头像。

开发者还可以在 TapTap 开发者中心后台 查看或管理账户系统。

不同的授权范围​

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

权限说明TapSDK 最早支持版本
public_profile获得 openid、unionid、用户昵称、用户头像v2.0.0
user_friends获得访问 TapTap 好友相关数据的权限v2.0.0
basic_info获得 openid 和 unionidv3.13.0
提示

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

获取用户信息​

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

var profile = await TapLogin.FetchProfile();
Debug.Log($"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 技术支持会在转移前通过工单和游戏开发者确认相关数据的处理方案，保证迁移前后用户数据不错乱。

登出当前账户​

账户的登出非常简单，调用 logOut 方法即可。

await TDSUser.Logout();

Unity PC 登录配置​

提示

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

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>

国际化​

TapTap 登录支持设置语言：

TapCommon.SetLanguage(TapLanguage.AUTO);

支持如下语言：

namespace TapTap.Common
{
    public enum TapLanguage
    {
        AUTO = 0, // 自动
        ZH_HANS = 1, // 简体中文
        EN = 2, // 英文
        ZH_HANT = 3, // 繁体中文
        JA = 4, // 日文
        KO = 5, // 韩文
        TH = 6, // 泰文
        ID = 7, // 印尼语
        DE = 8, // 德语
        ES = 9, // 西班牙语
        FR = 10, // 法语
        PT = 11, // 葡萄牙语
        RU = 12, // 俄语
        TR = 13, // 土耳其语
        VI = 14, // 越南语
    }
}

「自动」会尝试根据系统语言设置语言，如果系统语言不在上述支持的语言之中，那么会根据 SDK 初始化时配置的区域设置语言。 区域为中国大陆时会设置为简体中文，否则会设置为英文。

时长统计​

从 TapSDK Android / iOS / Unity 3.20.0 版本 、UE4 3.21.0 版本开始，为了在 Tap 客户端中展示用户的游戏时长，TapSDK 默认会收集当前用户的时长数据，开发者可在调用初始化接口前使用如下接口进行设置是否收集。

using TapTap.Common; // 命名空间

TapCommon.SetDurationStatisticsEnabled(true);

更多功能​

请阅读内建账户指南了解内建账户系统的更多功能。

视频教程​

可以参考视频教程：如何在游戏中集成 TapTap 登录功能，了解如何在 Untiy 项目中接入登录功能。

更多视频教程见开发者学堂。因为 SDK 功能在不断完善，视频教程可能出现与新版 SDK 功能不一致的地方，以当前文档为准。