# JavaScript SDK

> ### *在使用前，请先阅读*[*数据模型*](/shence/technical_guide/data_import/data_model.md)*的介绍。*

[更新日志](https://github.com/sensorsdata/sa-sdk-javascript/releases)

## 1. 获取和引入神策分析 SDK

### 1.1 获取 JavaScript SDK

* 从神策 cdn 获取，<https://static.sensorsdata.cn/sdk/版本号/sensorsdata.min.js> 不推荐这么使用，因为不保证稳定性。版本号 1.7.1.1 ,其中 1.7 表示神策分析的版本号，后面的 1 表示没有后端更新的版本号，后面的 1 表示当前版本号。因为神策分析后端如果触发了影响 SDK 的更新，会导致数据异常，所以这里您可以根据代码生成工具(参考本文档 1.2.1 自动生成引入代码)，生成一个可兼容的且会动态更新的版本。
* 从 [GitHub](https://github.com/sensorsdata/sa-sdk-javascript) 获取最新的代码下载，建议使用 Release 中的版本，首页上的 sensorsdata.min.js 是最新版的，可能不稳定。
* 从 npm 获取， `npm install sa-sdk-javascript` , 这里获取后建议使用 webpack 等工具来打包。这里获取到的是最新版本。

### 1.2 获取引入代码

#### 1.2.1 自动生成引入代码

> 如果您当前的版本没有生成导入代码的功能，请联系神策技术支持进行升级

首先从神策分析的主页中，进入数据导入向导页面：

![](/files/-Leydck2ctJbhNeQRsjz)

然后在右上角点击 数据接入 显示如下界面，然后点击 **生成导入代码**，进入代码生成页面，按需选择合适的选项，然后点击生成代码，如下图：

![](/files/-LeydkKY7aK5ITw9lhdQ)

最后将代码放入网页中的合适位置即可。

#### 1.2.2 手动配置引入代码

**1.2.2.1 数据接收地址配置**

首先从上面的导入向导中获取采集数据的 URL、Token 及获取配置信息的 URL。

如果使用神策分析 Cloud 服务，需获取的配置信息为:

* 数据接收地址，建议使用不带端口号的: <http://{$service_name}.datasink.sensorsdata.cn/sa?project={$project_name}&token={$project_token}>
* 数据接收地址，带端口号的: <http://{$service_name}.cloud.sensorsdata.cn:8106/sa?project={$project_name}&token={$project_token}>

如果用户使用单机版私有部署的神策分析，默认的配置信息为：

* 数据接收地址: <http://{$host_name}:8106/sa?project={$project_name}>

  （注：神策分析 1.7 及之前的版本，单机版私有部署默认端口号为 8006）

如果用户使用集群版私有部署的神策分析，默认的配置信息为：

* 数据接收地址: <http://{$host_name}:8106/sa?project={$project_name}>

如果私有部署的过程中修改了 Nginx 的默认配置，或通过 CDN 等访问神策分析，则请咨询相关人员获得配置信息。

**1.2.2.2 异步载入**

```markup
<script>
(function(para) {
  var p = para.sdk_url, n = para.name, w = window, d = document, s = 'script',x = null,y = null;
  if(typeof(w['sensorsDataAnalytic201505']) !== 'undefined') {
      return false;
  }
  w['sensorsDataAnalytic201505'] = n;
  w[n] = w[n] || function(a) {return function() {(w[n]._q = w[n]._q || []).push([a, arguments]);}};
  var ifs = ['track','quick','register','registerPage','registerOnce','trackSignup', 'trackAbtest', 'setProfile','setOnceProfile','appendProfile', 'incrementProfile', 'deleteProfile', 'unsetProfile', 'identify','login','logout','trackLink','clearAllRegister'];
  for (var i = 0; i < ifs.length; i++) {
    w[n][ifs[i]] = w[n].call(null, ifs[i]);
  }
  if (!w[n]._t) {
    x = d.createElement(s), y = d.getElementsByTagName(s)[0];
    x.async = 1;
    x.src = p;
    y.parentNode.insertBefore(x, y);
    w[n].para = para;
  }
})({
      sdk_url: '在 github 下载新版本的 sensorsdata.min.js',
      name: 'sensors',
      server_url:'数据接收地址',
      //heatmap_url神策分析中点击分析及触达分析功能代码，代码生成工具会自动生成。如果神策代码中 `sensorsdata.min.js` 版本是 1.9.1 及以上版本，这个参数必须配置，低于此版本不需要配置。
      heatmap_url: "在 github 下载新版本的 heatmap.min.js",
      //web_url 神策分析中点击分析及触达分析功能会用到此地址，代码生成工具会自动生成。如果神策后台版本及 `sensorsdata.min.js` 均是 1.10 及以上版本，这个参数不需要配置。
      web_url:"神策分析后台地址",
      heatmap: {
         //是否开启点击图，默认 default 表示开启，自动采集 $WebClick 事件，可以设置 'not_collect' 表示关闭
         //需要 JSSDK 版本号大于 1.7
         clickmap:'default',
         //是否开启触达注意力图，默认 default 表示开启，自动采集 $WebStay 事件，可以设置 'not_collect' 表示关闭
         //需要 JSSDK 版本号大于 1.9.1
         scroll_notice_map:'not_collect'
      }
    });
    sensors.quick('autoTrack'); //神策系统必须是1.4最新版及以上
</script>
```

将以上代码放入 html 的 head 里面,一般最好放在稍微靠前点的位置。 您在 sensors.track() 时，只要保证写在上面引用的代码的下面就可以，不需要等 window\.onload 后再执行。

**1.2.2.3 同步载入**

如果你需要把引入代码和 SDK 文件整合在一个文件中，然后在页面头部通过 script src 的方式引入。你可以把引入代码改成如下方式。并放在下载下来的 sensorsdata.js 文件前面。

```markup
<script>
    (function(para) {
      if(typeof(window['sensorsDataAnalytic201505']) !== 'undefined') {
        return false;
      }
      window['sensorsDataAnalytic201505'] = para.name;
      window[para.name] = {
        para: para
      };
    })({
      name: 'sensors',
      server_url:'数据接收地址',
      //heatmap_url神策分析中点击分析及触达分析功能代码，代码生成工具会自动生成。如果神策代码中 `sensorsdata.min.js` 版本是 1.9.1 及以上版本，这个参数必须配置，低于此版本不需要配置。
      heatmap_url: "在 github 下载新版本的 heatmap.min.js ",
      //web_url 神策分析中点击分析及触达分析功能会用到此地址，代码生成工具会自动生成。如果神策后台版本及 `sensorsdata.min.js` 均是 1.10 及以上版本，这个参数不需要配置。
      web_url:"神策分析后台地址",
      heatmap: {
         //是否开启点击图，默认 default 表示开启，自动采集 $WebClick 事件，可以设置 'not_collect' 表示关闭
         //需要 JSSDK 版本号大于 1.7
         clickmap:'default',
         //是否开启触达注意力图，默认 default 表示开启，自动采集 $WebStay 事件，可以设置 'not_collect' 表示关闭
         //需要 JSSDK 版本号大于 1.9.1
         scroll_notice_map:'not_collect'
      }
    });
  </script>
<script src="在 github 下载新版本的 sensorsdata.min.js"></script>
<script>
  sensors.quick('autoTrack');
</script>
```

一般将这段放在公用头部。其他参数配置跟上文一致。

**1.2.2.4 使用 import 方式**

从 npm 获取 sdk ， `npm install sa-sdk-javascript`

```javascript
import sensors from'sa-sdk-javascript';
sensors.init({
  server_url: '...',
  //heatmap_url神策分析中点击分析及触达分析功能代码，代码生成工具会自动生成。如果神策代码中 `sensorsdata.min.js` 版本是 1.9.1 及以上版本，这个参数必须配置，低于此版本不需要配置。
  heatmap_url: "在 github 下载新版本的 heatmap.min.js ",
  //web_url 神策分析中点击分析及触达分析功能会用到此地址，代码生成工具会自动生成。如果神策后台版本及 `sensorsdata.min.js` 均是 1.10 及以上版本，这个参数不需要配置。
  web_url:"神策分析后台地址",
  heatmap: {
     //是否开启点击图，默认 default 表示开启，自动采集 $WebClick 事件，可以设置 'not_collect' 表示关闭
     //需要 JSSDK 版本号大于 1.7
     clickmap:'default',
     //是否开启触达注意力图，默认 default 表示开启，自动采集 $WebStay 事件，可以设置 'not_collect' 表示关闭
     //需要 JSSDK 版本号大于 1.9.1
     scroll_notice_map:'not_collect'
  }
  .......
});
sensors.login(user_id);
sensors.quick('autoTrack');
```

**当神策服务器异常时，JS SDK发送的图片数据请求无法及时响应，会导致window\.onload无法生效，所以建议不要将页面渲染的代码放在window\.onload中。如果一定要使用window\.onload的话，建议将send\_type参数设置为'ajax'，使用ajax发送数据。**

### 1.3 如何确认数据发送成功

第一种：神策 JS SDK 默认会在浏览器开发者工具的控制台打印出发送的数据。 第二种：神策分析后台，提供埋点管理的功能，可以在埋点管理里面查看这个事件是否发送成功，并校验此事件的相关属性是否报错。

[详细操作](https://sensorsdata.cn/manual/debug_mode.html#216-javascript-sdk)

### 1.4 参数配置

> 如果使用自动代码生成，一般情况下无需手工修改参数

#### 1.4.1 普通参数

普通参数对代码埋点有效，下面是必填参数：

* **sdk\_url**: sensorsdata.min.js 文件的地址，请从 GitHub 获取并且放在你们自己网站目录下。
* **name**: SDK 使用的一个默认的全局变量，如定义成 sensors 的话，后面接可以使用 `sensors.track()` 用来跟踪信息。为了防止变量名重复，你可以修改成其他名称比如 sensorsdata 等 。
* **server\_url**: 数据接收地址。
* **heatmap\_url**: heatmap.min.js 文件的地址，请从 GitHub 获取并且放在你们自己网站目录下。神策分析中点击分析及触达分析功能代码，代码生成工具会自动生成。如果神策代码中 `sensorsdata.min.js` 版本是 1.9.1 及以上版本，这个参数必须配置，低于此版本不需要配置。
* **web\_url**: 神策分析后台地址，神策分析中点击分析及触达分析功能会用到此地址，代码生成工具会自动生成。如果神策后台版本及 `sensorsdata.min.js` 均是 1.10 及以上版本，这个参数不需要配置。

如果有需要，也可以修改可选参数：

* **heatmap**:点击图配置。配置成 `{}` 表示开启 $WebClick 和 $WebStay 的自动采集，默认 $WebClick 只采集 a，button，input 三个 dom 元素的点击事件。[详细配置参考](/shence/technical_guide/detailed_guide/js_sdk/js_sdk_heatmap.md)
* **cross\_subdomain**: 设置成 true 后，表示在根域下设置 cookie 。也就是如果你有 zhidao.baidu.com 和 tieba.baidu.com 两个域，且有一个用户在同一个浏览器都登录过这两个域的话，我们会认为这个用户是一个用户。如果设置成 false 的话，会认为是两个用户。默认 true。
* **show\_log**: 设置 true 后会在网页控制台打 logger，会显示发送的数据,设置 false 表示不显示。默认 true。
* **use\_client\_time**: 因为客户端系统时间的不准确，会导致发生这个事件的时间有误，所以这里默认为 false ，表示不使用客户端时间，使用服务端时间，如果设置为 true 表示使用客户端系统时间。如果你在属性中加入 {$time: new Date()} ，注意这里必须是 Date 类型，那么这条数据就会使用你在属性中传入的这个时间。
* **source\_channel**: 默认取来源是根据 utm\_source 等 ga 标准来的。如果你用的是百度统计的 hmsr 等参数。可以在这里面加入，参数必须是数组，比如 \['hmsr']。
* **source\_type**: 自定义搜索引擎流量，社交流量，搜索关键词。具体用法参考 7.2 。
* **is\_track\_device\_id**:设置成 true 后， 表示事件属性里面添加一个设备 id 的属性，存贮在 cookie 里面并发送。默认 false，记录但不发送。
* **send\_type**: 默认值 'image' 表示使用图片 get 请求方式发数据，( 神策系统 1.10 版本以后 ) 可选使用 'ajax' 和 'beacon' 方式发送数据，这两种默认都是 post 方式， beacon 方式兼容性较差。
* **callback\_timeout**: 默认值 200 ，单位毫秒，表示回调函数超时时间，如果数据发送超过 callback\_timeout 还未返回结果，会强制执行回调函数。（SDK 版本 1.11.6 以后支持）
* **queue\_timeout**: 默认值 600 ，单位毫秒，表示队列发送超时时间，如果数据发送时间超过 queue\_timeout 还未返回结果，会强制发送下一条数据。（SDK 版本 1.11.6 以后支持）
* **datasend\_timeout**: 默认值 1500 ，单位毫秒，表示数据发送超时时间，如果数据发送超过 datasend\_timeout 还未返回结果，会强制取消该请求。（SDK 版本 1.11.6 以后支持）
* **is\_track\_latest**: 是否开启 $latest 最近一次相关事件属性采集，默认值为一个对象。（SDK 版本 1.12.18 以后支持）[详细配置参考](https://54td.gitbook.io/shence/technical_guide/detailed_guide/pages/-LeyhTD4lVstaQwN0kRs#714-is_track_latest相关参数)
* **is\_track\_single\_page**: 默认 值false，表示是否开启单页面自动采集 $pageview 功能，SDK 会在 url 改变之后自动采集web页面浏览事件 $pageview。（SDK 版本 1.12.18 以后支持）

## 2. 如何标识用户

在进行任何埋点之前，都应当先确定如何标识用户。**distinct\_id** 是用来标识用户的，是一段唯一的字符串，默认情况下 JavaScript SDK 会自动生成一个 **distinct\_id** 并永久保存在浏览器中的 Cookie 中（我们暂时称这个为 **cookie\_id**），如果你已知了真实的用户 id ，你可以通过 `sensors.login("你们服务端分配给用户具体的登录 ID")` 来发送关联 cookie\_id 的事件，同时这个方法还会用"你们服务端分配给用户具体的登录 ID"替换浏览器缓存中的 **cookie\_id**。

获取 Cookie 中的 **distinct\_id** ：\
前端方式： 可以通过 `sensors.store.getDistinctId()` 方法获取到 **distinct\_id** (注意，如果前端已经调用过 login 方法，那么此时 distinct\_id 为真实 id，所以需要获取 first\_id 字段)。\
调用这个方法时，可能SDK还未初始化成功，建议将此方法放在下面代码中。

```javascript
    sensors.quick('isReady',function(){
        ……  
        sensors.store.getDistinctId();
        //如果前端已经调用过 login 方法,请使用这个方法获取匿名 id：sensors.store.getFirstId();  
        ……
    });
```

后端方式： 可以在 Cookie 里面找到 key 为 `sensorsdata2015jssdkcross` 的 value 值然后进行 `decodeURIComponent` 解码，最后通过 `JSON.parse` 方法得到一个对象，对象里面的 **distinct\_id** 即为用户所需要的 (注意，如果前端已经调用过 login 方法，那么此时 distinct\_id 为真实 id，所以需要获取 first\_id 字段)。

### 2.1 在登录和注册成功后，调用sensors.login("你们服务端分配给用户具体的登录 ID") 来标识真实用户

通过 `sensors.login("你们服务端分配给用户具体的登录 ID")` 来把 SDK 自动生成的 **cookie\_id** 关联成现在传入的 **"你们服务端分配给用户具体的登录 ID"**。且以后会一直使用这个 **"你们服务端分配给用户具体的登录 ID"**。

**我们的 JavaScript SDK 从 1.6.9 版本开始支持 sa.login() 方法。**

```javascript
    sensors.login('user1312312123');
```

问题1：这行代码放在哪里？\
建议放在所有事件前面。也就是在 sdk 载入代码后面，先使用 `sensors.login` （如果此时有这个"你们服务端分配给用户具体的登录 ID" 的话），然后再用 `sensors.quick('autoTrack')` 等，这样后续的事件才会使用这个更改后的 真实 id。\
问题2：在什么时候调用？\
页面登录的时候，只要获取到用户是登录状态，就需要调用。或者 注册流程成功的时候。\
问题3：sensors.login 和 sensors.identify 有什么区别？\
login 用来关联数据库的 id，identify 用来改变匿名 id，可以认为匿名 id 是跟浏览器绑定的。

### 2.2 使用 sensors.identify 来修改匿名 id

默认情况下，是把 **cookie\_id** 作为 **distinct\_id** 的。如果你能取到其他匿名 id（比如设备 id，或者你们自己生成的 cookieid），可以用 `sensors.identify(id)` 来改变当前的**distinct\_id**。

这个方法有三种使用方式:

* `sensors.identify(id)`: 这个 **id** 仅对当前页面有效。
* `sensors.identify(id, true)`: 会把这个 **id** 一直保存下来使用，永久有效。该方法应用较多。
* `sensors.identify()`: 重新生成一个新的 **cookie\_id**，该方法一般情况不使用。

### 2.3 使用 sensors.logout 切换到之前的匿名 id

通过 `sensors.logout()` 来永久改变当前的 **distinct\_id** 为 **cookie\_id** 。

```javascript
    sensors.logout();  // 取消当前 login 的 id，改成最初自动生成的 cookie_id
    sensors.logout(true); // 取消当前 login 的 id，重新生成一个新的 cookie_id
```

问题1，这个在什么时候使用？ 在你用过 sensors.login 后，在一个浏览器有多个用户登录的时候，你想在用户退出后改变当前的 distinct\_id。

## 3. 自定义事件追踪

第一次接入神策分析时，建议先追踪 3\~5 个关键的事件，只需要几行代码，便能体验神策分析的分析功能。例如：

* 图片社交产品，可以追踪用户浏览图片和评论事件。
* 电商产品，可以追踪用户注册、浏览商品和下订单等事件。

神策分析 SDK 初始化成功后，即可以通过 `sensors.track(event_name[, properties][, callback])` 记录事件：

* **event\_name**: `string`，必选。表示要追踪的事件名。
* **properties**: `object`，可选。表示这个事件的属性。
* **callback**: `function`，可选。表示已经发送完数据之后的回调。

```javascript
    // 追踪浏览商品事件。
    sensors.track('ViewProduct', {
        ProductId: '123456',
        ProductCatalog: "Laptop Computer",
        ProductName: "MacBook Pro",
        ProductPrice: 123.45
    });
```

另外，神策分析 SDK 也支持自动进行一些事件的追踪，具体请参考：[默认事件追踪](https://54td.gitbook.io/shence/technical_guide/detailed_guide/pages/-LeyhTD4lVstaQwN0kRs#4-默认事件追踪)。

### 3.1 事件公共属性

#### 3.1.1 sensors.registerPage(object)

如果某个事件的属性，在所有事件中都会出现，可以通过 registerPage 方法将该属性设置为事件公共属性。例如电商产品中的用户等级，常作为事件的公共属性。`sensors.registerPage({gender:"male"})` 。这样的话，下次你在使用 `sensors.track("index_visit")` 时等同于 `sensors.track("index_visit", {gender:"male"})`。

再比如想在当前页面的后续事件中都注入当前页面地址及前向地址属性，只针对当前页面有效的方法如下：

```markup
<script>
(function(para) {
  var p = para.sdk_url, n = para.name, w = window, d = document, s = 'script',x = null,y = null;
  w['sensorsDataAnalytic201505'] = n;
  w[n] = w[n] || function(a) {return function() {(w[n]._q = w[n]._q || []).push([a, arguments]);}};
  var ifs = ['track','quick','register','registerPage','registerOnce','trackSignup', 'trackAbtest', 'setProfile','setOnceProfile','appendProfile', 'incrementProfile', 'deleteProfile', 'unsetProfile', 'identify','login','logout','trackLink','clearAllRegister'];
  for (var i = 0; i < ifs.length; i++) {
    w[n][ifs[i]] = w[n].call(null, ifs[i]);
  }
  if (!w[n]._t) {
    x = d.createElement(s), y = d.getElementsByTagName(s)[0];
    x.async = 1;
    x.src = p;
    y.parentNode.insertBefore(x, y);
    w[n].para = para;
  }
})({
      sdk_url: '在 github 下载新版本的 sensorsdata.min.js',
      name: 'sensors',
      server_url:'数据接收地址',
      //heatmap_url神策分析中点击分析及触达分析功能代码，代码生成工具会自动生成。如果神策代码中 `sensorsdata.min.js` 版本是 1.9.1 及以上版本，这个参数必须配置，低于此版本不需要配置。
      heatmap_url: "在 github 下载新版本的 heatmap.min.js",
      //web_url 神策分析中点击分析及触达分析功能会用到此地址，代码生成工具会自动生成。如果神策后台版本及 `sensorsdata.min.js` 均是 1.10 及以上版本，这个参数不需要配置。
      web_url:"神策分析后台地址",
      heatmap: {}
    });
    //以异步加载 SDK 为例，神策 SDK 初始化完成，此时调用设置公共属性的方法，来保证之后的事件都有这两个属性。
    sensors.registerPage({
      current_url: location.href,
      referrer: document.referrer
    });
    sensors.track('button_A_click'); // 这时候，这个 button_A_click 事件，就会带有current_url和referrer这些属性。且仅对当前页面有效。
</script>
```

### 3.2 关闭页面前发数据

我们不建议在关闭页面前发数据，尤其是关闭页面前连续发多条数据，因为浏览器的特性，肯定会存在丢失！ 数据丢失率和网速相关，尤其在移动网络环境下，丢失率严重。在手机 ios 下的 safari 丢失率极高。 如果一定要在关闭页面前发数据，或提高页面某些 a 标签的数据准确性，请联系值班同学！

## 4. 默认事件追踪

为了方便使用，神策分析的 SDK 也提供了一些默认事件的收集，例如如果需要采集页面浏览事件（即 $pageview ），可以通过增加如下代码：

```javascript
  // 如果需要调用 login 来重新设置用户标识，必须在此之前调用
  sensors.quick('autoTrack')
```

设置之后，SDK 就会自动收集页面浏览事件，以及设置初始来源。注意，该方法目前对采用单页面开发模式的网页收集不准确，这种情况可以参考文档[常见问题 3](https://www.sensorsdata.cn/manual/js_sdk_faq.html#3-单页面中发送页面浏览事件pageview)。

### 4.1 Web 浏览页面事件增加自定义属性

如果想加额外的属性，可以如下方式（添加 platForm 属性为 h5）

```javascript
  // 如果需要调用 login 来重新设置用户标识，必须在此之前调用
 sensors.quick('autoTrack', {
   platForm:'h5'
 })
```

### 4.2 只采集 Web 浏览页面事件，不追踪用户的首次属性

如果只想追踪事件，不想设置首次来源到 profile 里，可以使用`sensors.quick('autoTrackWithoutProfile')`来替代。

## 5. 设置用户属性

为了更准确地提供针对人群的分析服务，可以使用神策分析 SDK 的 profileSet() 等方法设置用户属性，如年龄、性别等。用户可以在留存分析、分布分析等功能中，使用用户属性作为过滤条件，精确分析特定人群的指标。

你可以首先使用上面的 `identify(userid)` 来标识用户，然后可以对这个特定的用户设置一些属性。如果你不用这两个方法去标识用户，就会以 Cookie 中的匿名 `distinct_id` 来标识用户。

### 5.1 sensors.setProfile(properties\[, callback])

直接设置用户的属性，如果存在则覆盖。

* properties：`object`，必选。
* callback：`function`，可选。

```javascript
    sensors.setProfile({email:'xxx@xx'});
```

### 5.2 sensors.setOnceProfile(properties\[, callback])

如果不存在则设置，存在就不设置。

* properties：`object`，必选。
* callback：`function`，可选。

```javascript
    sensors.setOnceProfile({email:'xxx@xx'});
```

### 5.3 sensors.appendProfile(properties\[, callback])

给数组属性添加值。通过setProfile只能改变属性的值。如果这个属性是数组类型的，你不想完全改变这个值，只想做添加操作可以使用此方法。

* properties：`object`，必选。
* callback：`function`，可选。

```javascript
    //给 category 增加两个值
    sensors.appendProfile({catrgory: ['玉米','白菜']});
    //给 category 增加一个值
    sensors.appendProfile({catrgory: '玉米'});
```

### 5.4 sensors.incrementProfile(properties\[, callback])

对当前用户的属性做递增或者递减。

* properties：`object` 或者 `string`，必选。
* callback：`function`，可选。

```javascript
    // 表示 navClick 递减
    sensors.incrementProfile({'navClick': -1});
    // 表示 navClick 递增2
    sensors.incrementProfile({'navClick': 2});
    // 直接传入一个属性名，表示递增1
    sensors.incrementProfile('navClick');
```

### 5.5 sensors.deleteProfile(\[callback])

删除当前用户及他的所有属性。

* callback `function`。{可选}

```javascript
    //删除当前这个用户及他的所有属性
    sensors.deleteProfile();
```

### 5.6 sensors.unsetProfile(property\[, callback])

删除当前用户的一些属性

* property：`array` 或者 `string`。
* callback：`function`，可选。

```javascript
    //删除 email 和 location 属性
    sensors.unsetProfile(['email','location']);
    //删除 email 属性
    sensors.unsetProfile('email');
```

## 6 数据类型说明

* object: 上面 properties 是 object 类型。但是里面必须是 key: value 格式。且 value 必须只能是 string/number/date/boolean/array 这几种类型
* string: 一般情况下的值都是 string 类型
* number: 如 sensors.incrementProfile 中会用到
* datetime: 属性的值可以传入 new Date 的值即可(最终会自动转化成'2018-01-01 13:13:13.13')
* date: 传入字符串'2018-01-01'即可
* bool: 属性的值可以是 true/false
* array: array 里的必须是字符串。关于 array 类型限制请见 [数据格式](https://54td.gitbook.io/shence/technical_guide/detailed_guide/pages/-LeyhTCayIjuP3vqMBGl#73-属性长度限制)。

### 6.1 预置属性

#### 6.1.1 获取前端 JS SDK 采集的预置属性(1.9.13 支持)

此方法可获取，页面地址，页面标题，前向地址，SDK 类型及版本，屏幕宽高，最近一次的相关属性，不包括需要后端解析的 ip 及 UA 等属性，且这些属性与服务端的传输需要客户自己来做。

```javascript
sensors.getPresetProperties();
```

#### 6.1.2 所有事件都会有的预置属性：

| 字段名称                           | 类型  | 说明                             | 版本     |
| ------------------------------ | --- | ------------------------------ | ------ |
| $lib                           | 字符串 | SDK类型                          |        |
| $lib\_version                  | 字符串 | SDK版本                          |        |
| $screen\_height                | 数值  | 屏幕高度                           |        |
| $screen\_width                 | 数值  | 屏幕宽度                           |        |
| $is\_first\_day                | 布尔值 | 是否首日访问                         | 1.5 支持 |
| $latest\_referrer              | 字符串 | 最近一次站外地址(只要前向域名不是当前页面的域名，就会重置) | 1.6 支持 |
| $latest\_referrer\_host        | 字符串 | 最近一次站外域名                       | 1.6 支持 |
| $latest\_utm\_source           | 字符串 | 最近一次付费广告系列来源（只要有来源参数，就会重置）     | 1.6 支持 |
| $latest\_utm\_medium           | 字符串 | 最近一次付费广告系列媒介                   | 1.6 支持 |
| $latest\_utm\_term             | 字符串 | 最近一次付费广告系列字词                   | 1.6 支持 |
| $latest\_utm\_content          | 字符串 | 最近一次付费广告系列内容                   | 1.6 支持 |
| $latest\_utm\_campaign         | 字符串 | 最近一次付费广告系列名称                   | 1.6 支持 |
| $latest\_search\_keyword       | 字符串 | 最近一次搜索引擎关键词                    | 1.8 支持 |
| $latest\_traffic\_source\_type | 字符串 | 最近一次流量来源类型                     | 1.8 支持 |

注意：\
（1）其中 $latest\_search\_keyword 最近一次搜索引擎关键词由于各搜索引擎策略不同，可能有获取不到的情况。 （2）其中 $latest\_traffic\_source\_type 这个的属性值包括：付费广告流量、自然搜索流量、社交网站流量、引荐流量、直接流量。\
（3）最近一次付费广告相关参数是一个事件属性，且不需要做任何配置，会在所有事件中都存在。这个属性会保存最近一次有效的 utm\_source 。

#### 6.1.3 UserAgent 相关的预置属性

这一系列的属性从浏览器的 UserAgent 中进行解析。

神策分析 1.6 版本之后支持更准确的解析方式，但和原有方式不兼容，请根据需要选择。

| 字段名称              | 类型  | 说明     | 版本          |
| ----------------- | --- | ------ | ----------- |
| $manufacturer     | 字符串 | 设备制造商  | 1.6 新解析方式支持 |
| $model            | 字符串 | 设备型号   |             |
| $os               | 字符串 | 操作系统   |             |
| $os\_version      | 字符串 | 操作系统版本 |             |
| $browser          | 字符串 | 浏览器名   |             |
| $browser\_version | 字符串 | 浏览器版本  |             |

#### 6.1.4 $pageview（Web 浏览页面）事件的预置属性

| 字段名称             | 类型  | 说明     | 版本    |
| ---------------- | --- | ------ | ----- |
| $referrer        | 字符串 | 前向地址   |       |
| $referrer\_host  | 字符串 | 前向域名   |       |
| $url             | 字符串 | 页面地址   |       |
| $url\_path       | 字符串 | 页面路径   |       |
| $title           | 字符串 | 页面标题   |       |
| $is\_first\_time | 布尔值 | 是否首次访问 | 1.7修改 |
| $utm\_source     | 字符串 | 广告系列来源 |       |
| $utm\_medium     | 字符串 | 广告系列媒介 |       |
| $utm\_term       | 字符串 | 广告系列字词 |       |
| $utm\_content    | 字符串 | 广告系列内容 |       |
| $utm\_campaign   | 字符串 | 广告系列名称 |       |

#### 6.1.5 $WebClick（Web 元素点击）事件的预置属性

| 字段名称                  | 类型  | 说明     | 版本         |
| --------------------- | --- | ------ | ---------- |
| $element\_id          | 字符串 | 元素 ID  |            |
| $element\_content     | 字符串 | 元素内容   |            |
| $element\_name        | 字符串 | 元素名字   |            |
| $element\_class\_name | 字符串 | 元素样式名  |            |
| $element\_type        | 字符串 | 元素类型   |            |
| $element\_selector    | 字符串 | 元素选择器  |            |
| $element\_target\_url | 字符串 | 元素链接地址 |            |
| $url                  | 字符串 | 页面地址   |            |
| $title                | 字符串 | 页面标题   |            |
| $url\_path            | 字符串 | 页面路径   |            |
| $viewport\_width      | 数值  | 视区宽度   | （1.12.2支持） |

#### 6.1.6 $WebStay (Web 视区停留) 事件的预置属性

| 字段名称                | 类型  | 说明       | 版本                                                                                                              |
| ------------------- | --- | -------- | --------------------------------------------------------------------------------------------------------------- |
| $viewport\_width    | 数值  | 视区宽度     | （1.9支持）                                                                                                         |
| $viewport\_position | 数值  | 视区距顶部的位置 | （1.9支持）                                                                                                         |
| $viewport\_height   | 数值  | 视区高度     | （1.9支持）                                                                                                         |
| event\_duration     | 数值  | 视区停留时间   | （1.9支持）1.10.5 版本开始就采集的时长单位为秒，之前为毫秒。对于神策分析版本大于等于 1.13 的环境，如果上传了 event\_duration 属性，会自动 rename 为 $event\_duration |
| $url                | 字符串 | 页面地址     |                                                                                                                 |
| $title              | 字符串 | 页面标题     |                                                                                                                 |
| $url\_path          | 字符串 | 页面路径     |                                                                                                                 |

此事件为触达率分析图所使用的事件，触达率分析图可对用户在网页中的触达深度进行分析。

#### 6.1.7 预置的用户属性

| 字段名称                          | 类型       | 说明               |
| ----------------------------- | -------- | ---------------- |
| $first\_visit\_time           | Datetime | 首次访问时间           |
| $first\_referrer              | 字符串      | 首次前向地址           |
| $first\_referrer\_host        | 字符串      | 首次前向域名           |
| $first\_browser\_language     | 字符串      | 首次使用的浏览器语言       |
| $first\_browser\_charset      | 字符串      | 首次浏览器字符类型（1.8支持） |
| $first\_search\_keyword       | 字符串      | 首次搜索引擎关键词（1.8支持） |
| $first\_traffic\_source\_type | 字符串      | 首次流量来源类型（1.8支持）  |
| $utm\_source                  | 字符串      | 首次广告系列来源         |
| $utm\_medium                  | 字符串      | 首次广告系列媒介         |
| $utm\_term                    | 字符串      | 首次广告系列字词         |
| $utm\_content                 | 字符串      | 首次广告系列内容         |
| $utm\_campaign                | 字符串      | 首次广告系列名称         |

注意：其中 $first\_traffic\_source\_type 这个的属性值包括：付费广告流量、自然搜索流量、社交网站流量、引荐流量、直接流量。

## 7 统计来源相关问题

[使用神策JavaScript SDK统计来源相关问题](https://www.sensorsdata.cn/blog/shi-yong-shen-ce-javascript-sdktong-ji-lai-yuan-xiang-guan-wen-ti/)。

### 7.1 关于首次和最近一次属性取值介绍

#### 7.1.1  首次相关属性

* $first\_referrer:　首次前向地址
* $first\_referrer\_host:　首次前向域名
* $first\_traffic\_source\_type:　首次流量来源类型
* $first\_search\_keyword:　首次搜索引擎关键词

$first 相关属性是用户在第一次进入加载了 SDK 的页面时，通过 profile\_set\_once 这一事件给用户添加的用户属性，标明用户首次来源相关信息。

**取值介绍：**

A．正常获取的属性值

B．用户直接打开页面，没有从其他地方跳转时：

* $first\_referrer 和 $latest\_referrer\_host:　空 &#x20;
* $first\_traffic\_source\_type:　“直接流量” &#x20;
* $first\_search\_keyword:　“未取到值,直接打开” &#x20;

#### 7.1.2 最近一次相关属性

* $latest\_referrer:　最近一次站外地址(只要前向域名不是当前页面的域名，就会重置) &#x20;
* $latest\_referrer\_host:　最近一次站外域名 &#x20;
* $latest\_traffic\_source\_type:　最近一次流量来源类型 &#x20;
* $latest\_search\_keyword:　最近一次搜索引擎关键词 &#x20;

$latest 相关属性是当用户从站外跳转到加载了 SDK 的页面时，会采集这几个参数保存在 cookie 之中，会给所有事件都添加这几个事件属性，标明用户最近一次的来源相关信息。

**取值介绍：**

A．正常获取的属性值

B．用户直接打开页面，没有从其他地方跳转时：

* $latest\_referrer和$latest\_referrer\_host:　空 &#x20;
* $latest\_traffic\_source\_type:　“直接流量” &#x20;
* $latest\_search\_keyword:　“未取到值,直接打开”

C．取值异常：\
因为 cookie 被清空了，或者前面一个页面是同域名的，但是没有嵌入 sdk。

D．url 的 domain解析失败： 1．url 为空\
2．url 解析失败(例如 [www.biz.work](http://www.biz.work) 等域名无法解析) [参考地址](https://github.com/websanova/js-url/blob/master/url-tld.min.js)。\
3．初始化参数中配置了 current\_domain 属性（此属性的使用方法请咨询神策值班同学）：\
（1） current\_domain 为函数：返回值为空或路径中不含 “.”\
（2） current\_domain 为字符串：current\_domain 为空或 current\_domain 中不含 “.”

E. referrer 的 domain 解析失败：\
1．document.referrer 前向地址解析失败(例如 [www.biz.work](http://www.biz.work) 等域名无法解析) [参考地址](https://github.com/websanova/js-url/blob/master/url-tld.min.js)。\
2．初始化中配置了 referrer\_domain 属性（此属性的使用方法请咨询神策值班同学）：\
（1） referrer\_domain 为函数：返回值为空或路径中不含 “.”\
（2） referrer\_domain 为字符串：referrer\_domain 为空或 referrer\_domain 中不含 “.”

#### 7.1.3 广告系列相关参数

1．用户属性：

* $utm\_source：首次广告系列来源 &#x20;
* $utm\_medium：首次广告系列媒介 &#x20;
* $utm\_term：首次广告系列字词 &#x20;
* $utm\_content：首次广告系列内容 &#x20;
* $utm\_campaign：首次广告系列名称 &#x20;

用户在第一次进入加载了 SDK 的页面时，如果 url 中有 utm 相关的参数，会通过 profile\_set\_once 这一事件给用户添加对应的用户属性。

2．事件属性（1.6版本支持）：

* $latest\_utm\_source：最近一次付费广告系列来源（只要有来源参数，就会重置） &#x20;
* $latest\_utm\_medium：最近一次付费广告系列媒介 &#x20;
* $latest\_utm\_term：最近一次付费广告系列字词 &#x20;
* $latest\_utm\_content：最近一次付费广告系列内容 &#x20;
* $latest\_utm\_campaign：最近一次付费广告系列名称 &#x20;

用户进入加载了 SDK 的页面时，如果 url 中有 utm 相关的参数，会将其写入 cookie 中，如果 cookie 中有相同的参数会进行覆盖，之后采集的所有事件都会添加对应的事件属性。

**取值介绍：**

A．取到正常的属性值

B．未知（ url 中没有相关参数）

#### 7.1.4 is\_track\_latest相关参数:

```javascript
//需要 JSSDK 版本号大于 1.12.18
//true表示采集,false表示不采集,未设置的参数取默认值
is_track_latest: {
    //是否采集$latest_utm最近一次广告系列相关参数，默认值true
    utm:true,
    //是否采集$latest_traffic_source_type最近一次流量来源类型，默认值true
    traffic_source_type:true,
    //是否采集$latest_search_keyword最近一次搜索引擎关键字，默认值true
    search_keyword:true,
    //是否采集$latest_referrer最近一次前向地址，默认值true
    referrer:true,
    //是否采集$latest_referrer_host最近一次前向地址，默认值true
    referrer_host:true,
    //是否采集$latest_landing_page最近一次落地页地址，默认值false
    landing_page:false,
}
```

### 7.2 流量来源类型说明

关于首次流量来源类型 $first\_traffic\_source\_type 及最近一次流量来源类型 $latest\_traffic\_source\_type 的判断逻辑：\
如果落地页面地址中含有 utm 参数，就是付费广告流量\
如果不是付费广告流量且前向地址中包含 search 中的参数算自然搜索流量，\
如果不是付费广告流量且前向地址中包含 social 中的参数算社交网站流量，\
如果前向地址为空是直接流量，\
如果以上都不是（前向地址不为空）那么是引荐流量，\
其他情况为异常。

注意，其中 search 及 social 为可配参数，参数名为 **source\_type**: 自定义搜索引擎流量，社交流量，搜索关键词。具体用法如下：

```javascript
source_type :{
    search: ['.baidu.com','.google.'],
    social: ['.renren.com','.kaixin001.com'],
    keyword: {baidu:['wd','word','keyword'],sogou:'query'}
}
```

可以先通过 sensors.para.source\_type.search 等方式，来查看目前已经定义的部分判定条件。 如果你有新的判断条件想要增加，可以通过上述代码，来扩展。\
search 内容是数组，把 url 中包含特征的字符串作为判定条件，比如包含 .baidu.com 就认为是搜索引擎流量。\
social 同上，也是包含特征字符串，就认为是社交流量。\
keyword 内容是一个对象，key 是取的去掉域名后缀的字符串 , value 可以是关键词的字符串，也可以是一个包含有可能是关键词的数组。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://54td.gitbook.io/shence/technical_guide/detailed_guide/js_sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.