版本：v4

开发指南

权限说明

Unity
Android Java
Android Kotlin
iOS

该模块依赖如下权限：

权限	使用目的	权限申请时机
网络权限	用于访问网络数据	用户首次使用该功能时会申请权限

该模块将在应用中添加如下配置：

<uses-permission android:name="android.permission.INTERNET"/>

该模块依赖如下权限：

权限	使用目的	权限申请时机
网络权限	用于访问网络数据	用户首次使用该功能时会申请权限

该模块将在应用中添加如下配置：

<uses-permission android:name="android.permission.INTERNET"/>

准备集成 SDK

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

SDK 获取

Unity
Android Java
Android Kotlin
iOS

接入外部依赖

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

SDK 使用的 JSON 解析库为 Newtonsoft-json，如果当前工程已接入该依赖库，则不需额外处理，否则需在 Packages/manifest.json 添加如下依赖：

"com.unity.nuget.newtonsoft-json":"3.2.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"
         ]
      }
  ]
}

提示

如果需要接入 TapSDK Unity PC 平台，需要在使用 NuGet 集成工具，集成 K4os.Compression.LZ4 , protobuf-net 两个库，具体设置如下：

在 Packages/manifest.json 添加如下依赖：

"com.github-glitchenzo.nugetforunity": "https://github.com/GlitchEnzo/NuGetForUnity.git?path=/src/NuGetForUnity"

添加完后，在 Unity 顶部菜单中如果没有出现 NuGet选项，可以重启 Unity 编辑器，包括 Unity Hub 客户端。
在 Unity 顶部菜单中选择 NuGet > Manage NuGet Packages，在弹出的窗口中搜索 K4os.Compression.LZ4 和 protobuf-net 并安装。
最终会在 Assets文件夹下的 packages.config 文件中自动生成如下依赖：

<?xml version="1.0" encoding="utf-8"?>
<packages>
  <package id="K4os.Compression.LZ4" version="1.3.8" manuallyInstalled="true" />
  <package id="System.Collections.Immutable" version="7.0.0" />
  <package id="System.Runtime.CompilerServices.Unsafe" version="6.0.0" />
  <package id="protobuf-net" version="3.2.30" manuallyInstalled="true" />
  <package id="protobuf-net.Core" version="3.2.30" />
</packages>

添加 SDK 依赖

SDK 支持 Unity Package Manager 及本地文件导入两种集成方式，开发者根据需求选择其中一种即可，推荐使用远程依赖。

远程依赖

SDK 支持通过 NPMJS 及 GitHub 两种方式，开发者选择其中一种即可。

1. NPMJS 接入

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

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

但需要注意的是，需在 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/TapSDKCore-Unity.git#4.4.0",
   "com.taptap.sdk.login":"https://github.com/taptap/TapSDKLogin-Unity.git#4.4.0", 
 }

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

本地文件导入

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

提示

复制使用以下内容时，请删除空行以及注释，以免出现 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>

项目根目录的 build.gradle 添加仓库地址：

repositories {
  google()
  mavenCentral()
}

app module 的 build.gradle 添加对应依赖：

dependencies {
    implementation 'com.taptap.sdk:tap-core:4.4.0'
    implementation 'com.taptap.sdk:tap-kit:4.4.0'
    implementation 'com.taptap.sdk:tap-login:4.4.0'
}

提示

如果 targetSdkVersion < 29，还需要添加如下配置：

manifest 节点添加 xmlns:tools="http://schemas.android.com/tools"
application 节点添加 tools:remove="android:requestLegacyExternalStorage"

项目根目录的 build.gradle 添加仓库地址：

repositories {
  google()
  mavenCentral()
}

app module 的 build.gradle 添加对应依赖：

dependencies {
    implementation 'com.taptap.sdk:tap-core:4.4.0'
    implementation 'com.taptap.sdk:tap-kit:4.4.0'
    implementation 'com.taptap.sdk:tap-login:4.4.0'
}

提示

如果 targetSdkVersion < 29，还需要添加如下配置：

manifest 节点添加 xmlns:tools="http://schemas.android.com/tools"
application 节点添加 tools:remove="android:requestLegacyExternalStorage"

添加依赖

iOS 提供通过添加 cocoaPods 远程依赖和使用本地文件导入两种集成方式，推荐使用远程依赖方式。

远程依赖

在工程 Podfile 文件中对应模块下添加依赖：

 pod 'TapTapLoginSDK', '~> 4.4.0'

执行 pod install 下载对应依赖文件
将工程 Pods 目录下 TapTapLoginSDK/Frameworks/TapTapLoginResource.bundle 等资源文件导入工程中

本地文件依赖

TapTap 登录依赖于初始化模块，使用本地文件方式添加依赖时，需先参考 TapSDK 集成添加对应本地文件依赖项。

在下载页下载如下文件：

TapTapLoginSDK.xcframework 登录依赖库
TapTapLoginResource.bundle 登录资源文件

在工程中添加 framework 静态库，注意添加时选择 Embed 方式为 Do Not Embed，导入 bundle 资源文件
SDK 内部使用了 Kingfisher 依赖库，开发者应提前通过远程或文件导入方式添加对应依赖。

工程配置

TapTap 客户端应用跳转配置

打开 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>

配置 openUrl
a) 如果项目中有 SceneDelegate.swift，请先删除，然后请添加如下代码到 AppDelegate.swift 文件：

import TapTapLoginSDK

func application(_ app: UIApplication, open url: URL) -> Bool {
    return TapTapLogin.open(url: url)
}
    
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    return TapTapLogin.open(url: url)
}
    
func application(_ application: UIApplication, open url: URL, sourceApplication: String?, annotation: Any) -> Bool {
    return TapTapLogin.open(url: url)
}

b) 删除 info.plist 里面的 Application Scene Manifest

c) 删除 AppDelegate.swift 文件中的两个管理 Scenedelegate 生命周期代理方法

func application(_ application: UIApplication, configurationForConnecting connectingSceneSession: UISceneSession, options: UIScene.ConnectionOptions) -> UISceneConfiguration {
    
}
    
func application(_ application: UIApplication, didDiscardSceneSessions sceneSessions: Set<UISceneSession>) {
    
}

d) 在 AppDelegate.swift 中添加 UIWindow

var window: UIWindow?

SDK 初始化

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

Unity
Android Java
Android Kotlin
iOS

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

TapTapSdkOptions 详细参数见入门指南#快速开始

import com.taptap.sdk.core.TapTapRegion;
import com.taptap.sdk.core.TapTapSdk;
import com.taptap.sdk.core.TapTapSdkOptions;

/* 必选配置 */
// 开发者中心对应 Client ID
String clientId = "";
// 开发者中心对应 Client Token
String clientToken = "";
// 是否开启 log，建议 Debug 开启，Release 关闭，默认关闭 log
boolean enableLog = BuildConfig.DEBUG;

TapTapSdkOptions tapSdkOptions = new TapTapSdkOptions(
        clientId, // 游戏 Client ID
        clientToken, // 游戏 Client Token
        TapTapRegion.CN // 游戏可玩区域: [TapTapRegion.CN]=国内 [TapTapRegion.GLOBAL]=海外
);
tapSdkOptions.setEnableLog(enableLog);
// 初始化 TapSDK
TapTapSdk.init(context, tapSdkOptions);

TapTapSdkOptions 详细参数见入门指南#快速开始

import com.taptap.sdk.core.TapTapSdk
import com.taptap.sdk.core.TapTapSdkOptions
import com.taptap.sdk.core.TapTapRegion
import com.taptap.sdk.core.TapTapLanguage

TapTapSdk.init(
  context = context,
  sdkOptions = TapTapSdkOptions(
      clientId = clientId,
      clientToken = clientToken,
      region = TapTapRegion.CN,
      preferredLanguage = TapTapLanguage.ZH_HANS,
      enableLog = false
  )
)

import TapTapCoreSDK

// 核心配置项
let options = TapTapSdkOptions()
options.clientId = "your_client_id" // 必须，开发者中心对应 Client ID
options.clientToken = "your_client_token" // 必须，开发者中心对应 Client Token
options.region = .CN // .CN：中国大陆，.overseas：其他国家或地区
options.enableLog = enableLog.selectedSegmentIndex == 0 // 是否开启 log，建议 Debug 开启，Release 关闭，默认关闭 log
options.preferredLanguage = TapLanguageType.auto // 语言设置，默认跟随系统，当系统语言不支持时，国内为中文，海外为英文

// 初始化 SDK
TapTapSDK.initWith(options)

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

// 定义授权范围
List<string> scopes = new List<string>();
scopes.Add(TapTapLogin.TAP_LOGIN_SCOPE_PUBLIC_PROFILE);

// 初始化登录请求 Task
Task<TapTapAccount> task = TapTapLogin.Instance.LoginWithScopes(scopes.ToArray());
var result = await task;

// 判断登录结果
if (task.IsCompleted)
{
    // 登录成功
} 
else if (task.IsCanceled)
{
    // 登录取消
}
else
{
    // 登录失败
    Debug.Log($"登录失败: {task.Exception.Message}");
}

import com.taptap.sdk.kit.internal.callback.TapTapCallback;
import com.taptap.sdk.kit.internal.exception.TapTapException;
import com.taptap.sdk.login.Scopes;
import com.taptap.sdk.login.TapTapAccount;
import com.taptap.sdk.login.TapTapLogin;
import androidx.annotation.NonNull;

// 定义授权范围
String[] scopes = new String[]{Scopes.SCOPE_PROFILE, Scopes.SCOPE_BASIC_INFO};

TapTapLogin.loginWithScopes(activity, scopes, new TapTapCallback<TapTapAccount>() {
    @Override
    public void onSuccess(TapTapAccount tapTapAccount) {
        // 登录成功
    }

    @Override
    public void onFail(@NonNull TapTapException exception) {
        // 登录失败
    }

    @Override
    public void onCancel() {
        // 登录取消
    }
});

import com.taptap.sdk.login.TapTapLogin
import com.taptap.sdk.kit.internal.callback.TapTapCallback
import com.taptap.sdk.login.TapTapAccount
import com.taptap.sdk.login.Scopes

val scopes = mutableSetOf<String>()
scopes.add(Scopes.SCOPE_PROFILE)

TapTapLogin.loginWithScopes(
    activity,
    scopes.toTypedArray(),
    object : TapTapCallback<TapTapAccount> {

        override fun onSuccess(result: TapTapAccount) {
            // 成功
        }

        override fun onCancel() {
            // 取消
        }

        override fun onFail(exception: TapTapException) {
           // 失败
        }
    }
)

import TapTapLoginSDK

// 定义授权范围
var scopes: [Scope] = [Scope.publicProfile]

// 发起 Tap 登录
TapTapLogin.loginWithScopes(with: scopes) {[weak self] account, error, isCancel in
    guard let self else { return }
    if isCancel {
        // 登录取消
    } else if let error = error {
         // 登录失败
        NSLog("Tap登录失败：\(error.localizedDescription)")
    } else if let account = account {
         // 登录成功

         // 登录 token
         let token = account.accessToken
         // 用户信息
         let userInfo = account.userInfo
    }
}

不同的授权范围

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

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

获取用户信息

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

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

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

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

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

信息

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

检查登录状态和用户信息

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

Unity
Android Java
Android Kotlin
iOS

using TapSDK.Login;

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

import com.taptap.sdk.login.AccessToken;
import com.taptap.sdk.login.TapTapAccount;
import com.taptap.sdk.login.TapTapLogin;

TapTapAccount currentTapAccount = TapTapLogin.getCurrentTapAccount();

if (currentTapAccount != null) {
    // 已登录
    AccessToken accessToken = currentTapAccount.getAccessToken();
} else {
    // 未登录
}

import com.taptap.sdk.login.TapTapLogin
import com.taptap.sdk.login.TapTapAccount

// 获取用户信息
when (TapTapLogin.getCurrentTapAccount() == null) {
    true -> {
        // 未登录
    }

    else -> {
        // 已登录
    }
}

import TapTapLoginSDK

if let account = TapTapLogin.getCurrentTapAccount() {
    let token = account.accessToken
    let profile = account.userInfo
    if let token, let profile {
            // 用户已登录
       } else {
         NSLog("Tap账户未登录")
    }
} else {
    NSLog("Tap账户未登录")
}

登出

Unity
Android Java
Android Kotlin
iOS

using TapSDK.Login;

TapTapLogin.Instance.Logout();

import com.taptap.sdk.login.TapTapLogin;

TapTapLogin.logout();

import com.taptap.sdk.login.TapTapLogin

TapTapLogin.logout()

import TapTapLoginSDK

TapTapLogin.logout()

Unity PC 登录配置

提示

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>

权限说明​

准备集成 SDK​

SDK 获取​

接入外部依赖​

添加 SDK 依赖​

远程依赖​

1. NPMJS 接入​

2. GitHub 接入​

本地文件导入​

iOS 配置​

添加依赖​

远程依赖​

本地文件依赖​

工程配置​

SDK 初始化​

登录​

不同的授权范围​

获取用户信息​

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

登出​

Unity PC 登录配置​

Windows 平台​

macOS 平台​

权限说明

准备集成 SDK

SDK 获取

接入外部依赖

添加 SDK 依赖

远程依赖

1. NPMJS 接入

2. GitHub 接入

本地文件导入

iOS 配置

添加依赖

远程依赖

本地文件依赖

工程配置

SDK 初始化

登录

不同的授权范围

获取用户信息

检查登录状态和用户信息

登出

Unity PC 登录配置

Windows 平台

macOS 平台