跳到主要内容

JavaScript

最近更新 2026/10/03
提示

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

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

JavaScript SDK体积大小约为 58 KB

最新版本: v2.6.1

更新时间: 2026-07-31

资源下载: 源代码 下载

注意

当前文档适用于 v2.0.0 及以后的版本，历史版本请参考 JS 接入指南（V1），SDK下载（V1）

一、集成SDK​

SDK支持范围：

客户端框架：Vue2、Vue3、React、Angular

桌面框架：Electron

1.1 自动集成​

npm install thinkingdata-browser --save

"dependencies": {
    "thinkingdata-browser": "2.6.1",
},

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

import ta from "thinkingdata-browser";
var config = {
    appId: "APP_ID",
    serverUrl: "https://YOUR_SERVER_URL",
    autoTrack: {
     pageShow: true, //开启页面展示事件，事件名ta_page_show
     pageHide: true, //开启页面隐藏事件，事件名ta_page_hide
     pageView: true, //开启单页面浏览事件，事件名ta_pageview
     pageClick:true //开启页面元素点击事件,事件名ta_page_click
    }
};
ta.init(config);

1.2 手动集成​

步骤一：下载 JavaScript SDK

压缩包中提供了两种规范的脚本，您可以根据需要选择所需的脚本。下文描述的异步载入，需要使用 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://数据采集地址

对于异步载入，请使用 thinkingdata.min.js, 将以下代码置入 html 的 <script>中，并配置对应参数：

<!--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", "trackFirstEvent", "trackUpdate", "trackOverwrite"]; 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', //数据上传的URL
        autoTrack: {
           pageShow: true, //开启页面展示事件，事件名ta_page_show
           pageHide: true, //开启页面隐藏事件，事件名ta_page_hide
           pageView: true, //开启单页面浏览事件，事件名ta_pageview
           pageClick:true //开启页面元素点击事件,事件名ta_page_click
        },
        loaded: function(ta) {
           // var currentId = ta.getDistinctId();
           // ta.identify(currentId);
           // ta.quick('autoTrack');
        }
    });
</script>
<!--Thinking Analytics SDK END-->

异步载入特有的参数说明:

  • name 为全局的调用变量名
  • sdkUrl 为 sdk 的 URL，需要进行配置
  • loaded，初始化回调函数，使用代码片段载入为异步载入，因此有返回值的方法可能调用不成功，或者在 SDK 加载完成前触发的 track 将会出现异常。我们在参数中提供了 loaded 属性，loaded 中的回调函数将会在初始化完成后、开始上报数据前被调用，比如在此设置用户 ID，则 SDK 载入前产生的数据，将会被设置上述用户 ID.

二、常用功能​

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

2.1 设置账号 ID​

在用户产生登录行为时，可调用 login 来设置用户的账号 ID. AE 平台优先以账号 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 个字符，对字母大小写不敏感，AE 会统一转化为小写字母
  • Value 为该属性的值，支持字符串、数字、布尔、时间、对象、对象组、数组

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

2.3 发送事件​

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

ta.track("product_buy",{product_name:"商品名"});

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

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

Object类型需要配合 AE 平台3.5及以上版本

2.4 设置用户属性​

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

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

三、最佳实践​

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

import ta 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
     pageView: true, //开启单页面浏览事件，事件名ta_pageview
     pageClick:true //开启页面元素点击事件,事件名ta_page_click
    }
};
//初始化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" });
这篇文档对你有帮助吗？
本页内容