跳到主要内容

客户端接入

介绍​

TapSDK 提供了一套可供游戏开发者收集账号数据的 API。 系统会收集账号数据并进行分析，最终形成数据报表，帮助游戏开发者分析账号行为并优化游戏。

环境要求​

  • Unity 2019.4 或更高版本
  • iOS 11 或更高版本，Xcode 版本 14.1 或更高版本
  • Android 5.0（API level 21）或更高版本

权限说明​

集成前准备​

  1. 参考 准备工作 创建应用、开启应用配置开通数据分析服务、绑定 API 域名；

SDK 集成​

请先下载 TapSDK，并添加相关依赖。

如果只需要单独使用 TapDB，可以只导入依赖 common 和 tapdb。

Unity v3.7.1 及更高版本，还需要导入 com.leancloud.storage。

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

但需要注意的是，要在 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.3",
    "com.taptap.tds.tapdb":"https://github.com/TapTap/TapDB-Unity.git#3.29.3",
    "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_Common.unitypackage TapSDK 基础库，必选。
    • TapTap_TapDB.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>

信息

如果你曾使用 <3.6.3 的 TapSDK 的数据分析功能，且初始化时区域选择为国际（IO），那么升级 SDK 至 >=3.6.3 的 TapSDK 前需要先迁移数据。 请提交工单联系我们迁移数据后再升级。

初始化 SDK​

初始化 SDK 并上报一个设备登录（ device_login ）事件，调用这个接口是使用其他接口的先决条件，需要尽早调用。

信息

以下两种初始化方式结合使用场景任选其一即可。

TapSDK 初始化​

如果项目中同时集成内建账户系统的 TapTap 登录并完成了初始化，需要在此基础上添加 TapDBConfig 配置，即可同步初始化 TapDB。代码如下：

using TapTap.Bootstrap; // 命名空间

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.IO)  // 非必须，CN 表示中国大陆，IO 表示其他国家或地区
    .TapDBConfig(true, "gameChannel", "gameVersion", true)  // TapDB 会根据 TapConfig 的配置进行自动初始化
    .ConfigBuilder();

TapBootstrap.Init(config);

TapDBConfig 说明

public Builder TapDBConfig(bool enable, string channel, string gameVersion, bool advertiserIDCollectionEnabled)
参数可为空说明
enable否是否开启 TapDB
channel是分包渠道，长度不大于 256
version是游戏版本，为空时，自动获取游戏安装包的版本，长度不大于 256
advertiserIDCollectionEnabled否IDFA 开关，请参考 收集设备指纹

TapDB 单独初始化​

在单独使用 TapDB 功能时（即不接登录功能时，不导入 TapBootstrap 包时），可以通过以下方式初始化 TapDB。

public static void Init(string clientId, string channel, string gameVersion, bool isCN)

TapDB.Init("clientId", "taptap", "gameVersion", false);
参数可为空说明
clientId否Client Id 可以在控制台获取
channel是分包渠道
version是游戏版本，为空时，自动获取游戏安装包的版本
isCN是区域，true 表示中国大陆，false 表示中国大陆以外的国家或地区。

设置账号​

设置账号 ID​

调用该 API 记录一个账号，当账号登录时调用。

调用后会上报一个账号登录（ user_login ）事件，并将这个设备的是否有用户注册过（ has_user ）属性置为 true。

在重启应用或调用清除账号 ID（ clearUser ）前，上报的事件都会带有该账号 ID。

public static void SetUser(string userId)

TapDB.SetUser("userId");
字段可为空说明
userId否账号的唯一字符串，字符串长度不大于 256，只能包含数字、大小写字母、下划线（_）、短横（-）
开发者需要保证不同账号的 userId 均不相同。

清除账号 ID​

当用户进行登出时，可调用 clearUser 清除当前 SDK 中保存的账号 ID，后续上报的事件将不会带有账号 ID，调用该接口不会上报任何事件。

public static void ClearUser()

TapDB.ClearUser();

设置账号名称​

在用户进行账号登录后，可调用该接口设置该账号的名称，调用后将更新账号的账号名称（ user_name ）属性。

public static void SetName(string name)

TapDB.SetName("Tarara");
参数可为空说明
name否长度大于 0 并小于等于 256，账号名

设置账号等级​

在用户进行账号登录后，可调用该接口设置该账号的等级，调用将更新账号的账号等级（ level ）属性。

public static void SetLevel(int level)

TapDB.SetLevel(5);
参数可为空说明
level否账号等级

设置账号区服​

在用户进行账号登录后，可调用该接口设置该账号的区服信息，调用将初始化账号的首次区服（ first_server ）属性、更新账号的当前区服（ current_server ）属性。

public static void SetServer(string server)

TapDB.SetServer("1 区");
参数可为空说明
server否账号服务器

上报充值记录​

在用户进行充值后，可调用该接口上报充值信息，调用后将上报 charge 事件，并将传入的参数作为事件的属性。

public static void OnCharge(string orderId, string product, long amount, string currencyType, string payment)

public static void OnCharge(string orderId, string product, long amount, string currencyType, string payment,
            string properties)

TapDB.OnCharge("0xueiEns", "轩辕剑", "100", "CNY", "wechat", "{\"on_sell\":true}");
参数可为空说明
orderId否订单 ID
product是产品名称
amount否充值金额（单位分，即无论什么币种，都需要乘以 100）
currencyType是货币类型，遵循 ISO 4217 标准。参考：人民币 CNY，美元 USD；欧元 EUR
payment是支付方式，如：支付宝
properties是充值（ charge ）的事件属性

注意:在条件允许的情况下推荐使用服务端充值统计接口，请参考 服务端接入文档

自定义事件​

上报事件​

在 SDK 初始化完成后可使用该接口上报事件

public static void TrackEvent(string eventName, string properties)

TapDB.TrackEvent("eventName", "{\"weapon\":\"axe\"}");
参数可为空说明
eventName否事件的名称
properties是事件的属性

注意:

  • 事件名支持上报预置事件和自定义事件，其中自定义事件应以 # 开头
  • 事件属性的 key 值为属性的名称，支持 NSString 类型
  • 事件属性的 value 值为属性的名称，支持 NSString（最大长度 256 ）、NSNumber（取值区间为 [-9E15, 9E15] ）类型
  • 事件属性支持上报预置属性和自定属性，其中自定义属性应以 # 开头
  • 事件属性传入预置属性时，SDK 默认采集的预置属性将被覆盖

设置通用事件属性​

对于一些所有事件都要携带的属性，建议使用通用事件属性实现。

添加静态通用事件属性​

public static void RegisterStaticProperties(string staticProperties)

//当设置了静态通用事件属性 #current_channel，值固定为 TapDB 后使用事件上报时，等效于在事件属性中添加了 #current_channel
string properties = "{\"#current_channel\":\"TapDB\"}";
TapDB.RegisterStaticProperties(properties);
字段可为空说明
staticProperties否静态通用事件属性字典

删除单个静态通用事件属性​

public static void UnregisterStaticProperty(string propertyName)

TapDB.UnregisterStaticProperty("#current_channel");
参数可为空说明
propertyName否静态通用属性名

清空全部静态通用属性​

public static void ClearStaticProperties()

TapDB.ClearStaticProperties();

注册动态通用事件属性​

对于可能随时发生变化的通用事件属性，可以注册动态通用事件属性回调，该回调会在每次调用时被触发，将计算好的属性添加到本次上报事件属性中。

public static void RegisterDynamicProperties(IDynamicProperties properties)

// 后续上报的事件都将携带 #currentLevel 属性，值为变量 level 在事件上报时刻的值
public class TapDBDynamicPropertiesImpl : IDynamicProperties
{
        public Dictionary<string, object> GetDynamicProperties()
        {
                Dictionary<string, object> dic = new Dictionary<string, object>();
                dic["#currentLevel"] = level;
                return dic;
        }
}
TapDB.RegisterDynamicProperties(new TapDBDynamicPropertiesImpl());
参数可为空说明
dynamicProperties否动态通用事件属性计算回调

注意:

  • 在上报事件或通用属性中使用相同属性名会出现属性覆盖的现象，属性覆盖的优先级从高到低依次为：事件属性、动态通用事件属性、静态通用事件属性、预置属性（例如 trackEvent 中设置的事件属性将覆盖动态通用事件属性、静态通用事件属性、预置属性中的同名属性）

修改用户属性​

TapDB 支持两种用户主体：设备和账号，你可以通过如下接口对这两种用户的属性进行操作。

修改设备属性​

设备属性初始化​

对于需要保证只有首次设置时有效的属性，可以使用该接口进行赋值操作，仅当前值为空时赋值操作才会生效，如当前值不为空，则赋值操作会被忽略。

public static void DeviceInitialize(string properties)

string properties = "{\"firstActiveServer\":\"server1\"}";
TapDB.DeviceInitialize(properties);
// 此时设备表的 "#firstActiveServer" 字段值为 "server1"

string properties = "{\"firstActiveServer\":\"server2\"}";
TapDB.DeviceInitialize(properties);
// 此时设备表的 "#firstActiveServer" 字段值还是为 "server1"
参数可为空说明
properties否属性字典

设备属性更新​

对于常规的设备属性，可使用该接口进行赋值操作，新的属性值将会直接覆盖旧的属性值。

public static void DeviceUpdate(string properties)

string properties = "{\"currentPoints\":10}";
TapDB.DeviceUpdate(properties);
// 此时设备表的 "currentPoints" 字段值为 10

properties = "{\"currentPoints\":42}";
TapDB.DeviceUpdate(properties);
// 此时设备表的 "currentPoints" 字段值为 42
参数可为空说明
properties否属性字典

设备属性累加​

对于数值类型的属性，可以使用该接口进行累加操作，调用后 TapDB 将对原属性值进行累加后保存结果值

public static void DeviceAdd(string properties)

string properties = "{\"totalPoints\":10}";
TapDB.DeviceAdd(properties);
// 此时设备表的 "totalPoints" 字段值为 10

properties = "{\"totalPoints\":-2}";
TapDB.DeviceAdd(properties);
// 此时设备表的 "totalPoints" 字段值为 8
账号可为空说明
properties否属性字典，value 仅支持数值类型

上述代码示例中，属性值为整数。 累加操作也支持浮点数，不过浮点数相加有精度问题，开发者还需留意。

修改账号属性​

账号属性初始化​

使用方法同设备属性初始化操作

public static void UserInitialize(string properties)

TapDB.UserInitialize(properties);

账号属性更新​

使用方法同设备属性更新操作

public static void UserUpdate(string properties)

TapDB.UserUpdate(properties);

账号属性累加​

使用方法同设备属性累加操作

public static void UserAdd(string properties)

TapDB.UserAdd(properties);

收集设备指纹​

允许 SDK 采集设备指纹用于辅助数据分析、广告归因，将使统计结果更加精确，

信息

请在权限申请、设置 IDFA 开关等操作结束后初始化 SDK，以保证设备指纹能够正常上报。

OAID（Android）​

注意：SDK 版本 3.28.2 及以上支持 OAID 版本为 1.0.5 ~ 2.4.0； 3.15.0 ~ 3.28.0 支持 OAID 版本为 1.0.5 ~ 2.1.0； 3.14.0 及以下支持 OAID 版本为 1.0.5 ~ 1.0.25

TapDB SDK 在应用接入 OAID 第三方库时，会在发送相关事件中携带该参数（key 为 device_id4)。现支持该第三方库版本为 1.0.5 ~ 2.4.0，因不同版本变更较大，所以针对不同版本接入的说明如下：

对于 1.0.5 ~ 1.0.25 不需要额外配置，只需应用添加对应第三方库的依赖即可。

对于 1.0.26 ~ 2.4.0 除添加对应第三方库外，需要添加如下处理：

1. 设置证书信息及配置文件​

证书信息为应用通过 移动安全联盟邮箱 [email protected] 申请的 .cert.pem 文件内容, 该文件与包名对应。现支持两种设置方式：

  1. 将 cert.pem 文件拷贝到应用 assets 目录，并注意该文件名应设置为 packageName.cert.pem , packageName 为当前应用包名。
  2. 通过 SDK 的接口 setOAIDCert 将证书文件的内容进行设置

以上两种方式选择一种即可，当两种同时使用时，优先使用通过接口设置的证书信息。

配置文件为 supplierconfig.json, 应用需要将内部 appid 对应的内容修改为应用在对应应用市场的应用 ID，其他部分不需要修改，并将修改后的文件拷贝到 assets 目录下。

2. 在应用工程中加载对应库文件​

不同版本 OAID 第三方库对应的库文件名称如下：

版本号库名称
1.0.30 ~ 2.4.0msaoaidsec
1.0.29nllvm1632808251147706677
1.0.27nllvm1630571663641560568
1.0.26nllvm1623827671

在 Android 项目工程自定义 Application 类的 onCreate 方法中添加加载第三方库代码，例如当应用接入的 OAID 版本为 1.2.1 时如下：

System.loadLibrary("msaoaidsec");

常见问题处理​

当项目中已引入 OAID 库但上报时仍未发现设备 OAID 信息时，请检查以下几项

  1. 设备时间是否正常
  2. 对于 1.0.26 及以上版本证书所对应的包名是否和当前包名对应
  3. 对于 1.0.26 及以上版本是否加载了其库文件以及库文件名称是否和版本对应
  4. 应用在 Android 12 报错 java.lang.UnsatisfiedLinkError且 应用 minSdkVersion 大于等于 23 ，建议在 AndroidManifest.xml 文件 application 标签中添加 android:extractNativeLibs="true"

IMEI（Android）​

在 AndroidManifest.xml 增加如下条目，且用户同意权限的申请后，SDK 将自动采集 Android IMEI。

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

IDFA（iOS）​

由于 iOS14.5 以上系统，获取 IDFA 需要弹出窗口有用户确认，故 SDK 默认不获取 IDFA，可以调用接口开启 IDFA 获取。

请确保 info.plist 中添加了权限请求描述文字，SDK 在初始化时将自动弹出权限请求窗口。

<key>NSUserTrackingUsageDescription</key>
<string>此标识符将用于向您推荐个性化广告（或其他描述）</string>

若使用 TapSDK 初始化，请在 TapDBConfig 中的 advertiserIDCollectionEnabled 传入 true 开启 IDFA 采集开关。

若单独使用 TapDB SDK 请调用如下接口开启 IDFA 采集开关，为保证数据准确性，该接口应在初始化接口之前调用

TapDB.AdvertiserIDCollectionEnabled(true);

诊断接入​

信息

TapSDK 3.14.0 及以上可接入此功能。

UE4 SDK 暂不支持诊断接入。

添加依赖​

SDK 可以通过 Unity Package Manager 导入或手动导入，二者任选其一。

如果选择 UPM 导入，可以在项目的 Packages/manifest.json 文件中添加：

"dependencies":{
    "com.taptap.tds.common":"https://github.com/TapTap/TapCommon-Unity.git#3.29.3",
    "com.taptap.tds.tapdb": "https://github.com/TapTap/TapDB-Unity.git#3.29.3",
    "com.taptap.tds.themis": "https://github.com/taptap/TapThemis-Unity.git#3.2.3-3",
}

如果选择手动导入：

  • 在 下载页 找到 TapSDK Unity 下载地址，下载 TapSDK-UnityPackage.zip 然后解压，导入其中的 TapTap_Common，TapTap_TapDB模块。

命名空间​

using TapTap.Themis;

启用设置​

在集成 Themis 对应依赖后，TapDB 模块默认会调用 Themis 相关接口，如果游戏需要禁止该调用，可在初始化 TapDB 接口前调用本接口进行关闭。

TapDB.EnableThemis(false);

接口描述​

初始化​

TapThemis.InitTHEMIS();

注意：该接口需要在 TapDB 初始化接口之后调用

设置日志上报等级​

TapThemis.U3d_ConfigAutoReportLogLevel(TapTap.Themis.LogSeverity.LogError);

默认等级为 LogError，当应用日志等级高于设置的等级时会自动上报。

设置异常时是否退出​

TapThemis.U3d_ConfigAutoQuitApplication(true);

设置当发生未捕获的异常时是否自动退出。

注册日志监听​

TapThemis.U3d_UnregisterLogCallback(logcallback);
public void logcallback(string condition, string statckTrace, LogType type ){

}

注册应用日志监听，当应用输出日志时，调用对应回调处理。

移除日志监听​

TapThemis.U3d_UnregisterLogCallback(logcallback);

上报异常​

TapThemis.ReportException(new Exception("Themis crash test from unity"),"crashMessage from untiy");

主动上报异常信息。