小程序/小游戏 SDK 使用指南

来源：好游戏攻略时间：2024-11-26 06:38

最新版本为: 2.0.1

更新时间为: 2021-11-15

下载地址：小程序 (opens new window) , 小游戏 (opens new window)

小程序/小游戏 SDK 为常见小程序平台、快应用、小游戏平台的提供了一套标准的 API 接口以实现数据上报功能。目前，支持的平台及对应的文件如下：

小程序：

微信小程序: thinkingdata.wx.min.js 百度小程序: thinkingdata.swan.min.js 字节跳动小程序: thinkingdata.tt.min.js 支付宝小程序: thinkingdata.my.min.js 钉钉小程序: thinkingdata.dd.min.js 快手小程序: thinkingdata.ks.min.js 快应用: thinkingdata.quick.min.js

小游戏：

微信小游戏: thinkingdata.mg.wx.min.js QQ 小游戏: thinkingdata.mg.qq.min.js 字节跳动小游戏: thinkingdata.mg.tt.min.js 百度小游戏: thinkingdata.mg.swan.min.js 哔哩哔哩小游戏: thinkingdata.mg.bl.min.js 华为快游戏: thinkingdata.mg.huawei.min.js OPPO 快游戏: thinkingdata.mg.oppo.min.js VIVO 快游戏: thinkingdata.mg.vivo.min.js 魅族快游戏: thinkingdata.mg.mz.min.js 小米快游戏: thinkingdata.mg.xiaomi.min.js H5小游戏 UC小游戏 Facebook小游戏

# 一、集成 SDK

下载小程序 SDK (opens new window), 在 app.js 中引入对应的 SDK 文件（以微信小程序为例）:

引入 SDK 之后，您就可以创建 SDK 实例，开始上报数据了：

TA 配置对象参数说明如下：

appId: 您项目的 APP ID，必需, 可以在 TA 后台项目管理页查看 serverUrl: 数据上报 URL，必需如果您使用的是云服务，填入: https://receiver.ta.thinkingdata.cn 如果您使用的是私有化部署的版本，请与运维同学确认上报地址 autoTrack：可选, 表示是否开启自动采集功能，每一个元素分别代表如下的自动采集事件，默认全部关闭： appLaunch：自动采集小程序初始化，一次使用只会触发一次 appShow：自动采集小程序启动，或从后台进入前台 appHide：自动采集小程序从前台进入后台，并记录本次访问（启动至调入后台）的时间 pageShow：自动采集小程序页面显示或切入前台，记录页面路径以及前向路径 pageShare：自动采集小程序进行转发分享，记录转发时的页面

关于自动采集事件的详细信息，可以查看自动采集事件一节

注意在上报数据之前，请先在微信公众平台或其他平台的开发设置中，将数据传输 URL 加入到服务器域名的 request 列表中.

# 二、配置 SDK

如前述示例，您需要调用 init 方法完成 SDK 的初始化：

主动调用初始化方法 init 后，数据才会真正上报。这允许您掌控数据开始上报的时机，确保在数据开始上报之前，您已经完成对 SDK 的必要设置 (用户 ID、公共事件属性等) 。

# 2.1 设置访客 ID

SDK 默认会随机生成一个访客 ID 来标识用户。您可以调用 identify 接口自定义访客 ID:

提示请在 `init` 接口调用完成之前设置好访客 ID. 如果您需要将微信 open ID 作为访客 ID, 可在 open ID 的回调中先调用 `identify` 设置访客 ID, 再调用 `init` 完成

SDK 初始化

# 2.2 设置账号 ID

在用户产生登录行为时，可调用 login 来设置用户的账号 ID. TA 平台优先以账号 ID 作为身份标识 (用户识别规则) ，设置后的账号 ID 将会被保存，多次调用 login 将会覆盖先前的账号 ID：

在用户产生登出行为之后，可调用 logout 来清除账号 ID，在下次调用 login 之前，将会以访客 ID 作为身份识别 ID：

注意

# 2.3 设置公共事件属性

提示公共事件属性是所有[事件](#event)（包括自动采集事件）都会包含的属性，[用户属性](#user)中不会包含。

本节会介绍如何设置公共事件属性和动态公共属性。如果公共属性与事件中设置的自定义属性有相同 key 值，则最终的属性会根据下述优先级取值：

用户自定义事件属性 > 动态公共属性 > 事件公共属性

# 3.3.1 设置事件公共属性

您可以调用setSuperProperties来设置公共事件属性，公共事件属性的格式要求与事件属性一致。在设置时只能传入常量，适合设置变化不频繁的属性。

根据属性优先级，自定义属性优先级高于事件公共属性，因此事件公共属性也可以作为某个属性的缺省值，在需要修改的事件中设置同名 Key 覆盖缺省值。

如果多次调用 setSuperProperties 设置公共事件属性，则同名字段后面的调用会覆盖之前的，不同名字段。

如果您需要删除某个公共事件属性，可以调用 unsetSuperProperty() 清除其中一个公共事件属性；如果您想要清空所有公共事件属性，则可以调用 clearSuperProperties();如果您想要获取所有公共事件属性，可以调用getSuperProperties;

# 3.3.2 设置动态公共属性

可以调用 setDynamicSuperProperties 接口并传入一个回调函数设置动态公共属性。回调函数的返回值将作为公共属性加入到事件属性中：

回调函数必须返回一个 JS 对象，其中每个元素代表一个属性。属性格式要求与事件属性一致。

# 三、发送事件

您可以直接调用track上传自定义事件，建议您根据先前梳理的文档来设置事件的属性以及发送信息的条件，此处以购买商品为范例：

track 接口共有两个参数，第一个参数为事件的名称，第二个参数为事件的属性事件的名称是字符串，只能以字母开头，可包含数字，字母和下划线“_”，长度最大为 50 个字符，对字母大小写不敏感。事件的属性是 JS 对象，每个元素代表一个属性。元素的 name 对应属性的名称，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为 50 个字符，对字母大小写不敏感。元素的 value 为该属性的值，支持String、Number、Boolean、Date 和 Array.

注意: Array 类型属性在 v1.5.0 之后版本支持，需要配合 TA 平台 2.5 及之后的版本.

小程序 SDK 将会在小程序启动（onlaunch）时，获取场景值，如果能取到场景值，则在本次小程序的生命周期中，所有事件都会带有 #scene 场景值这一属性。

# 3.1 设置事件上报时间

事件触发的时间默认取本机时间，但在一些情况下，可能需要手动设置事件的时间，可以使用以下方法进行调用：

第三个参数为事件触发时间，必须是 Date 类型，将会替换事件触发的时间，如果不传该参数，则事件触发时间默认选取用户的本机时间

# 3.2 记录事件时长

您可以调用timeEvent来开始计时，配置您想要计时的事件名称，当您上传该事件时，将会自动在您的事件属性中加入#duration这一属性来表示记录的时长，单位为秒。

# 四、用户属性

# 4.1 设置用户属性（userSet）

对于一般的用户属性，您可以调用userSet来进行设置，使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性

与上传事件时的事件属性一致，此处传入的用户属性也是对象类型，name 对应属性的名称，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为 50 个字符，对字母大小写不敏感，value 为该属性的值，支持String 、Number、Boolean、Date 和 Array.

注意：Array 类型在 v1.5.0 以上版本支持，需要配合 TA 平台 2.5 及之后版本使用.

# 4.2 初始化用户属性（userSetOnce）

如果您要上传的用户属性只要设置一次，则可以调用userSetOnce来进行设置，当该属性之前已经有值的时候，将会忽略这条信息。

userSetOnce 的参数要求与 userSet 一致。

# 4.3 累加用户属性（userAdd）

当您要上传数值型的属性时，您可以调用userAdd来对该属性进行累加操作，如果该属性还未被设置，则会赋值 0 后再进行计算

与上传事件时的事件属性一致，此处传入的用户属性也是对象类型，name 对应属性的名称，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为 50 个字符，对字母大小写不敏感，value 为该属性需要累加的值，只支持Number 类型，传入负数相当于做减法。

# 4.4 重置用户属性（userUnset）

当您要清空用户的某个用户属性值时，您可以调用userUnset来对指定属性进行清空操作，如果该属性还未在集群中被创建，则userUnset不会创建该属性

# 4.5 删除用户（userDel）

如果您要删除某个用户，可以调用userDel将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到

# 4.6 为 Array 类型的用户属性追加元素 (userAppend)

自 v1.5.0 开始，您可以调用 userAppend 对 Array (List) 类型的用户数据追加元素。

注意：该特性需要配合 TA 平台 2.5 及之后版本使用

# 五、自动采集事件

在 1.2.0 版本后，我们提供了自动采集功能，只需在创建实例的 config 中开启您需要自动采集的事件，SDK 将会自动采集小程序的一些行为，现在主要有以下几种事件支持自动采集：

现在支持的自动化收集数据有：

小程序初始化，用户一次使用只会触发一次小程序启动，包括启动与后台调回前台小程序调入后台，并记录本次访问（启动至调入后台）的时间小程序页面显示或切入前台，自动记录页面的路径以及前向路径小程序进行转发分享，自动记录转发时的页面

接下来将会详细介绍每种数据的采集方法

# 5.1 开启自动采集事件

在 config 中，参数autoTrack中的元素表示每个自动采集事件的开关，设置为true为开启自动采集：

appLaunch：自动采集小程序初始化 appShow：自动采集小程序启动，或从后台进入前台 appHide：自动采集小程序从前台进入后台 pageShow：自动采集小程序页面显示或切入前台 pageShare：自动采集小程序进行转发分享

不同平台由于运行环境以及结构原因，支持不同的自动采集事件，支持列表如下：

平台 appLaunch appShow appHide pageShow pageShare 小程序 √ √ √ √ √ 小游戏 √ √

# 5.2 自动采集事件详解

# 5.2.1 小程序初始化

小程序初始化将会在小程序被首次打开时，或用户杀死进程再重新开启时触发，在进程的生命周期内只会触发一次，详细的事件介绍如下：

事件名：ta_mp_launch 自动采集属性： #scene，场景值，取自微信提供的场景值

通过小程序初始化事件，您可以计算每天的用户使用次数、人均使用次数，包括以场景值做分组，查看不同场景值的用户的使用情况。

# 5.2.2 小程序启动

小程序启动将会在小程序被启动、或小程序被从后台调回前台时触发，详细的事件介绍如下：

事件名：ta_mp_show 自动采集属性： #scene，场景值，取自微信提供的场景值 #url_path，页面路径，小程序启动被展示页面的路径

小程序启动由于会受到调出前后台的影响（条数较多），因此不太适合直接进行分析，但是可以在行为路径中标识用户的一次使用，可以作为用户行为路径的初始行为

# 5.2.3 小程序隐藏

小程序隐藏将会在小程序被调入后台时触发，并记录本次使用的时长，详细的事件介绍如下：

事件名：ta_mp_hide 自动采集属性： #scene，场景值，取自微信提供的场景值 #duration，数值型，表示本次启动（ta_mp_show）到隐藏的持续时长

小程序隐藏事件会记录使用时长（单位为秒），因此可以直接计算用户使用总时长以及人均时长，也可以除以初始化次数计算单次使用时长。

# 5.2.4 小程序页面浏览

小程序页面浏览将会在小程序的页面被打开时，或小程序从后台调回前台的页面展示时触发，会记录页面的路径以及访问的前向路径，详细的事件介绍如下：

事件名：ta_mp_view 自动采集属性： #scene，场景值，取自微信提供的场景值 #url_path，页面路径，也就是被展示页面的路径 #referrer，前向路径，被展示页面之前页面的路径，也就是跳转前路径，如果是启动小程序时展示的首页，则取值为“直接打开”

通过小程序页面浏览事件，您可以计算每个页面的 pv、uv，以及用户访问小程序的使用路径。

# 5.2.5 小程序页面转发分享

小程序页面转发分享将会在转发按钮被点击时触发（包括右上角导航栏的转发按钮，以及页面中的转发按钮），详细的事件介绍如下：

事件名：ta_mp_share 自动采集属性： #scene，场景值，取自微信提供的场景值 #url_path，页面路径，也就是转发时所在的页面路径

小程序页面转发分享事件，适合对页面的分享率进行分析，可以帮助您优化页面转发。

# 六、其他功能

# 6.1 多实例

从 v1.3.0 开始，本 SDK 支持多实例。我们称通过上文描述的方法完成初始化的实例 ta 为主实例，通过本节描述的方法创建的实例为子实例。

多个实例之间共享设备相关的预置属性（包括设备 ID），其他的属性均不共享，包括：

#distinct_id 访客 ID #account_id 账号 ID 公共事件属性、动态公共属性 timeEvent 监控的事件

您可以通过创建子实例，向另一个项目中上报数据，或者以另一套用户 ID 上报数据。

# 6.2 获取设备 ID

您可以调用getDeviceId()获取设备 ID，由于运行环境的原因，设备 ID 会保存在本地缓存，一旦用户删除缓存，则设备 ID 将会变更，因此设备 ID 不能保证稳定不变

# 6.3 onCompelete 回调函数

从 v1.3.1 开始，对于 track, userSet, userSetOnce, userAdd, userDel 等接口，支持传入 onComplete 回调. 可以直接在原参数列表后传入 onComplete, 也可以使用参数对象的方式. 如果使用参数对象，参数对象中必须包含 onComplete, 否则会出现参数错误.

以上传事件为例：

onComplete 的参数 res 为 object 类型，有两个属性 code 和 msg.

res.code 为 int 类型，定义如下:

0: 成功 -1: 数据格式不正确 -2: APP ID 无效 -3: 网络或服务端异常

Debug 模式定义如下:

0: 成功 -1: 参数或者权限校验的问题 1: 表示字段基本的错误, 会给出详细的错误字段和原由 2: 表示整条错误 -3: 网络或服务端异常

res.msg 是对 res.code 的文字说明。

# 6.4 开启 Debug 模式

从 v1.6.0 版本开始，客户端 SDK 支持 Debug 模式，需要配合 TA 平台 2.5 之后的版本使用。

Debug 模式可能会影响数据采集质量和 App 的稳定性，只用于集成阶段数据验证，不要在线上环境使用。

当前 SDK 实例支持三种运行模式：

"none": 不开启 Debug "debug": 开启 Debug 模式，并入库 "debugOnly": 开启 Debug 模式，不入库

SDK 初始化：

为了避免 Debug 模式在生产环境上线，规定只有指定的设备才能开启 Debug 模式。只有在客户端开启了 Debug 模式，并且设备 ID 在 TA 后台的"埋点管理"页的"Debug 数据"板块中配置了的设备才能开启 Debug 模式。

设备 ID 可以通过以下三种方式获取：

TA 平台中事件数据中的 #device_id 属性通过实例接口调用：获取设备 ID

# 七、相关预置属性

# 7.1 所有事件带有的预置属性

以下预置属性，是小程序/小游戏 SDK 中所有事件（包括自动采集事件）都会带有的预置属性

属性名中文名说明 #ip IP 地址用户的 IP 地址，TA 将以此获取用户的地理位置信息 #country 国家用户所在国家，根据 IP 地址生成 #country_code 国家代码用户所在国家的国家代码(ISO 3166-1 alpha-2，即两位大写英文字母)，根据 IP 地址生成 #province 省份用户所在省份，根据 IP 地址生成 #city 城市用户所在城市，根据 IP 地址生成 #device_model 设备型号用户设备的型号，如 iPhone 8 等 #device_id 设备 ID 用户的设备 ID，取初始化时生成的 UUID #screen_height 屏幕高度用户设备的屏幕高度，如 1920 等 #screen_width 屏幕宽度用户设备的屏幕高度，如 1080 等 #manufacturer 设备制造商用户设备的制造商，如 Apple，vivo 等 #os_version 操作系统版本 iOS 11.2.2、Android 8.0.0 等 #os 操作系统如 Android、iOS 等 #network_type 网络状态上传事件时的网络状态，如 WIFI、3G、4G 等 #lib SDK 类型您接入 SDK 的类型，如 MP（小程序）、MG（小游戏）等 #lib_version SDK 版本您接入 SDK 的版本 #scene 场景值微信小程序启动时传入的场景值 #mp_platform 小程序平台标识应用所在的平台 #zone_offset 时区偏移数据时间相对 UTC 时间的偏移小时数

# 7.2 自动采集事件的预置属性

以下预置属性，是各个自动采集事件中所特有的预置属性

小程序启动（ta_mp_show）的预置属性属性名中文名说明 #url_path 页面路径小程序启动被展示页面的路径小程序隐藏（ta_mp_hide）的预置属性属性名中文名说明 #duration 事件时长表示本次启动ta_mp_show到隐藏ta_mp_hide的持续时长，单位是秒小程序页面浏览（ta_mp_view）的预置属性属性名中文名说明 #url_path 页面路径页面路径，也就是被展示页面的路径 #referrer 前向路径被展示页面之前页面的路径，也就是跳转前路径，如果是启动小程序时展示的首页，则取值为“直接打开” 小程序页面转发分享（ta_mp_share）的预置属性属性名中文名说明 #url_path 页面路径小程序被转发时所在的页面路径

# 7.3 获取预制属性

服务端埋点需要 App 端的一些预置属性时，可以通过此方法获取客户端端的预置属性，再传给服务端。

IP，国家城市信息由服务端解析生成，客户端不提供接口获取这些属性

# 八、进阶功能

从 v1.7.0 开始，SDK 支持上报三种特殊类型事件: 首次事件、可更新事件、可重写事件。这三种事件需要配合 TA 系统 2.8 及之后的版本使用。由于特殊事件只在某些特定场景下适用，所以请在数数科技的客户成功和分析师的帮助下使用特殊事件上报数据。

# 8.1 首次事件

首次事件是指针对某个设备或者其他维度的 ID，只会记录一次的事件。例如在一些场景下，您可能希望记录在某个设备上第一次发生的事件，则可以用首次事件来上报数据。

如果您希望以设备以外的其他维度来判断是否首次，则可以为首次事件设置 FIRST_CHECK_ID. 例如您需要记录某个账号的首次事件，可以将账号 ID 设置为首次事件的 FIRST_CHECK_ID:

注意：由于在服务端完成对是否首次的校验，首次事件默认会延时 1 小时入库。

# 8.2 可更新事件

您可以通过可更新事件实现特定场景下需要修改事件数据的需求。可更新事件需要指定标识该事件的 ID，并在创建可更新事件对象时传入。TA 后台将根据事件名和事件 ID 来确定需要更新的数据。

# 8.3 可重写事件

可重写事件与可更新事件类似，区别在于可重写事件会用最新的数据完全覆盖历史数据，从效果上看相当于删除前一条数据，并入库最新的数据。TA 后台将根据事件名和事件 ID 来确定需要更新的数据。

# Release Notes

v2.0.1 2021/11/15

代码优化

v2.0.0 2021/09/15

支持暂停/开始、停止/恢复数据上报支持事件黑名单代码优化

v1.8.2 2021/06/24

支持预制属性获取

v1.8.1 2021/03/08

新增快手小程序的支持

v1.8.0 2020/11/20

新增哔哩哔哩小游戏、小米小游戏、H5 游戏的支持完善游戏引擎支持：支持 ts 项目接入完善游戏引擎支持：支持常见小游戏、快游戏平台(华为、小米、OPPO、VIVO)、H5 游戏其他代码细节层面的优化

v1.7.1 2020/08/27

支持魅族平台

v1.7.0 2020/08/24

支持首次事件，可更新事件，可重写事件

v1.6.2 2020/07/23

支持钉钉小程序修复华为快游戏上报异常问题

v1.6.1 2020/07/10

支持华为快游戏

v1.6.0 2020/06/10

支持 debug 模式

v1.5.0 2020/02/10

属性值支持 Array 类型新增 userAppend 接口去除本地属性值检查

v1.4.4 2019/12/24

修复 VIVO 和 OPPO 平台首次 appHide 没有计时

v1.4.3 2019/12/20

优化 OPPO 快游戏网络请求

v1.4.2 2019/11/20

支持 OPPO、VIVO 快游戏

v1.4.0 2019/10/22

新增userUnset接口，可用于清空一个用户属性新增预置属性#zone_offset，单位为小时。默认情况下会将本地时区的偏移上报到服务端，该时间偏移会受夏令时影响。满足如下公式：

v1.3.2 2019/09/29

修复 v1.3.1 引入的部分平台的兼容性问题

v1.3.1 2019/09/27

track, userSet, userSetOnce, userAdd, userDel 接口添加回调函数

v1.3.0 2019/08/15

代码优化 #network_type 属性根据网络状态更新数据发送内容：用户属性数据不传送预置属性，简化发送内容优化日志打印新增接口 getAccountId() getDistinctId() timeEvent() initInstance() identify() 同 authorizeOpenID() getDeviceId() getSuperProperties() unsetSuperProperty() setDynamicSuperProperties() 多实例通过调用 initInstance(name, config) 可以创建新的实例. 子实例默认使用父实例的配置，默认情况下不启用本地缓存配置信息 enablePersistence 父实例默认为 true，子实例默认为 false asyncPersistence 异步读取缓存 maxRetries 当请求失败或超时时的重试次数, 默认为 3 次 sendTimeout 超时时间，单位为毫秒 enableLog 是否打开日志打印跨平台支持主流小程序小游戏平台：微信、百度、支付宝、字节跳动、快应用增加预置属性 #mp_platform，标识应用所在的平台 #lib 为 MP/MG，分别代表小程序和小游戏

小程序/小游戏 SDK 使用指南

# 一、集成 SDK