Version: v4

Unity SDK 开发指南

本文介绍如何在 Unity 项目中接入 TapTap 登录，覆盖 Android、iOS 和 PC。

集成前准备

参考开发者中心配置创建应用、配置包名与签名证书
参考 TapTap 登录功能介绍开通 TapTap 登录服务
参考 Unity 集成指南完成 TapSDK 基础接入。接入 TapTap PC 端时，还需完成启动校验

SDK 获取

远程依赖

NPMJS 方式：在 Packages/manifest.json 中添加：

"dependencies":{
  "com.taptap.sdk.core":"4.11.0",
  "com.taptap.sdk.login":"4.11.0"
}

GitHub 方式：在 Packages/manifest.json 中添加：

"dependencies":{
  "com.taptap.sdk.core":"https://github.com/taptap/tapsdk-unity-dist.git?path=/Core#4.11.0",
  "com.taptap.sdk.login":"https://github.com/taptap/tapsdk-unity-dist.git?path=/Login#4.11.0"
}

本地文件导入

在下载页下载并导入以下 unitypackage 文件：

TapSDK_Core.unitypackage（TapTapSDK 核心模块，必选）
TapSDK_Login.unitypackage（TapTapSDK 登录模块，必选）

工程配置

iOS 配置

通过 Unity 导出 Xcode 工程时，需要添加 TapTap 客户端跳转配置。

在 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>

PC 配置

接入 TapTap PC 端的游戏，与未接入游戏的登录交互不同。请按实际接入方式选择对应流程。

TapTap PC 端登录

tip

接入 TapTap PC 端时，需要使用启动校验功能，具体参考 Unity PC 接入说明。

在 TapTap PC 端登录时，SDK 会静默完成登录，不会弹出 UI。该流程为异步操作，建议在发起登录前显示加载弹窗，并在登录完成后关闭。

普通 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 中打开 Build Settings，选择 PC、Mac & Linux Standalone，Target Platform 选择 macOS
勾选 Create Xcode Project，导出 Xcode 工程后编译
打开导出的 Xcode 工程，选择 Target，点击 Info，展开 URL Types，检查是否自动添加 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 登录按钮后调用。授权范围必须包含 public_profile 或 basic_info，可按业务组合其他权限。

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

tip

若只请求 basic_info，用户可使用无感登录，无需手动确认授权。

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using TapSDK.Login;
using UnityEngine;

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

参数	类型	必选	说明
`scopes`	`string[]`	是	本次登录请求的授权范围，必须包含 `public_profile` 或 `basic_info`。

LoginWithScopes 成功时返回 TapTapAccount；用户取消时抛出 TaskCanceledException；登录失败时抛出其他异常。请区分三种结果：

登录成功：使用返回的账号信息建立游戏登录态
用户取消：捕获 TaskCanceledException，不要提示为系统错误
登录失败：记录异常信息，并允许用户重试

获取当前用户

游戏启动时先调用该接口。该接口没有参数，返回本地缓存的 TapTapAccount；没有可用登录信息时返回 null。如果本地已有有效登录信息，不要再弹出登录按钮。

using System;
using TapSDK.Login;
using UnityEngine;

try
{
    TapTapAccount account = await TapTapLogin.Instance.GetCurrentTapAccount();
    if (account != null)
    {
        // 用户已登录
        AccessToken accessToken = account.accessToken;
        string openId = account.openId;
    }
    else
    {
        // 用户未登录，显示登录按钮
    }
}
catch (Exception e)
{
    Debug.Log($"获取用户信息失败 {e.Message}");
}

字段	说明
`accessToken`	玩家在 TapTap 平台的用户 token。服务端调用 OpenAPI 时使用，见获取用户信息
`openId`	用户在当前游戏内的唯一标识
`unionId`	用户在同一厂商下所有游戏中的统一标识
`name`	TapTap 昵称
`avatar`	TapTap 头像 URL

登出

登出只清除本地缓存的 TapTap 登录信息，不会退出 TapTap 客户端。

using TapSDK.Login;

TapTapLogin.Instance.Logout();

接入验证

场景	预期结果
初始化完成后点击登录	进入成功、取消或失败之一
Android / iOS 已安装 TapTap 客户端	拉起客户端完成授权
Android / iOS 未安装 TapTap 客户端	进入 WebView 授权
iOS 授权后返回游戏	收到登录结果
Windows TapTap PC 端登录	静默完成登录
普通 PC 扫码或浏览器登录	授权完成后返回登录结果
登录成功后重启游戏	`GetCurrentTapAccount()` 返回当前账号
调用 `Logout()`	本地登录信息被清除，可重新发起登录
用户取消登录	捕获 `TaskCanceledException`，不提示系统错误

集成前准备​

SDK 获取​

远程依赖​

本地文件导入​

工程配置​

iOS 配置​

PC 配置​

TapTap PC 端登录​

普通 PC 登录​

Windows 平台​

macOS 平台​

发起登录​

获取当前用户​

登出​

接入验证​