目录
此内容是否有帮助?

# JavaScript SDK 使用指南

提示

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

您可以在 GitHub (opens new window) 获取 JavaScript SDK 源码。

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

JavaScript SDK体积大小约为 35 KB

最新版本为： v1.6.0

更新时间为： 2022-06-21

下载地址 (opens new window)

# 一、引入 JavaScript SDK

1.下载 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/sync_js

或 http://global-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 模式一节
  • zoneOffset:自定义时区，例如东八区传入8。

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

3.通过npm方式引入

npm install thinkingdata-browser --save

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

import thinkingdata from "thinkingdata-browser";
var config = {
    appId: "APP_ID",
    serverUrl: "https://YOUR_SERVER_URL/sync_js",
};
thinkingdata.init(config);

# 二、设置用户 ID

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

# 2.1 设置访客 ID（可选）

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

ta.identify("123ABCabc");

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

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

# 2.2 设置账号 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");

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

# 2.3 清除账号 ID

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

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

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

# 三、发送事件

# 3.1 上传事件

您可以直接调用 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、Object和 Array;Object中的内容可以为String、Number、Boolean、Date，Array（内容为字符串);Array中的内容可以为Object和String

注意：

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

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

# 3.2 监控 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 中元素被生成后调用本接口。

# 3.3 设置公共事件属性

在采集数据的过程中，有一些字段会被多个事件所共用，比如发生在同一页面上的所有事件，都应该带有这个页面的页面属性，用户的账号信息应该在所有数据中都带有。那么在调用 track 上报事件时，这些

属性每次都需要设置一遍，针对这样的属性，可以使用公共属性设置接口来统一设置：

# 3.3.1 公共属性类型

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

  • 页面公共属性: 针对当前页面生效，优先级最高。如果重新初始化 SDK，页面公共属性会被清空。只能设置定值。
  • 动态公共属性: 针对当前页面生效，优先级次于页面公共属性。重新初始化 SDK 后，需要再次设置动态公共属性，可以设置动态变量。
  • 静态公共属性: 对所有页面生效. 优先级最低，开启缓存的情况下，会缓存在 localStorage 或 cookie 中。只能设置定值。

# 3.3.2 设置页面公共属性

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

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

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

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

# 3.3.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}
    });
*/

# 3.3.4 设置静态公共属性

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

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

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

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

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

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

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

# 3.4 记录事件时长

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

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

// 其他代码

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

# 3.5 自动采集页面浏览事件

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

ta.quick("autoTrack");

从v1.6.0版本开始，可以支持自定义属性。

ta.quick('autoTrack', {
    name: 'test_name',
    time: new Date(),
    pro: [1, 2, 3, 4],
})

# 3.6 自动采集页面显示和隐藏事件

从v1.6.0版本开始，增加ta_page_show 和 ta_page_hide 事件。

SDK默认是不采集这些事件，可以通过SDK初始化的config来配置。

var config = {
    appId: 'xxx',
    serverUrl: 'xxx',
    autoTrack: {
     //开启ta_page_show事件
     pageShow: true,
     //开启ta_page_hide事件
     pageHide: true,
    }
};

ta_page_hide事件会将页面本次展示到关闭的时长放到属性#duration中。

# 四、用户属性

# 4.1 设置用户属性（userSet）

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

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

属性格式要求与事件属性保持一致。

# 4.2 初始化用户属性（userSetOnce）

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

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

属性格式要求与事件属性保持一致。

# 4.3 累加用户属性（userAdd）

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

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

设置的属性key为字符串，Value 只允许为数值。

# 4.4 重置用户属性（userUnset）

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

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

userUnset的传入值为被清空属性的 Key 值。

# 4.5 删除用户（userDel）

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

ta.userDel();

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

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

ta.userAppend({ Elements: ["a", "b"] });

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

# 4.7 对 Array 类型的数据追加唯一元素 (userUniqAppend)

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

//如果用户属性存在，不会新建该元素
ta.userAppend({ Elements: ["a", "b"] });

# 五、其他功能

# 5.1 多实例

在 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");

# 5.2 获取设备 ID

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

var deviceId = ta.getDeviceId();

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

# 5.3 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 字段

# 5.4 暂停/停止数据上报

在 v1.6.0 版本中，新增了 SDK 数据上报状态，一共有三种状态：

# 5.4.1 暂停 SDK 上报

您可能希望在一些场景下，暂时停止数据采集以及上报，比如用户处于测试环境中、或者用户登录了一个测试账号，此时您可以调用下列接口，暂时停止 SDK 实例的上报。

您可以通过某一实例（包括主要实例以及轻实例）调用 setTrackStatus，传入 pause 来暂停 SDK 实例的上报，该实例已经设置的 #distinct_id、#account_id、公共属性等将保留；该实例已经采集但还未上报成功的数据将继续尝试上报；后续该实例不能采集以及上报任何新数据、不能设置访客 ID、账户 ID 以及公共属性等，但是可以读取该实例已经设置的公共属性和设备 ID、访客 ID、账号 ID 等信息。

实例的停止状态将会被保存在本地缓存，直到调用 setTrackStatus，传入 normal，SDK 实例将会重新恢复数据采集以及上报，需要注意轻实例因为不进行缓存，因此每次打开 App 后，轻实例的暂停状态不会被保留，将重新开启上报。

// 暂停上报
instance.setTrackStatus({ status: 'pause' })

// 恢复上报
instance.setTrackStatus({ status: 'normal' })

# 5.4.2 停止 SDK 上报

在一些特殊场景下，您可能需要完全停止 SDK 实例的功能，比如在适用 GDPR 的地区，用户选择不提供数据采集权限，则您可以调用setTrackStatus，传入stop关闭 SDK 实例的功能，只能通过主要实例调用。

与 pause状态的最大区别在于，其将会清空该实例的本地缓存，包括本实例的访客 ID，账号 ID，公共属性，以及未上报的数据队列。之后再关闭该实例的采集和上报功能。

// 停止上报，并重置本地缓存
instance.setTrackStatus({ status: 'stop' })

实例的停止状态也将保存在本地缓存，直到调用 setTrackStatus，传入 normal，后续可以继续上报，但此时相当于一个全新的实例

// 重新开启上报
instance.setTrackStatus({ status: 'normal' })

# 5.4.3 恢复 SDK 上报

SDK不进行数据上报状态设置的话，就是默认此状态。

instance.setTrackStatus({ status: 'normal' })

# 5.5 支持数据传输加密

从v1.6.0开始，数据上报方式为ajax的支持数据传输加密。可以在SDK初始化config中配置加密相关信息。

var config = {
    appId: "xxx",
    serverUrl: "xxx",
     secretKey: {
       //加密公钥 可以在TA管理后台获取
       publicKey: '公钥',
       //公钥版本号
       version: 1
     },
};

想要支持数据加密，需要额外引入crypto-js和jsencrypt

<script src="https://cdn.bootcdn.net/ajax/libs/crypto-js/4.1.1/crypto-js.js"></script>
<script src="https://cdn.bootcss.com/jsencrypt/3.2.1/jsencrypt.js"></script>

# 六、相关预置属性

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

属性名
 中文名
 说明
#ip
 IP 地址
 用户的 IP 地址，TA 将以此获取用户的地理位置信息
#country
 国家
 用户所在国家，根据 IP 地址生成
#country_code
 国家代码
 用户所在国家的国家代码(ISO 3166-1 alpha-2，即两位大写英文字母)，根据 IP 地址生成
#province
 省份
 用户所在省份，根据 IP 地址生成
#city
 城市
 用户所在城市，根据 IP 地址生成
#device_id
 设备 ID
 用户的设备 ID
#screen_height
 屏幕高度
 用户设备的屏幕高度，如 1920 等
#screen_width
 屏幕宽度
 用户设备的屏幕高度，如 1080 等
#lib
 SDK
类型
 您接入
SDK
的类型，如 JavaScript 等
#lib_version
 SDK 版本
 您接入 SDK 的版本
#os
 操作系统
 如Android、iOS等
#browser
 浏览器类型
 用户使用的浏览器类型，如 Chrome，Firefox 等
#browser_version
 浏览器版本
 用户使用的浏览器的版本，如 Chrome 61.0，Firefox 57.0 等
#zone_offset
 时区偏移
 数据时间相对 UTC 时间的偏移小时数

自动采集事件带有的预置属性:

属性名
 中文名
 说明
#url
 页面地址
 当前页面的地址
#url_path
 页面路径
 当前页面的路径
#referrer
 前向地址
 跳转前页面的地址
#referrer_host
 前向路径
 跳转前页面的路径
#title
 页面标题
 当前页面的标题

# 6.1 获取预制属性

服务端埋点需要 App 端的一些预置属性时，可以通过此方法获取 客户端 端的预置属性，再传给服务端。

   //获取属性对象
   var presetProperties = ta.getPresetProperties();

   //生成事件预置属性
   var properties = presetProperties.toEventPresetProperties();
   /*
    {
      "#os":"Mac OS X",
      "#screen_width":1920,
      "#screen_height":1080,
      "#browser":"chrome",
      "#browser_version":"91.0.4472.114",
      "#device_id":"17a3858fafd9b4-0693d07132e2d1-34657600-2073600-17a3858fafea9b",
      "#zone_offset":8
    }
   */

    //获取某个预置属性
    var os =  presetProperties.os;//os类型，如Android
    var screenWidth = presetProperties.screenWidth;//屏幕宽度
    var screenHeight = presetProperties.screenHeight;//屏幕高度
    var browser = presetProperties.browser;//浏览器类型
    var browserVersion =  presetProperties.browserVersion;//浏览器版本号
    var deviceId = presetProperties.deviceId;//设备ID
    var zoneOffset = presetProperties.zoneOffset;//时区偏移值

IP，国家城市信息由服务端解析生成，客户端不提供接口获取这些属性

# 七、进阶功能

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

# 7.1 首次事件

首次事件是指针对某个设备或者其他维度的 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 小时入库。

# 7.2 可更新事件

您可以通过可更新事件实现特定场景下需要修改事件数据的需求。可更新事件需要指定标识该事件的 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 不变

# 7.3 可重写事件

可重写事件与可更新事件类似，区别在于可重写事件会用最新的数据完全覆盖历史数据，从效果上看相当于删除前一条数据，并入库最新的数据。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

# v1.6.0 2022/06/17

  • 增加ajax请求失败重试
  • 增加ta_app_show和ta_app_hide事件

# v1.5.0 2022/06/14

  • 支持数据传输加密
  • 支持userUniqAppend
  • 优化数据停止/暂停上报接口
  • 自动采集事件支持自定义属性
  • 支持自定义时区
  • 用户使用时长超长，限制最大24小时

# v1.4.3 2021/11/19

  • 优化设置静态公共属性功能
  • 代码优化

# v1.4.2 2021/08/23

  • 新增enableTracking接口
  • 新增optOutTracking接口
  • 新增optInTracking接口

# v1.4.1 2021/06/24

  • 支持预制属性获取
  • 优化上报地址处理逻辑

# v1.4.0 2020/08/25

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

# v1.3.0 2020/02/10

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

# v1.2.0 2019/10/22

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

# v1.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 中的操作系统信息

# v1.0.7 2019/05/31

  • 修复兼容性 Bug

# v1.0.6 2019/05/10

  • 支持 identify 接口

← Unity SDK 合规指南 →