跳到主要内容

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

但需要注意的是，要在 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.2",
    "com.taptap.tds.common":"https://github.com/TapTap/TapCommon-Unity.git#3.29.2",
    "com.taptap.tds.bootstrap":"https://github.com/TapTap/TapBootstrap-Unity.git#3.29.2",
    "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>

初始化​

初始化 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 协议，参考文档关于 域名 的说明。

接入功能​

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：