Tap 客服开发指南
本文介绍如何在游戏中接入 TDS 提供的客服系统。
权限说明
- Unity
- Android
- iOS
- UE4
该模块需要权限如下:
权限 | 使用目的 | 权限申请时机 |
---|---|---|
网络权限 | 访问网络数据 | 用户首次使用该功能时会申请权限 |
获取网络状态 | 用于检测当前网络连接是否有效 | 用户首次使用该功能时会申请权限 |
读取存储权限 | 用于反馈工单时添加本地图片、视频附件 | 上传附件时申请 |
该模块将在应用 AndroidManifest.xml
中添加如下权限:
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"
android:maxSdkVersion="32" />
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES"/>
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO"/>
SDK 初始化
在 下载页 获得 TapSDK,引入 TapSupport
模块:
- Unity
- Android
- iOS
- UE4
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.support":"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.common":"https://github.com/TapTap/TapCommon-Unity.git#3.29.4",
"com.taptap.tds.support":"https://github.com/TapTap/TapSupport-Unity.git#3.29.4",
"com.leancloud.storage":"https://github.com/leancloud/csharp-sdk-upm.git#storage-2.3.0",
}
在 Unity 顶部菜单中选择 Window > Package Manager 可查看已经安装在项目中的包。
方法二:手动导入
-
在 下载页 找到 TapSDK Unity 下载地址,下载
TapSDK-UnityPackage.zip
。 -
在 Unity 项目中依次转到 Assets > Import Packages > Custom Packages,从解压后的
TapSDK-UnityPackage.zip
中,选择希 望在游戏中使用的 TapSDK 包导入,其中:
TapTap_Common.unitypackage
TapSDK 基础库,必选。TapTap_Support.unitypackage
TapTap 客服库,必选。
- 如果当前项目已集成
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>
TapSupport SDK 依赖 TapCommon 模块:
repositories{
flatDir {
dirs 'libs'
}
}
dependencies {
...
implementation name:'TapCommon_3.29.4', ext:'aar'
implementation (name:'TapSupport_3.29.4', ext:'aar')
}
确认 AndroidManifest.xml
已添加网络权限:
<uses-permission android:name="android.permission.INTERNET"></uses-permission>
TapSupport SDK 依赖 TapCommon 模块:
TapCommonSDK.framework
TapSupportSDK.framework
TapSupport SDK 依赖 TapCommon 模块:
PublicDependencyModuleNames.AddRange(
new string[]
{
"TapCommon",
"TapSupport"
// ... add other public dependencies that you statically link with here ...
}
);
在初始化 SDK 之前,有一些准备工作需要完成:
- 请厂商管理员或客服管理员邀请你成为客服管理员。
- 每个厂商会被分配一个专属域名,需要记下待用。你可以在客服工作台的 设置 > 开发者信息 中找到可用的域名。如果你想要使用自己的域名,可以联系厂商管理员在开发者中心游戏客服模块中绑定。
- 在客服工作台,为你的游戏创建一个产品(设置 > 管理 > 产品与分类),记下这个产品的 ID。
然后使用以下 代码初始化 TapSupport 模块:
- Unity
- Android
- iOS
- UE4
using TapTap.Support;
TapSupport.Init("https://please-replace-with-your-customized.domain.com", "产品 ID");
import com.tds.tapsupport.TapSupport;
import com.tds.tapsupport.TapSupportCallback;
import com.tds.tapsupport.TapSupportConfig;
TapSupportConfig config = new TapSupportConfig("https://please-replace-with-your-customized.domain.com", "产品 ID", new TapSupportCallback() {
@Override
public void onUnreadStatusChanged(boolean hasUnread) {
// 我们会在 §未读消息通知 讨论 callback 的用法
}
})
TapSupport.setConfig(this, config);
#import <TapSupportSDK/TapSupportSDK.h>
TapSupportConfig *config = [TapSupportConfig new];
config.server = @"https://please-replace-with-your-customized.domain.com";
config.productID = @"产品 ID";
config.callback = self;
[TapSupport shareInstance].config = config;
#include "TapUESupport.h"
FTapSupportConfig Config;
Config.ServerUrl = TEXT("https://please-replace-with-your-customized.domain.com");
Config.ProductID = TEXT("产品 ID");
TapUESupport::Init(Config);
上述代码示例中,please-replace-with-your-customized.domain.com
就是准备工作 2 中获取或绑定的域名。产品 ID
是在准备工作 3 中新建的产品的 ID。
登录
为了确保玩家提交的表单等信息只有该玩家能访问,客服系统需要登录才能使用。我们提供三种不同的登录方式:
- TDS 内建账户(TDSUser)登录
- 游戏自有账户系统关联登录
- 匿名登录
这里的登录指的是游戏玩家在游戏内使用客服系统功能时认证身份的过程(authentication)。这一步主要是游戏侧与客服系统之间的交互,通常玩家是无感知的,和游戏本身的登录是两回事(比如这里的匿名登录与游戏的游客登录无关)。
TDS 内建账户登录
如果你的游戏使用了 TDS 内建账户服务,可以直接在客户端使用已登录的 TDSUser 授权登录客服系统。
TDS 内建账户服务是 TDS 提供的支持多种登录方式的用户系统。如果你的游戏已经在使用 TapTap 登录、好友、成就、排行榜等服务,你很可能已经在使用 TDS 内建账户了。更多介绍,请参考《内建账户功能介绍》。
要使用 TDSUser 授权登录客服系统,先要使用一个已登录的 TDS 用户账号请求授权 token,然后使用该 token 调用客服模块的 TDS 登录接口:
- Unity
- Android
- iOS
- UE4
try {
string token = await TDSUser.RetrieveShortToken();
await TapSupport.LoginWithTDSCredential(token);
Debug.Log("登录 TDSUser JWT 完成");
} catch (TapException e) {
Debug.LogError($"{e.Code} : {e.Message}");
} catch (Exception e) {
Debug.Log(e);
}
TDSUser.retrieveShortTokenInBackground(tdsUser.getSessionToken()).subscribe(new Observer<JSONObject>() {
@Override
public void onSubscribe(Disposable d) {
}
@Override
public void onNext(JSONObject jsonObject) {
String credential = jsonObject.getString("identityToken");
TapSupport.loginWithTDSCredential(credential, new TapSupport.LoginCallback() {
@Override
public void onComplete(boolean success, Throwable error) {
if (success) {
// 登录成功
} else {
// 登录失败
Log.e("TapSupportActivity", "login:error:" + error.toString());
}
}
});
}
@Override
public void onError(Throwable error) {
// 请求授权 token 失败
}
@Override
public void onComplete() {
}
});
[TDSUser retrieveShortTokenWithCallback:^(NSString *_Nullable token, NSError *_Nullable error) {
if (error) {
// 请求授权 token 失败
} else {
[TapSupport loginWithTDSCredential:token
handler:^(BOOL succcess, NSError *_Nullable error) {
if (succcess) {
// 登录成功
} else {
// 登录失败
}
}];
}
}];
// Todo 1
if (TSharedPtr<FTDSUser> User = FTDSUser::GetCurrentUser())
{
User->RetrieveShortToken(
FStringSignature::CreateLambda([](const FString& Credential)
{
/** 获取Credential成功 */
TapUESupport::LoginWithTDSCredential(
Credential,
FSimpleDelegate::CreateLambda([]()
{
/*** 登录成功 */
}),
FTUError::FDelegate::CreateLambda([](const FTUError& Error)
{
/*** 登录失败 */
}));
}),
FLCError::FDelegate::CreateLambda([](const FLCError& Error)
{
/** 获取Credential失败 */
}));
}