跳到主要内容
版本：v4

客户端接入

介绍​

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

环境要求​

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

权限说明​

集成前准备​

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

SDK 集成​

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

如果只需要单独使用 TapEvent，可以导入依赖 com.taptap.sdk.core。

第一步：添加 SDK 所需的外部依赖​

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

  1. SDK 使用的 JSON 解析库为 Newtonsoft-json，如果当前工程已接入该依赖库，则不需额外处理，否则需在 Packages/manifest.json 添加如下依赖：
"com.unity.nuget.newtonsoft-json":"3.2.1"
  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"
         ]
      }
  ]
}

第二步：添加 SDK 依赖​

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

远程依赖​

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

1. NPMJS 接入​

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

"dependencies":{
  "com.taptap.sdk.core":"4.7.1",
}

但需要注意的是，需在 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.7.1", 
}

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

本地文件导入​

  1. 在 下载页 下载下列模块对应 unitypackage 文件，并在 Unity 项目中依次通过 Assets > Import Packages > Custom Packages 进行导入，包括：
  • TapSDK_Core.unitypackage TapSDK 基础库，必选。
  1. 如果当前项目已集成 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​

在 TapSDK 初始化 时可以配置上报事件所携带的游戏包属性及当前设备的信息，具体使用方式如下：

using TapSDK.Core;

// 核心配置
TapTapSdkOptions coreOptions = new TapTapSdkOptions
{
    // 客户端 ID，开发者后台获取
    clientId = clientId,
    // 客户端令牌，开发者后台获取
    clientToken = clientToken,
    // 地区，CN 为国内，Overseas 为海外
    region = TapTapRegionType.CN,
    // 语言，默认为 Auto，默认情况下，国内为 zh_Hans，海外为 en
    preferredLanguage = TapTapLanguageType.zh_Hans,
    // 游戏版本号，如果不传则默认读取应用的版本号
    gameVersion = "1.1.0",
    // CAID，仅国内 iOS
    caid = "000-000-0000-00000",
    // 是否开启广告商 ID 收集，默认为 false
    enableAdvertiserIDCollection = true,
    // OAID证书, 仅 Android，用于上报 OAID 仅 [TapTapRegion.CN] 生效
    oaidCert = null,
    // 是否开启日志，Release 版本请设置为 false
    enableLog = true,
    // 是否禁用 OAID 反射，默认为 true
    disableReflectionOAID = true
};

//数据分析相关配置
TapTapEventOptions eventOptions =  new TapTapEventOptions
{
    // 渠道，如 AppStore、GooglePlay
    channel = "AppStore",
    // 初始化时传入的自定义参数，会在初始化时上报到 device_login 事件
    propertiesJson = "{\"device_login_custom_key\": \"这是初始化的时候传入的数据，会上报到 device_login 事件\"}",
    // 是否能够覆盖内置参数，默认为 false
    overrideBuiltInParameters = false,
    // 是否开启自动上报 IAP 事件
    enableAutoIAPEvent = true,
    // 是否禁用自动上报设备登录事件，默认为 false
    disableAutoLogDeviceLogin = false
};


TapTapSdkBaseOptions[] otherOptions = new TapTapSdkBaseOptions[]
{
    eventOptions,
    // ... 其他模块配置项
};
TapTapSDK.Init(coreOptions, otherOptions);

字段可为空说明
clientId否客户端 ID，开发者后台获取
clientToken否客户端令牌，开发者后台获取
region否地区，CN 为国内，Overseas 为海外
preferredLanguage是默认为 TapTapLanguageType.Auto, 语言
enableLog是默认为 false, 是否开启日志，Release 版本请设置为 false
channel是渠道，如 AppStore、GooglePlay
gameVersion是游戏版本号，如果不传则默认读取应用的版本号
propertiesJson是初始化时传入的自定义参数，会在初始化时上报到 device_login 事件
caid是CAID，仅国内 iOS
overrideBuiltInParameters是是否能够覆盖内置参数，默认为 false
enableAdvertiserIDCollection是是否开启广告商 ID 收集，仅 iOS ，默认为 false，开启时需添加工程配置
enableAutoIAPEvent是是否开启自动上报 IAP 事件
oaidCert是OAID证书, 仅 Android，用于上报 OAID 仅 [TapTapRegion.CN] 生效
disableReflectionOAID是是否禁用 OAID 反射，默认为 true
disableAutoLogDeviceLogin是是否禁用自动上报设备登录事件，默认为 false

设置账号​

设置账号 ID​

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

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

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

字段可为空说明
userId否账号的唯一字符串，字符串长度不大于 160，只能包含数字、大小写字母、下划线（_）、短横（-）、加号（+）、正斜线（/）、等号（=）、英文句号（.）、英文逗号（,）、英文冒号（:）
开发者需要保证不同账号的 userId 均不相同。
properties是账号登录（ user_login ）的事件属性
using TapSDK.Core

// 自定义属性
var dict = new Dictionary<string, string>();
dict.Add(key, value);
dict.Add(key2, value2);
string properties = dict.toJson();

// 设置用户 ID 及账号登录事件属性
TapTapEvent.SetUserID(userId, properties);

清除账号 ID​

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

using TapSDK.Core

TapTapEvent.ClearUser();

上报充值记录​

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

using TapSDK.Core

TapTapEvent.LogChargeEvent(
   orderID: orderID,
   productName: productName,
   amount: amount,
   currencyType: currencyType,
   paymentMethod: paymentMethod,
   properties: properties
);
字段可为空说明
orderID否订单 ID
productName否产品名称
amount否充值金额（单位分，即无论什么币种，都需要乘以 100）
currencyType否货币类型，遵循 ISO 4217 标准。参考：人民币 CNY，美元 USD；欧元 EUR
paymentMethod否支付方式，如：支付宝
properties否充值（ charge ）的事件属性

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

自定义事件​

上报事件​

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

using TapSDK.Core

var dict = new Dictionary<string, string>
{
  { key, value },
  { key2, value2 }
};
string properties = dict.toJson();
TapTapEvent.LogEvent(name, properties);
字段可为空说明
name否事件的名称
properties否事件的属性 JSONString

注意:

  • 事件名支持上报预置事件和自定义事件，其中自定义事件应以 # 开头
  • 事件属性的 key 值为属性的名称，支持 NSString 类型
  • 事件属性的 value 值为属性的名称，支持 NSString（最大长度 256 ）、NSNumber（取值区间为 [-9E15, 9E15] ）类型
  • 事件属性支持上报预置属性和自定属性，其中自定义属性应以 # 开头
  • 事件属性传入预置属性时，SDK 默认采集的预置属性将不被覆盖， 这个可以再初始化时候修改配置 overrideBuiltInParameters 控制。

设置通用事件属性​

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

添加静态通用事件属性​

using TapSDK.Core

// 添加单个属性
var key = kv["key"];
var value = kv["value"];
TapTapEvent.AddCommonProperty(key, value);

// 添加多个属性
var key = kv["key"];
var value = kv["value"];
var key2 = kv["key2"];
var value2 = kv["value2"];
var dict = new Dictionary<string, string>
{
  { key, value },
  { key2, value2 }
};
string properties = dict.toJson();
TapTapEvent.AddCommon(properties);
字段可为空说明
properties否事件的属性 JSONString

删除部分静态通用事件属性​

using TapSDK.Core

// 删除单个属性
TapTapEvent.ClearCommonProperty(key);

// 删除多个属性
var key1 = kv["key"];
var key2 = kv["value"];
var keysToClear = new string[] { key1, key2 };
TapTapEvent.ClearCommonProperties(keysToClear);

清空全部静态通用属性​

using TapSDK.Core

TapTapEvent.ClearAllCommonProperties();

注册动态通用事件属性​

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

using TapSDK.Core;

// 后续上报的事件都将携带 #currentTime 属性，值为变量 currentTime 在事件上报时刻的值
TapTapEvent.RegisterDynamicProperties(() =>
{
    string currentTime = DateTime.Now.ToString("o");
    Debug.Log("RegisterDynamicProperties currentTime" + currentTime);
    return $"{{ \"currentTime\": \"{currentTime}\" }}";
});

注意:

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

修改用户属性​

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

修改设备属性​

设备属性初始化​

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

using TapSDK.Core;

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

string properties2 = "{\"firstActiveServer\":\"server2\"}";
TapTapEvent.DeviceInitialize(properties2);
// 此时设备表的 "#firstActiveServer" 字段值还是为 "server1"

设备属性更新​

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


using TapSDK.Core;

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

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

设备属性累加​

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

using TapSDK.Core;

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

properties = "{\"totalPoints\":-2}";
TapTapEvent.DeviceAdd(properties);
// 此时设备表的 "totalPoints" 字段值为 8

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

修改账号属性​

账号属性初始化​

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

using TapSDK.Core;

string properties = "{\"firstActive\":\"active\"}";
TapTapEvent.UserInitialize(properties);

账号属性更新​

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

using TapSDK.Core;

string properties = "{\"firstActive\":\"activeNew\"}";
TapTapEvent.UserUpdate(properties);

账号属性累加​

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

using TapSDK.Core;

string properties = "{\"conut\":1}";
TapTapEvent.UserAdd(properties);

收集设备指纹​

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

信息

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

手动设置 OAID（Android 推荐做法）​

我们强烈推荐开发者使用手动设置 OAID 的方式，而不是依赖 SDK 自动获取。这样做可以避免 OAID 相关的兼容性问题，提高稳定性和性能。设置方法如下：

  1. 初始化时禁用相关自动功能：

    • 设置 disableReflectionOAID = true 禁用反射获取 OAID（默认为 true）
    • 设置 disableAutoLogDeviceLogin = true 禁用自动上报设备登录事件（默认为 false）

  2. 手动调用相关 API 完成设置：

using TapSDK.Core

// 手动设置 OAID (仅 Android 平台)
TapTapEvent.SetOAID("your_oaid_value");

// 手动上报设备登录事件
TapTapEvent.LogDeviceLoginEvent();

OAID 自动获取（Android 已废弃）​

注意：为提高兼容性和性能，SDK 默认已禁用自动获取 OAID 功能（disableReflectionOAID = true）。我们强烈推荐使用"手动设置 OAID"的方式。如果您仍需使用自动获取 OAID 功能，可在初始化时设置 disableReflectionOAID = false 开启此功能，但需注意这可能带来兼容性问题。

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. 设置证书信息及配置文件​

证书信息为应用通过 移动安全联盟邮箱 msa@caict.ac.cn 申请的 .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>

在初始化时设置 TapTapSdkOptions 中的 enableAdvertiserIDCollection 为 true 开启 IDFA 采集开关。