跳到主要内容
版本:v3

TapSDK 快速开始

本文介绍如何快速接入 TapSDK 并实现 TapTap 登录 功能。

备注

下载 页面提供了 Unity、Android、iOS 示例项目,可供参考。

创建应用

请登录 TapTap 开发者中心 注册为开发者并创建应用。

下载 TapTap 应用

在测试设备中下载 TapTap 客户端,测试时会唤起 TapTap 客户端授权登录。若用户设备中未安装 TapTap 客户端,则会打开 WebView 进行登录。

环境要求

  • Unity 2019.4 或更高版本
  • iOS 11 或更高版本,Xcode 版本 14.1 或更高版本
  • Android 5.0(API level 21)或更高版本
警告
  • 下面的项目配置以及初始化部分,预设开发者使用基于内建账户系统的 TDS 服务。
  • 如果游戏已经有了完整的账户系统,仅需要接入 TapTap 登录、内嵌动态,且不需要 TDS 更多云服务,则不必参考下面的配置和初始化方式,可跳转至 单纯的 TapTap 登录开发指南内嵌动态开发指南
  • 请慎重选择,如果之后需要其他 TDS 服务,升级需要一定的开发成本。

项目配置

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

但需要注意的是,要在 Packages/manifest.jsondependencies 同级下声明 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 文件拷贝到工程 AssetsPlugins 目录下,另外为了避免导出 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>

初始化

初始化 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_idclient_tokenserver_url,其中:

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

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

接入功能

TapSDK 提供了众多功能。请在初始化 SDK 后,根据项目需要,参考相应功能的文档,接入相应功能。 绝大多数游戏都会接入 TapTap 登录,所以我们推荐从这一功能开始。

接入 TapTap 登录

请根据开发者指南:快速上手,接入 TapTap 一键登录 完成操作。

配置签名证书

Android 和 iOS 应用需要在 TapTap 开发者中心进入你的游戏,依次选择 游戏服务 > 开发与构建 > TapTap 登录 配置应用的相关信息(如下图所示),否则 Android 应用测试登录功能时会返回 signature not match 报错信息,iOS 会返回 sdk_not_matched 报错信息,无法正常使用 TapTap 登录功能。

Android 签名处填写 MD5 值,详情可参考:如何获取 MD5 值

接下来,就可以打包应用,测试 TapTap 登录功能了。

Android 代码混淆

TapSDK 已经做了混淆处理,再次混淆会导致不可预期的错误,请在项目的混淆脚本中添加如下配置,跳过对 TapSDK 的混淆操作:

-keep class com.tds.** { *;}
-keep class com.taptap.** { *;}
-keep class com.tapsdk.** { *;}
-keep class tds.androidx.** { *;}

如果使用到基于数据存储的云服务,比如内建账户方式登录则需要额外添加 数据存储 相关的混淆代码。

打包

Android 或 iOS 请按通常的 Android APK 或者 iOS 应用打包流程操作即可。这里介绍一下 Unity 打包流程:

打包 APK

第一步,配置 package name 和签名文件:

第二步,检查 File > Build Settings > Player Settings > Other Settings > Target API Level 版本,当 API Level 小于 29 时,需要配置 manifest,在 application 节点添加:

tools:remove="android:requestLegacyExternalStorage"

这是因为 SDK 内部默认配置了 android:requestLegacyExternalStorage = true,当 targetSdkVersion < 29 时会报错 Android resource linking failed

导出 Xcode 工程

需要配置 icon 和 BundleID