menu
Is this helpful?

# JavaScript

提示

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

JavaScript SDK 运行环境需为浏览器,暂不兼容 IE 8 及以下版本.

JavaScript SDK体积大小约为 35 KB

最新版本: v2.0.0 下载 (opens new window)

更新时间: 2023-11-08

资源下载:源代码 (opens new window)

注意

当前文档适用于 v2.0.0 及以后的版本,历史版本请参考 JS 接入指南(V1) (opens new window)SDK下载(V1) (opens new window)

# 一、集成SDK

# 1.1 自动集成

npm install thinkingdata-browser --save

接下来开始初始化SDK,具体配置参数请参考上面第二步。

import thinkingdata from "thinkingdata-browser";
var config = {
    appId: "APP_ID",
    serverUrl: "https://YOUR_SERVER_URL",
    autoTrack: {
     pageShow: true, //开启页面展示事件,事件名ta_page_show
     pageHide: true, //开启页面隐藏事件,事件名ta_page_hide
    }
};
thinkingdata.init(config);

# 1.2 手动集成

步骤一:下载JavaScript SDK (opens new window)

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

步骤2:载入 JavaScript SDK

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

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

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

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

# 二、常用功能

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

# 2.1 设置账号 ID

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

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

该方法不会上传登录事件

# 2.2 设置公共事件属性

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

var superProperties = {};
superProperties["channel"] = "ta";//字符串
superProperties["age"] = 1;//数字
superProperties["isSuccess"] = true;//布尔
superProperties["birthday"] = new Date();//时间
superProperties["object"] = {key:"value"};//对象
superProperties["object_arr"] = [{key:"value"}];//对象组
superProperties["arr"] = ["value"];//数组
ta.setSuperProperties(superProperties);//设置公共事件属性

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

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

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

# 2.3 发送事件

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

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

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

Array 类型在 v1.3.0 之后版本支持,需要配合 TE 平台 2.5 及以上版本.
Object类型需要配合 TE 平台3.5及以上版本

# 2.4 设置用户属性

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

// username为TA
ta.userSet({ username: "TA" });
//username为TE
ta.userSet({ username: "TE" });

# 三、最佳实践

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

import thinkingdata from "thinkingdata-browser";
var config = {
    appId: "APP_ID",
    serverUrl: "https://YOUR_SERVER_URL/sync_js",
    autoTrack: {
     pageShow: true, //开启页面展示事件,事件名ta_page_show
     pageHide: true, //开启页面隐藏事件,事件名ta_page_hide
    }
};
window.ta = thinkingdata;
//初始化SDK
ta.init(config);

//如果用户已登录,可以设置用户的账号ID作为身份唯一 标识
ta.login("TA");

//设置公共事件属性
var superProperties = {};
superProperties["channel"] = "ta";//字符串
superProperties["age"] = 1;//数字
superProperties["isSuccess"] = true;//布尔
superProperties["birthday"] = new Date();//时间
superProperties["object"] = {key:"value"};//对象
superProperties["object_arr"] = [{key:"value"}];//对象组
superProperties["arr"] = ["value"];//数组
ta.setSuperProperties(superProperties);//设置公共事件属性

//发送事件
ta.track("product_buy", //事件名称
 //事件属性
 {product_name:"商品名"});
 
//设置用户属性
ta.userSet({username: "TA" });