小程序&小游戏

最近更新 2026/10/05

提示

在接入前, 请先阅读接入前准备。

如果您使用游戏引擎开发小游戏，请阅读常用游戏引擎的集成方案：Egret 白鹭引擎、 LayaAir、 CocosCreator.

最新版本: v3.8.1 下载(小程序) 下载(小游戏)

更新时间: 2026-09-29

资源下载: 源代码

注意

当前文档适用于 v3.0.0 及以后的版本，历史版本请参考小程序&小游戏接入指南（V2），小程序SDK下载（v2.2.4）、小游戏SDK下载（v2.2.4）

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

小程序：

微信小程序: tdanalytics.wx.min.js
百度小程序: tdanalytics.swan.min.js
抖音小程序: tdanalytics.tt.min.js
支付宝小程序: tdanalytics.my.min.js
钉钉小程序: tdanalytics.dd.min.js
快手小程序: tdanalytics.ks.min.js
快应用: tdanalytics.quick.min.js
QQ小程序：tdanalytics.qq.min.js
京东小程序：tdanalytics.jd.min.js
360小程序：tdanalytics.qh.min.js

小游戏：

微信小游戏: tdanalytics.mg.wx.min.js
QQ 小游戏: tdanalytics.mg.qq.min.js
抖音小游戏: tdanalytics.mg.tt.min.js
百度小游戏: tdanalytics.mg.swan.min.js
哔哩哔哩小游戏: tdanalytics.mg.bl.min.js
华为快游戏: tdanalytics.mg.huawei.min.js
OPPO 快游戏: tdanalytics.mg.oppo.min.js
VIVO 快游戏: tdanalytics.mg.vivo.min.js
魅族快游戏: tdanalytics.mg.mz.min.js
荣耀快游戏：tdanalytics.mg.honor.min.js
小米快游戏: tdanalytics.mg.xiaomi.min.js
淘宝小游戏：tdanalytics.mg.tb.min.js
快手小游戏：tdanalytics.mg.ks.min.js
支付宝小游戏：tdanalytics.mg.my.min.js
美团小游戏：tdanalytics.mg.mt.min.js
京东小游戏：tdanalytics.mg.jd.min.js
H5小游戏
UC小游戏
Facebook小游戏

一、集成 SDK

小程序
快应用
小游戏

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

var TDAnalytics = require("./tdanalytics.wx.min.js");

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

// AE SDK 配置对象
var config = {
  appId: "YOU-APP-ID", // 项目的 APP ID
  serverUrl: "https://youserverurl.com", // 数据上报地址
  autoTrack: {
    appLaunch: true, // 自动采集 ta_mp_launch
    appShow: true, // 自动采集 ta_mp_show
    appHide: true, // 自动采集 ta_mp_hide
    pageShow: true, // 自动采集 ta_mp_view
    pageShare: true // 自动采集 ta_mp_share
  }
};

// 初始化
TDAnalytics.init(config);

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

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

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

下载小程序 SDK, 在 app.ux 中引入对应的 SDK

文件 tdanalytics.quick.min.js:

var TDAnalytics = require("./tdanalytics.quick.min.js");

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

// AE SDK 配置对象
var config = {
  appId: "YOU-APP-ID", // 项目的 APP ID
  serverUrl: "https://youserverurl.com", // 数据上报地址
  persistenceComplete(ta) {
    // 异步存储初始化完成时的回调，可以做一些与缓存相关的删除操作
    //TDAnalytics.clearSuperProperties();
  }
};

// 初始化
TDAnalytics.init(config);

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

appId: 您项目的 APP ID，必需, 可以在 AE 后台项目管理页查看
serverUrl: 数据上报 URL，必需
- 如果您使用的是云服务，填入: https://global-receiver-ta.thinkingdata.cn
- 如果您使用的是私有化部署的版本，请与运维同学确认上报地址
persistenceComplete: 可选。快应用缓存是异步读取的，因此完成缓存读取前，对缓存相关的字段进行查询、删除操作将会出现与预期不符的情况，为了保证在初始化阶段的缓存查询与删除能够正确执行，需要在

persistenceComplete 回调中完成相关操作。缓存相关数据包括：用户 ID（#account_id 与#distinct_id），设备 ID，公共事件属性等。

persistenceComplete 的进一步说明:

针对异步调用导致的 SDK 状态问题，我们为每个实例设置了 Ready 状态。当以下条件全部满足时，我们认为实例已经 Ready:

获取系统信息完成：我们通过调用平台提供的 getSystemInfo() 获取系统信息
缓存信息读取完成：快应用是异步读取缓存
用户主动调用了 TDAnalytics.init()

当实例未进入 Ready 状态，我们会缓存所有上报的数据，等待实例初始化完成后，会清空缓存，以此保证状态正确。

在异步读取缓存的不同阶段，需要特别注意下面的说明：

在缓存信息未读取的时候，可以设置公共属性、登录账户。
当缓存读取完成时，我们会用新的值覆盖之前在缓存中的值。
在缓存读取完成之前，调用涉及删除或读取之前缓存的一些信息的函数，则无法读取或删除实际缓存中的数据。

针对上述第 3 点，可以通过在初始化时传入回调函数 (即 persistenceComplete) 来保证调用顺序。

注意：快应用暂不支持自动采集事件

下载小游戏 SDK, 在 game.js 中引入对应的 SDK 文件（以微信小游戏为例）:

var TDAnalytics = require("./tdanalytics.mg.wx.min.js");

// AE SDK 配置对象
var config = {
  appId: "YOUR_APPID", // 项目 APP ID
  serverUrl: "YOUR_SERVER_URL", // 上报地址
  autoTrack: {
    appShow: true, // 自动采集 ta_mg_show
    appHide: true // 自动采集 ta_mg_hide
  }
};
// 初始化
TDAnalytics.init(config);

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

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

注意

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

二、常用功能

在使用常用功能之前，建议你先了解用户识别规则。SDK默认会生成随机数作为访客ID，并持久化存储访客ID在本地，用户未登录之前，会以访客ID作为身份识别ID。注意:访客 ID 在用户清理缓存以及更换设备时将会变更。

2.1 设置账号ID

在用户进行登录时，可调用 login 来设置用户的账号 ID， AE 平台将会以账号 ID 作为身份识别 ID，并且设置的账号 ID 将会在调用 logout 之前一直保留。多次调用 login 将覆盖先前的账号 ID

// 用户的登录唯一标识，此数据对应上报数据里的#account_id，此时#account_id的值为TA
TDAnalytics.login("TA");

该方法不会上传登录事件

2.2 设置公共事件属性

公共事件属性指的就是每个事件都会带有的属性，您可以调用 setSuperProperties 来设置公共事件属性，我们推荐您在发送事件前，先设置公共事件属性。对于一些重要的属性，譬如用户的会员等级、来源渠道等，这些属性需要设置在每个事件中，此时您可以将这些属性设置为公共事件属性。

var superProperties = {
    channel : "ta",
    age : 1,
    isSuccess : true,
    birthday :  new Date(),
    object : { key : "value" },
    object_arr : [ { key : "value" } ],
    arr : [ "value" ]
};
TDAnalytics.setSuperProperties(superProperties);

公共事件属性将会被保存到缓存中，无需每次启动时调用。如果调用 setSuperProperties 上传了先前已设置过的公共事件属性，则会覆盖之前的属性。

Key 为该属性的名称，为字符串类型，规定只能以字母开头，包含数字，字母和下划线 "_"，长度最大为 50 个字符，对字母大小写不敏感，AE 会统一转化为小写字母
Value 为该属性的值，支持字符串、数字、布尔、时间、对象、对象组、数组

事件属性、用户属性的要求与公共事件属性保持一致

2.3 发送事件

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

TDAnalytics.track({
    eventName: "product_buy", // 事件名称
    properties: {
        product_name: "商品名"
    } //事件属性
});

事件的名称是字符串类型，只能以字母开头，可包含数字，字母和下划线 "_"，长度最大为 50 个字符。

2.4 设置用户属性

对于一般的用户属性，您可以调用 userSet 来进行设置，使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性，类型与传入属性的类型一致，此处以设置用户名为例：

//此时username为TA
TDAnalytics.userSet({
    properties: {
        username: "TA"
    }
});
//此时username为AE
TDAnalytics.userSet({
    properties: {
        username: "AE"
    }
});

三、最佳实践

以下示例代码包含以上所有操作，我们推荐按照如下步骤使用

小程序
快应用
小游戏

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

var TDAnalytics = require("./tdanalytics.wx.min.js");
var config = {
  appId: "YOU-APP-ID", // 项目的 APP ID
  serverUrl: "https://youserverurl.com", // 数据上报地址
  autoTrack: {
    appLaunch: true, // 自动采集 ta_mp_launch
    appShow: true, // 自动采集 ta_mp_show
    appHide: true, // 自动采集 ta_mp_hide
    pageShow: true, // 自动采集 ta_mp_view
    pageShare: true // 自动采集 ta_mp_share
  }
};
// 初始化
TDAnalytics.init(config);
// 用户的登录唯一标识，此数据对应上报数据里的#account_id，此时#account_id的值为TA
TDAnalytics.login("TA");
//设置公共事件属性
var superProperties = {
    channel : "ta", //字符串
    age : 1,//数字
    isSuccess : true,//布尔
    birthday :  new Date(),//时间
    object : { key : "value" },//对象
    object_arr : [ { key : "value" } ],//对象组
    arr : [ "value" ]//数组
};
TDAnalytics.setSuperProperties(superProperties);
//发送事件
TDAnalytics.track({
    eventName: "product_buy", // 事件名称
    properties: {
        product_name: "商品名"
    } //事件属性
});
//设置用户属性
TDAnalytics.userSet({
    properties: { 
        username: "AE" 
    }
});

在 app.ux 中引入对应的 SDK（ tdanalytics.quick.min.js）

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

var TDAnalytics = require("./tdanalytics.quick.min.js");
// AE SDK 配置对象
var config = {
  appId: "YOU-APP-ID", // 项目的 APP ID
  serverUrl: "https://youserverurl.com", // 数据上报地址
  persistenceComplete(ta) {
    // 异步存储初始化完成时的回调，可以做一些与缓存相关的删除操作
    //TDAnalytics.clearSuperProperties();
  }
};
// 初始化
TDAnalytics.init(config);
// 用户的登录唯一标识，此数据对应上报数据里的#account_id，此时#account_id的值为TA
TDAnalytics.login("TA");
//设置公共事件属性
var superProperties = {
    channel : "ta", //字符串
    age : 1,//数字
    isSuccess : true,//布尔
    birthday :  new Date(),//时间
    object : { key : "value" },//对象
    object_arr : [ { key : "value" } ],//对象组
    arr : [ "value" ]//数组
};
TDAnalytics.setSuperProperties(superProperties);
//发送事件
TDAnalytics.track({
    eventName: "product_buy", // 事件名称
    properties: {
        product_name: "商品名"
    } //事件属性
});
//设置用户属性
TDAnalytics.userSet({
    properties: {
        username: "AE" 
    }    
});

在 game.js 中引入对应的 SDK 文件（以微信小游戏为例），引入 SDK 之后，您就可以创建 SDK 实例，开始上报数据了：

var TDAnalytics = require("./tdanalytics.mg.wx.min.js");
var config = {
  appId: "YOUR_APPID", // 项目 APP ID
  serverUrl: "YOUR_SERVER_URL", // 上报地址
  autoTrack: {
    appShow: true, // 自动采集 ta_mg_show
    appHide: true // 自动采集 ta_mg_hide
  }
};
//初始化
TDAnalytics.init(config);
// 用户的登录唯一标识，此数据对应上报数据里的#account_id，此时#account_id的值为TA
TDAnalytics.login("TA");
//设置公共事件属性
var superProperties = {
    channel : "ta", //字符串
    age : 1,//数字
    isSuccess : true,//布尔
    birthday :  new Date(),//时间
    object : { key : "value" },//对象
    object_arr : [ { key : "value" } ],//对象组
    arr : [ "value" ]//数组
};
TDAnalytics.setSuperProperties(superProperties);
//发送事件
TDAnalytics.track({
    eventName: "product_buy", // 事件名称
    properties: {
        product_name: "商品名"
    } //事件属性
});
//设置用户属性
TDAnalytics.userSet({
    properties: {
        username: "AE"
    }
});

这篇文档对你有帮助吗？

一、集成 SDK​

二、常用功能​

2.1 设置账号ID​

2.2 设置公共事件属性​

2.3 发送事件​

2.4 设置用户属性​

三、最佳实践​

一、集成 SDK

二、常用功能

2.1 设置账号ID

2.2 设置公共事件属性

2.3 发送事件

2.4 设置用户属性

三、最佳实践