微信小程序 SDK 使用指南

本指南将会为您介绍如何使用微信小程序SDK接入您的项目，建议在接入开始前，先阅读数据规则一章，在了解TA数据规则后再进行接入。

最新版本为：1.2.2

更新时间为：2019-05-13

微信小程序 SDK已停止后续开发，项目转移至小程序\小游戏 SDK，本文档仅供老版本的用户进行参考

1. 引入微信小程序SDK

1.下载微信小程序 SDK

2.解压压缩包，并把thinkingdata.js与thinkingdata_conf.js置入您的项目中，本文档以置入utils文件夹为例

3.配置thinkingdata_conf.js里的参数：

var conf = {
  appid: APPID,
  server_url: APPURL,
  max_string_length: 100,
  // is_plugin: true,
  // autoTrack: {
  //   appLaunch: true,
  //   appShow: true, 
  //   appHide: true, 
  //   pageShow: true, 
  //   pageShare: true
  // }
};

• APP_ID是您的项目的APP_ID，需要进行配置，在您申请项目时会给出，请在此处填入
• serverUrl为上传数据的URL，需要进行配置
• max_string_length为传入的字符串最大长度限制，默认为100
• is_plugin表示您的小程序是否使用了插件，如果使用了插件，请将其设置为true，并且查看使用插件时的注意事项一节，默认为false即未使用插件
• autoTrack表示是否开启自动采集功能，每一个元素分别代表如下的自动采集事件，默认全部关闭：
  • appLaunch：自动采集小程序初始化，一次使用只会触发一次
  • appShow：自动采集小程序启动，或从后台进入前台
  • appHide：自动采集小程序从前台进入后台，并记录本次访问（启动至调入后台）的时间
  • pageShow：自动采集小程序页面显示或切入前台，记录页面路径以及前向路径
  • pageShare：自动采集小程序进行转发分享，记录转发时的页面

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

如果您使用的是云服务，请使用以下传输URL:

https://receiver.ta.thinkingdata.cn

如果您使用的是私有化部署的版本，由于微信的服务器域名中不能出现端口号，因此需要您自行配制域名，绑定TA私有化服务器的接收端。

2.载入微信小程序SDK

请在app.js中引入小程序SDK，本文档以SDK置入utils文件夹为例

require('./utils/thinkingdata.js');

在其他页面中可使用getApp()方法取得小程序实例，即可调用SDK的各方法：

var app = getApp();
app.thinkingdata.login("thinkingdata");
app.thinkingdata.init();

使用插件时的注意事项

如果您的小程序中使用了插件，则需要做以下特殊处理：

1. 在thinkingdata_conf.js文件中的 is_plugin设置为true

2. 请在app.js中引入小程序SDK，本文档以SDK置入utils文件夹为例

   var thinking = require('./utils/thinkingdata.js');
   var App = thinking.App;
   app.thinkingdata.init();
   

3. 请在每个page中的开头添加以下语句：

   var Page = getApp().thinkingdata.Page;
   

3. 初始化SDK以及标识用户

a) 初始化SDK

在SDK载入完成之后，需要显现调用初始化接口init完成SDK的初始化。

var App = thinking.App;
app.thinkingdata.init();

只有当调用init之后，数据才会被上报，在调用init之前触发的数据（包括自动采集数据），将会被暂存，直到init被调用时才会上报，这些数据的时间为埋点触发时间，而非init被调用的时间（即上报时间）

app.thinkingdata.authorizeOpenID('authorizeOpenID');
app.thinkingdata.login("ABC_123456");
app.thinkingdata.setSuperProperties({"channel": "渠道"});

//先设置ID以及公共属性再初始化
app.thinkingdata.init();

b) 标识用户

SDK将会自动生成一个ID作为每个用户的默认访客ID，该ID将会作为用户在未登录状态下的身份识别，如果您希望以微信的openid作为用户标识，可使用authorizeOpenID设置。如果您的用户存在账号ID，请使用login设置用户的账号ID。

1) 传入OpenID

如果您希望以微信的openid作为用户标识，则可以使用以下方法将openid作为用户标识：

//传入值为openid
app.thinkingdata.authorizeOpenID('authorizeOpenID');

需要注意以下几点：

1. 设置后的OpenID将会被设置为访客ID#distinct_id，如果使用login传入账号ID，则根据用户识别规则，会优先以账号ID为准
2. 如果需要传入OpenID，请在上传数据之前调用本方法，以免出现重复计算用户的现象
3. 如果需要进行设置，建议在初始化之前调用本接口

2) 设置账号ID

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

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

//再次调用login调整账号ID，此时"#account_id"的值为"XYZ_987654"
app.thinkingdata.login("XYZ_987654");

请注意，该方法不会上传用户登录的事件

3) 清除账号ID

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

//去除上报数据里的#account_id，之后的数据将不带有"#account_id"
app.thinkingdata.logout();

请注意，该方法不会上传用户登出的事件

4. 发送事件

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

app.thinkingdata.track(
   'Purchase',              //追踪事件的名称
    {
        'Item':'商品A',
        'ItemNum':1,
        'Cost':100
    }                       //需要上传的事件属性
);

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

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

4.1 设置事件上报时间

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

//第三个参数，可以输入Date类型的参数，替换事件触发时间
app.thinkingdata.track('event', {"parakey":"paravalue"}, new Date());

//如果没有properties需要上传，请传入一个空对象
app.thinkingdata.track('event', {}, new Date());

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

4.2 设置公共事件属性

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

• 公共事件属性是一个JSONObject对象，其中每个元素代表一个属性。
• Key的值为属性的名称，为String类型，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为50个字符，对字母大小写不敏感。
• Value为该属性的值，支持String、Number、Boolean和Date。

//设置公共事件属性
app.thinkingdata.setSuperProperties({ 'channel': '渠道'});

//使用track上传事件，此时事件中会带有公共事件属性
app.thinkingdata.track(
   'Purchase',              //追踪事件的名称
    {
        'Item':'商品A',
        'ItemNum':1,
        'Cost':100
    }                       //需要上传的事件属性
);

/* 等价于在事件中加入这些公共属性
app.thinkingdata.track(
    'Purchase', //追踪事件的名称
    {
        'Item':'商品A',
        'ItemNum':1,
        'Cost':100,
        'channel':'渠道' //相当于在事件中加入这个属性
    } 
);
*/

如果多次调用setSuperProperties设置公共事件属性，则同名字段后面的调用会覆盖之前的，不同名字段。如果公共事件属性和track上传的某个属性的Key重复，则该事件的属性会覆盖公共事件属性。

如果您需要清除公共事件属性，可以调用clearSuperProperties将所有公共属性清除。

app.thinkingdata.clearSuperProperties();

5. 用户属性

a) 设置用户属性（userSet）

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

//设置用户属性，会员等级
app.thinkingdata.userSet({vip_level:'钻石会员'});

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

b) 初始化用户属性（userSetOnce）

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

//以设置用户名为例，如果用户名已设置，则忽略本次设置，如果不存在，则设置为传入值
app.thinkingdata.userSetOnce({UserName:'TA'});

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

c) 累加用户属性（userAdd）

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

//以付费为例，用户每次付费时调用此接口，则'total_revenue'字段每次会做累加付费金额的处理
app.thinkingdata.userAdd({total_revenue:50});

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

d) 删除用户（userDel）

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

app.thinkingdata.userDel();

6. 自动采集事件

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

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

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

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

6.1 开启自动采集事件

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

var conf = {
  appid: APPID,
  server_url: APPURL,
  max_string_length: 100,
  is_plugin: false,
  autoTrack: {
    appLaunch: true,
    appShow: true,
    appHide: true,
    pageShow: true,
    pageShare: true
  }
};

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

6.2 自动采集事件详解

6.2.1 小程序初始化

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

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

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

6.2.2 小程序启动

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

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

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

6.2.3 小程序隐藏

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

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

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

6.2.4 小程序页面浏览

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

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

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

6.2.5 小程序页面转发分享

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

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

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

7. 相关预置属性

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

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

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

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

• 小程序启动（ta_mp_show）的预置属性

• 小程序隐藏（ta_mp_hide）的预置属性

• 小程序页面浏览（ta_mp_view）的预置属性

• 小程序页面转发分享（ta_mp_share）的预置属性

ChangeLog

v1.2.2 2019/05/13

• 修复了极端情况下，访客ID可能为空的问题

v1.2.1 2019/04/22

• 增加了公共事件属性的接口：setSuperProperties、clearSuperProperties

v1.2.0（重大更新） 2019/04/18

• 初始化方式改动，增加了初始化接口init，在init调用前触发的事件，将会被缓存于消息队列，init调用时，会将#account_id与#distinct_id同步到消息队列的数据中，并发送这些数据
• 增加自动采集功能
• track接口添加了设置事件触发时间的重载
• 添加了对包含插件的小程序的支持

v1.1.1 2019/01/08

• 修复了PageView误报的问题

v1.1.0 2018/07/06

• 微信小程序SDK上线，提供接口：track、authorizeOpenID、login、logout、userSet、userSetOnce、userAdd、userDel