JavaScript SDK 使用指南

本指南将会为您介绍如何使用 JavaScript SDK 接入您的项目，建议在接入开始前，先阅读数据规则一章，在了解TA数据规则后再进行接入。您可以在访问 GitHub 获取 JavaScript SDK 的源代码。

最新版本为： v1.4.0

更新时间为： 2020-08-25

下载地址

1. 引入 JavaScript SDK

1.下载 JavaScript SDK

压缩包中提供了两种规范的脚本，您可以根据需要选择所需的脚本。下文描述的异步载入，需要使用 thinkingdata.min.js 文件；同步载入需要使用 thinkingdata.umd.min.js.

2.载入 JavaScript SDK

您可以选择异步载入或者同步载入的方式使用 SDK. 两种方式在实际使用中区别不大，可以任选其一。

在初始化 SDK 的时候需要传入一些配置参数:

• appId: 您的项目的 APP_ID，需要进行配置，在您申请项目时会给出，请在此处填入
• serverUrl: 上传数据的 URL，需要进行配置

如果您使用的是云服务，请输入以下 URL: https://receiver.ta.thinkingdata.cn/sync_js 或 http://receiver.ta.thinkingdata.cn/sync_js 如果您使用的是私有化部署的版本，请输入以下 URL: http://数据采集地址/sync_js

• send_method: 数据上报方式，默认为 'image'，即使用图片 GET 请求方式上报数据，可以替换为 'ajax'
• useAppTrack: 是否开启与 APP 的打通，在需要采集 APP 中的 H5 页面数据时设置，true 为开启，默认为 false，即不开启；详情可查看 H5 与 APP SDK 打通一节。
• showLog: 是否打印上报数据，打开后将会在浏览器控制台打印上报的数据，默认为 true 即开启.
• persistence: 本地缓存类型，默认为 localStorage, 可配置为 cookie. localStorage 不支持跨子域名共享，如果有类似需求，请选择 cookie 类型.
• mode: 运行模式，默认为普通模式，可以设置为 debug 或者 debug_only. 可参考 Debug 模式一节

注意：上面的配置参数是异步载入和同步载入的方式都可以配置的，一般来说只需要配置 appId 和 serverUrl 即可.

• 异步载入
• 同步载入

<!--Thinking Analytics SDK BEGIN-->
<script>
    !function (e) { if (!window.ThinkingDataAnalyticalTool) { var n = e.sdkUrl, t = e.name, r = window, a = document, i = "script", l = null, s = null; r.ThinkingDataAnalyticalTool = t; var o = ["track", "quick", "login", "identify", "logout", "trackLink", "userSet", "userSetOnce", "userAdd", "userDel", "setPageProperty", "setSuperProperties", "setDynamicSuperProperties", "clearSuperProperties", "timeEvent", "unsetSuperProperties", "initInstance"]; r[t] = function (e) { return function () { if (this.name) (r[t]._q = r[t]._q || []).push([e, arguments, this.name]); else if ("initInstance" === e) { var n = arguments[0]; r[t][n] = { name: n }; for (var a = 0; a < o.length; a++)r[t][n][o[a]] = r[t].call(r[t][n], o[a]); (r[t]._q1 = r[t]._q1 || []).push([e, arguments]) } else (r[t]._q = r[t]._q || []).push([e, arguments]) } }; for (var u = 0; u < o.length; u++)r[t][o[u]] = r[t].call(null, o[u]); r[t].param = e, r[t].__SV = 1.1, l = a.createElement(i), s = a.getElementsByTagName(i)[0], l.async = 1, l.src = n, s.parentNode.insertBefore(l, s) } }(
    {
        appId:'APP_ID', //系统分配的APPID
        name: 'ta', //全局的调用变量名，可以任意设置，后续的调用使用该名称即可
        sdkUrl:'./thinkingdata.min.js', //统计脚本URL
        serverUrl:'https://YOUR_SERVER_URL/sync_js', //数据上传的URL
        loaded: function(ta) {
           // var currentId = ta.getDistinctId();
           // ta.identify(currentId);
           // ta.quick('autoTrack');
        }
    });
</script>
<!--Thinking Analytics SDK END-->

<!--Thinking Analytics SDK BEGIN-->
<script src="./thinkingdata.umd.min.js"></script>
<script>
// 创建 SDK 配置对象
var config = {
    appId: 'APP_ID',
    serverUrl: 'https://YOUR_SERVER_URL/sync_js',
};

// 将 SDK 实例赋给全局变量 ta，或者其他您指定的变量
window.ta = thinkingdata;

// 用配置对象初始化 SDK
ta.init(config);

// 之后您就可以使用 ta 来上报事件了
ta.track('test_event');
</script>
<!--Thinking Analytics SDK END-->

2. 设置用户 ID

在 JS SDK 初始化完成之后，SDK 将会自动生成一个随机的访客 ID 作为用户标识，该 ID 将会作为用户在未登录状态下的身份识别。如果您的用户存在账号 ID，请使用 login 设置用户的账号 ID. 您也可以通过相关接口修改默认的访客 ID.

a) 设置访客ID（可选）

如果用户在您的产品中可以未登录状态下使用，且您需要配置用户在未登录状态下的访客 ID，则您可以调用 identify 来进行设置：

ta.identify('123ABCabc');

如果需要获得访客 ID，可以调用 getDistinctId 获取：

//返回访客 ID，多实例的情况下，返回的是调用实例的访客ID
var distinctId = ta.getDistinctId();

b) 设置账号ID

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

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

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

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

c) 清除账号 ID

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

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

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

3. 发送事件

a) 上传事件

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

ta.track(
   'Purchase',              //追踪事件的名称
    {
        'Item':'商品A',
        'ItemNum':1,
        'Cost':100,
        'Elements':['apple','ball','cat'],
    }                       //需要上传的事件属性
);

• track 接口共有两个参数，第一个参数为事件的名称，第二个参数为事件的属性
• 事件的名称是字符串，只能以字母开头，可包含数字，字母和下划线 "_"，长度最大为 50 个字符，对字母大小写不敏感。
• 事件的属性是一个 JSON 格式的对象，其中元素必须是 Key : Value 的形式，每个元素代表一个属性。
• Key 为属性的名称，为 string 类型，规定只能以字母开头，包含数字，字母和下划线 "_"，长度最大为 50 个字符，对字母大小写不敏感。
• Value为该属性的值，支持支持 String、Number、Boolean、Date 和 Array.

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

b）监控 HTML 元素点击事件

如果您想要追踪页面上元素的点击事件，可以使用 trackLink 对 HTML 元素进行批量监控：

ta.trackLink(
    {
        'tag':['a','button'],             //HTML标签
        'class':['class1','class2'],      //自定义的Class名称
        'id':['id1','id2']                //自定义的ID名称
         },                               //监控元素的规则
    'click',                              //追踪事件的名称
    {                    
        'production':'产品名',
        'name':'元素标识名'
        }                                 //事件的属性        
);

• 第一个参数是您需要监控的元素的规则，类型是 JSON 对象，支持根据 HTML 标签类型、Class 以及 id 追踪需要监控的页面元素，至少要选择一种途经选取 DOM 元素。对于满足规则的元素，会通过事件监听器的方式监控元素的点击事件，当监听元素被点击时，将会上报一个事件，事件名和事件属性取后续两个参数的值
• 第二个参数是事件的名称，为 string 类型，规则与 track 接口的事件名一致，必须填写
• 第三个参数是事件的属性，类型是JSON对象，如果没有需要上报的属性，可传入空JSON
• 本接口规定事件属性 'name'为元素的标识，如果参数三中没有设置事件属性 'name'，则本接口将会根据以下逻辑，获取被监控元素的特定属性值作为元素标识。取值，元素的自定义属性 'td-name'，元素的 innerHTML，元素的 value，如果都没有取到则传 '未获取标识'.

本接口只会在被调用时为符合规则的元素设置事件监听器，因此在调用接口后元素的标识发生变化，或者新生成了符合规则的元素，监听器上报的事件不会做出相应的改变，如果需要监控新生成元素，可在 ajax 中元素被生成后调用本接口。

c) 设置公共事件属性

在采集数据的过程中，有一些字段会被多个事件所共用，比如发生在同一页面上的所有事件，都应该带有这个页面的页面属性，用户的账号信息应该在所有数据中都带有。那么在调用 track 上报事件时，这些 属性每次都需要设置一遍，针对这样的属性，可以使用公共属性设置接口来统一设置：

1. 公共属性类型

在介绍如何设置公共属性之前，您需要先了解三种类型的公共属性的特性，根据实际需求，选用适合的类型：

• 页面公共属性: 针对当前页面生效，优先级最高。如果重新初始化 SDK，页面公共属性会被清空。只能设置定值。

• 动态公共属性: 针对当前页面生效，优先级次于页面公共属性。重新初始化SDK后，需要再次设置动态公共属性，可以设置动态变量。

• 静态公共属性: 对所有页面生效. 优先级最低，开启缓存的情况下，会缓存在 localStorage 或 cookie 中。只能设置定值。

2. 设置页面公共属性

对于一些页面中的静态属性，比如一个页面的名称或者地址，您可能希望在这个页面中触发的所有事件上都加入这个属性。类似这样的、需要适用于页面中所有事件的静态属性，您可以使用 setPageProperty 进行设置，请注意，使用 setPageProperty 设置的公共属性只对当前页面有效

// 将页面 ID 设置为页面公共属性，该页面中触发的所有事件，都会带有以下属性 
ta.setPageProperty({'page_id': 'page10001'});

如果您希望获取当前页面的页面公共属性，可以调用getPageProperty来获取

// 获取当前页面的页面公共属性
var pageProperty = ta.getPageProperty();

3. 设置页面动态公共属性

在 v1.1.0 版本中，新增了页面动态公共属性的特性。通过 setDynamicSuperProperties 设置动态公共属性的回调函数，SDK 将会在事件上报时触发回调函数，并把返回JSON对象加入到事件属性中。

setDynamicSuperProperties 的参数是一个函数，函数需要返回一个 JSON 对象，其格式要求与事件属性保持一致。

// 设置动态公共属性，在事件上报时触发回调函数，并把返回的JSON对象加入到事件属性中
ta.setDynamicSuperProperties(
    function() {
        var d = new Date();
        d.setHours(10);
        return {'date': d}
    });

/*  
ta.setDynamicSuperProperties(
    ()=>{
        var d = new Date();
        d.setHours(10); 
        return {'date': d}
    });
*/

4. 设置静态公共属性

对于一些重要的属性，譬如用户的渠道、昵称、ID等，这些属性需要设置在每个事件中，您可以调用setSuperProperties 来设置静态公共事件属性，静态公共事件属性会对全局生效。当开启缓存时（默认打开），静态公共属性会缓存在 localStorage 或 cookie 中。

静态公共属性的参数是一个 JSON 对象，其格式要求与事件属性保持一致。

// 设置公共事件属性，所有数据事件中都会带有这些属性
ta.setSuperProperties({'channel':'渠道名','user_name':'用户名'});

如果您需要所有获取已设置静态公共属性，可以调用 getSuperProperties；如果您需要删除某个静态公共属性，您可以调用 unsetSuperProperty 清除其中一个静态公共属性；如果您想要清空所有静态公共属性，则可以调用 clearSuperProperties.

// 获取静态公共事件属性
var superProperties = ta.getSuperProperties();

// 清除一条静态公共事件属性，比如将之前设置 'channel' 属性清除，之后的数据将不会该属性
ta.unsetSuperProperty('channel');

// 清除所有静态公共事件属性
ta.clearSuperProperties();

d) 记录事件时长

您可以调用 timeEvent 来开始计时，配置您想要计时的事件名称，当您上传该事件时，计时将会结束，并且 SDK 将会自动在该事件的事件属性中加入 #duration 属性来表示记录的时长，单位为秒，timeEvent 支持跨页面计时。

// 开始计时，记录的事件为'Purchase'
ta.timeEvent('Purchase');

// 其他代码

// 上传事件，计时结束，'Purchase'这一事件中将会带有表示事件时长的属性"#duration"
ta.track('Purchase', {'Item':'商品A','ItemNum':1,'Cost':100});

e) 自动采集页面浏览事件

TA 提供自动采集页面浏览事件的接口，您只需使用以下代码，JS SDK将会自动上传用户浏览页面的事件：

ta.quick('autoTrack');

4. 用户属性

a) 设置用户属性（userSet）

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

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

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

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

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

c) 累加用户属性（userAdd）

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

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

d) 重置用户属性（userUnset）

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

// 清空该用户属性名为 userPropertykey 的用户属性值，即设置成 NULL
ta.userUnset('userPropertykey');

e) 删除用户（userDel）

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

ta.userDel();

e) 对 Array 类型的数据追加元素 (userAppend)

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

ta.userAppend({'Elements':['a':1,'b':2]});

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

5. 其他功能

a) 多实例

在 v1.1.0 版本，加入了多实例的功能，可以通过调用 initInstance 方法，可以创建子实例对象。其参数为子实例名称。之后您可以通过该名称调用子实例的接口。

// 创建一个名字为 newInstance 的实例
ta.initInstance('newInstance');

// 为子实例设置 distinct_id 并发送 test_event 的事件
ta.newInstance.identify('new_distinct_id');
ta.newInstance.track('test_event');

默认情况下，子实例与主实例采用相同的配置（appId, serverUrl等）。并且默认情况下，子实例不会开启本地缓存。

如果需要为子实例单独配置参数，可以在初始化时传入配置信息，通过在配置信息中传入不同的 appId 值，可以达到向不同项目上报数据的功能:

// 定义子实例的配置参数
var param = {
  appId: 'debug-appid',
  serverUrl: 'ANOTHER_SERVER_URL',
  persistenceEnabled: true, // 开启子实例的本地缓存，子实例本地缓存根据子实例名称 name 区分
  send_method:'image',
  showLog: true
}

// 初始化子实例
ta.initInstance('anotherInstance', param);

//往主实例项目中上报数据
ta.track('Event');

//往子实例项目中上报数据
ta.anotherInstance.track('Event');

主实例与子实例的 ID 体系不互通，公共属性不互通，可以单独为每个实例设置用户 ID，以下案例通过这一特性，为邀请好友这一事件的邀请者和被邀请者，分别上报了邀请成功和被邀请事件

//主实例是被邀请的新用户，子实例是邀请者
ta.login('invitee');
ta.anotherInstance.login('inviter');

//新用户触发被邀请事件
ta.track('be_invited');

//邀请者触发邀请新用户事件
ta.anotherInstance.track('invite_new_user');

b) 获取设备 ID

在 v1.1.0 版本，加入了获取设备 ID（也就是预置属性#device_id）的接口，您可以通过调用getDeviceId 来获取设备 ID：

var deviceId = ta.getDeviceId();

// 如果需要将设备ID设置成访客ID可以如下调用
// ta.identify(ta.getDeviceId());

c) Debug 模式

自 v1.4.0 版本，您可以通过在初始化配置中设置 mode 参数，开启 Debug 模式。Debug 模式仅用于开发阶段的数据格式校验，不要在线上环境开启 Debug 模式。

当前 SDK 实例支持两种 Debug 模式：

• "debug": 通过 Debug 接口上报并校验数据
• "debug_only": 仅校验数据，不入库

由于 Debug 会影响集群性能以及数据采集的稳定性，因此规定只有指定的设备才能开启 Debug 模式。只有在 web 端开启了 Debug 模式，并且 SDK 随机生成的设备 ID 在 TA 后台的埋点管理相关页面中配置了的设备才能开启 Debug 模式。

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

• TA 平台中事件数据中的 #device_id 属性
• 控制台日志中观察上报事件数据中的 #device_id 字段

6. 相关预置属性

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

7. 进阶功能

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

a) 首次事件

首次事件是指针对某个设备或者其他维度的 ID，只会记录一次的事件。例如在一些场景下，您可能希望记录在某个浏览器(以 TA SDK 随机生成的 #device_id 判断唯一性) 上第一次发生的事件，则可以用首次事件来上报数据。

// 示例：上报设备首次事件, 假设事件名为 DEVICE_FIRST
ta.trackFirstEvent({
    eventName: 'DEVICE_FIRST',
    properties: { 'INT_PROPERTY': 0 }
});

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

// 示例：上报用户账号的首次事件, 假设事件名为 USER_FIRST
// 将用户 ID 设置为首次事件的 FIRST_CHECK_ID
ta.trackFirstEvent({
    eventName: 'USER_FIRST',
    firstCheckId: 'YOUR_ACCOUNT_ID',
    properties: { 'INT_PROPERTY': 0 }
});

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

b) 可更新事件

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

// 示例： 上报可被更新的事件，假设事件名为 UPDATABLE_EVENT
ta.trackUpdate({
    eventName: 'UPDATABLE_EVENT',
    properties: { 'status': 3 ,
                  'price': 100},
    eventId: 'test_event_id',
});
// 上报后事件属性 status 为 3, price 为 100

ta.trackUpdate({
    eventName: 'UPDATABLE_EVENT',
    properties: { 'status': 5 },
    eventId: 'test_event_id',
});
// 上报后事件属性 status 被更新为 5, price 不变

c) 可重写事件

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

// 示例： 上报可被重写的事件，假设事件名为 OVERWRITE_EVENT
ta.trackOverwrite({
    eventName: 'OVERWRITE_EVENT',
    properties: { 'status': 3 ,
                  'price': 100},
    eventId: 'test_event_id',
});

// 上报后事件属性 status 为 3, price 为 100
ta.trackOverwrite({
    eventName: 'OVERWRITE_EVENT',
    properties: { 'status': 5 },
    eventId: 'test_event_id',
});

// 上报后事件属性 status 被更新为 5, price 属性被删除

注意：可更新事件和可重写事件默认会使用设备当前时间更新历史数据的事件时间，如果您希望指定事件时间，可以在上报可更新事件的时候，指定事件时间

// 以 trackUpdate 为例，可以传入 Date 类型的 eventTime 以指定事件时间
ta.trackUpdate({
    eventName: 'UPDATABLE_EVENT',
    properties: { 'status': 5 },
    eventId: 'test_event_id',
    eventTime: realEventTime
});

Change Log

1.4.0 2020/08/25

• 支持首次事件, 允许传入自定义的 ID 校验是否首次上报
• 支持可更新、可重写的事件
• 支持 DEBUG 模式，通过后台校验数据格式

1.3.0 2020/02/10

• 支持 Array 类型
• 新增 userAppend 接口
• 去除本地数据格式校验

1.2.0 2019/10/22

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

    utc_time + #zone_offset = #event_time
  

1.1.0 2019/07/23

• 默认使用 localStorage 缓存 #device id, #distinct id, #account id 等需要持久化的数据
• 支持多实例: 多个实例之间原则上只有 #device id 是共享的. 其他的所有属性和配置都不共享，可以分别向不同的项目中上报各自的数据
• 增加接口：
  • getDeviceId()
  • getDistinctId()
  • getPageProperty()
  • setSuperProperties(superProperties)
  • unsetSuperProperty(propertyName)
  • clearSuperProperties()
  • getSuperProperties()
  • setDynamicSuperProperties(function)
  • timeEvent(eventName)
• 增加属性合法性校验逻辑
• 自动采集点击事件优化:
  • 增加 #element_type 属性, 传入 nodeName
  • 增加页面属性，类似于ta_pageview
  • 优化自动采集逻辑，修复已知BUG
• 初始化参数中增加 loaded 参数, 可以传入回调函数。当初始化完成时，会回调此函数.
• 其他优化：
  • 修复 device id 未持久化bug
  • 优化初始化逻辑
  • 预置属性增加 #os 采集ua 中的操作系统信息

1.0.7 2019/05/31

• 修复兼容性Bug

1.0.6 2019/05/10

• 支持 identify 接口