神策 JavaScript SDK 使用说明

作者: 李大嘴JimmyLee | 来源:发表于2020-12-26 16:07 被阅读0次

1. 获取和集成 JavaScript SDK

需要引入2套SDK包
1、埋点管理系统
server_url：https://xxx/track
2、神策自带后台管理系统
server_url： https://xxx/sa?project=production

1.1 获取 JS SDK

获取 JS SDK的方法有三种

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

我们这里推荐第三种通过 npm 安装的方式使用ES6导入的方式引用

1.2 集成 JavaScript SDK

注意：之前提过目前公司需要引入2个SDK的配置因为有2个不同接收地址所以这里提供2个

import sensors from 'sa-sdk-javascript'
sensors.init({ // 神策系统配置
    server_url: 'https://xxx/sa?project=production', // 数据接收地址
    is_track_single_page: true, // 单页应用页面浏览事件采集(url改变就触发)
    show_log: false, // 控制台显示数据开关
    heatmap: { // 热图设置 default开启 not_collect关闭（详细配置解释看官方文档）
        clickmap: 'default', // 点击热图，收集点击事件
        scroll_notice_map: 'default' // 视区热图，收集页面区域停留时间
    }
})
sensors.quick('autoTrack') 
export default sensors

import sa from 'sa-sdk-javascript'
sa.init({ // 埋点系统配置
    server_url: 'https://xxx/track', // 数据接收地址
    is_track_single_page: true, // 单页应用页面浏览事件采集(url改变就触发)
    show_log: false, // 控制台显示数据开关
    heatmap: { // 热图设置 default开启 not_collect关闭（详细配置解释看官方文档）
        clickmap: 'default', // 点击热图，收集点击事件
        scroll_notice_map: 'default' // 视区热图，收集页面区域停留时间
    }
})
sa.quick('autoTrack') // 首次触发页面加载事件 $pageview
export default sa

这里推荐使用 ES6模块化引用

1.2.1 SDK配置文件引入指南

创建文件

main.js中添加

import Vue from "vue";
import sensors from './sensors' //神策官方埋点配置
import sa from './sa' //埋点管理后台配置
Vue.prototype.$sensors = sensors //神策官方埋点
Vue.prototype.$sa = sa //埋点

1.2.2 如何埋点

1.自动采集事件埋点

主要用于主动触发页面浏览事件，一般只在页面配置后调用一次即可。

sensors.quick('autoTrack')

事件埋点
事件名+传递参数（必须是对象）+回调函数

this.$sensors.track('ViewSupplyChainDetails'[, param][,callback])

如下在方法中使用自定义埋点

    //刷新
    async refreshResourcesLists() {
      this.$sensors.track('ViewProduct', {
        productId: '123456',
        productCatalog: "Laptop Computer",
        productName: "MacBook Pro",
        productPrice: 123.45
      });
      this.$sa.track('ViewProduct', {
        productId: '123456',
        productCatalog: "Laptop Computer",
        productName: "MacBook Pro",
        productPrice: 123.45
      });
    }

3.公共属性埋点

const param = {
  platform_type: 'WEB', // 平台类型：App，H5，Web
  app_name: '沐甜商城网站', // 应用名称
  product_line: '白糖',
}
sensors.registerPage(param) // 设置公共属性

1.3 配置 JavaScript SDK参数

如果使用自动代码生成，一般情况下无需手工修改参数自动生成方式请看最后

下面是必填参数：

name: SDK 使用的一个默认的全局变量，如定义成 sa 的话，后面接可以使用 sa.track() 用来跟踪信息。为了防止变量名重复，你可以修改成其他名称比如 sensorsdata 等。
server_url: 数据接收地址。

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

heatmap_url: （1.9以上版本新加） heatmap.min.js 文件的地址，在热力分析渲染页面时会用到。
heatmap:点击图配置,如果这个参数配置了，就必须要配 heatmap_url，否则网页热力图功能不能正常渲染。配置成 {} 表示开启 $WebClick 和 $WebStay 的自动采集，默认 $WebClick 只采集 a，button，input 三个 dom 元素的点击事件。详细配置参考
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.10 。
is_single_page: 设置成 true 后，表示在单页面开发的网站中，我们会对 hashchange 和 popstate 事件进行监听，当这两个事件任何一个发生时，也会发送 $pageview 事件。默认 false。详情参考 7.9 节。
is_track_device_id:设置成 true 后，表示事件属性里面添加一个设备 id 的属性，存贮在 cookie 里面并发送。默认 false，记录但不发送。
send_type: 默认值 'image' 表示使用图片 get 请求方式发数据，( 神策系统 1.10 版本以后 ) 可选使用 'ajax' 和 'beacon' 方式发送数据，这两种默认都是 post 方式， beacon 方式兼容性较差，请参考 3.3.2 目录。

说明： server_url 的获取，建议使用神策分析后台的「数据接入」功能复制获取。

1.4 如何确认数据发送成功

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

详细操作

2. 如何标识用户

在进行任何埋点之前，都应当先确定如何标识用户。distinct_id 是用来标识用户的，是一段唯一的字符串，默认情况下 JavaScript SDK 会自动生成一个 distinct_id 并永久保存在浏览器中的 Cookie 中（我们暂时称这个为 cookie_id），如果你已知了真实的用户 id ，你可以通过 sa.login(user_id) 来修改当前的 distinct_id。

获取 Cookie 中的 distinct_id ：

前端方式：

可以通过 sa.store.getDistinctId() 方法获取到 distinct_id 。

后端方式：

可以在 Cookie 里面找到 key 为 sensorsdata2015jssdkcross 的 value 值然后进行 decodeURIComponent 解码，最后通过 JSON.parse 方法得到一个对象，对象里面的 distinct_id 即为用户所需要的。

2.1 在登录和注册成功后，调用sa.login(user_number) 来标识真实用户

参考产品提供的埋点事件设计文档

注意：用户唯一标识，登录前记录cookieId,登录后记录用户编号

通过 sa.login(user_number) 来把 SDK 自动生成的 cookie_id 关联成现在传入的 user_number。且以后会一直使用这个 user_number。

sa.login('123132');

问题1，这行代码放在哪里？

建议放在所有事件前面。也就是在 sdk 载入代码后面，先使用 sa.login （如果此时有这个 user_id 的话），然后再用 sa.quick('autoTrack') 等，这样后续的事件才会使用这个更改后的 userid。

问题2，在什么时候调用？

页面登录的时候，只要获取到用户是登录状态，就需要调用。或者注册流程成功的时候。

问题3，sa.login 和 sa.identify 有什么区别？

2.2 使用 sa.identify 来修改匿名 id

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

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

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

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

通过 sa.logout() 来永久改变当前的 distinct_id 为 cookie_id 。

sa.logout(); // 取消当前 login 的 id，改成最初自动生成的 cookie_id

sa.logout(true); // 取消当前 login 的 id，重新生成一个新的 cookie_id

问题1，这个在什么时候使用？

在你用过 sa.login 后，在一个浏览器有多个用户登录的时候，你想在用户退出后改变当前的 distinct_id。

3. 自定义事件追踪

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

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

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

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

// 追踪浏览商品事件。
sa.track('ViewProduct', {
   productId: '123456',
   productCatalog: "Laptop Computer",
   productName: "MacBook Pro",
   productPrice: 123.45
});

另外，神策分析 SDK 也支持自动进行一些事件的追踪，具体请参考：默认事件追踪。

3.1 SDK 默认属性

对于任何事件，神策分析 SDK 都会自动收集浏览器、操作系统、地域等一系列系统信息作为事件属性。完整的默认属性列表请参考：数据格式。

3.1.1 获取前端 JS SDK 采集的预置属性

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

sa.getPresetProperties();

3.2 事件公共属性

3.2.1 sa.registerPage(object)

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

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

sa.registerPage({
    current_url: location.href,
    referrer: document.referrer
});

sa.track('button_A_click'); // 这时候，这个 button_A_click 事件，就会带有current_url和referrer这些属性。且仅对当前页面有效。

4. 设置用户属性

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

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

4.1 sa.setProfile(properties[, callback])

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

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

sa.setProfile({email:'xxx@xx'});

4.2 sa.setOnceProfile(properties[, callback])

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

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

sa.setOnceProfile({email:'xxx@xx'});

4.3 sa.appendProfile(properties[, callback])

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

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

//给 category 增加两个值

sa.appendProfile({catrgory: ['玉米','白菜']});

//给 category 增加一个值

sa.appendProfile({catrgory: '玉米'});

4.4 sa.incrementProfile(properties[, callback])

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

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

// 表示 navClick 递减

sa.incrementProfile({'navClick': -1});

// 表示 navClick 递增2

sa.incrementProfile({'navClick': 2});

// 直接传入一个属性名，表示递增1

sa.incrementProfile('navClick');

4.5 sa.deleteProfile([callback])

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

callback function。{可选}

//删除当前这个用户及他的所有属性

sa.deleteProfile();

4.6 sa.unsetProfile(property[, callback])

删除当前用户的一些属性

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

//删除 email 和 location 属性

sa.unsetProfile(['email','location']);

//删除 email 属性

sa.unsetProfile('email');

5 数据类型说明

object: 上面 properties 是 object 类型。但是里面必须是 key: value 格式。且 value 必须只能是 string/number/date/boolean/array 这几种类型
string: 一般情况下的值都是 string 类型
number: 如 sa.incrementProfile 中会用到
datetime: 属性的值可以传入 new Date 的值即可(最终会自动转化成'2018-01-01 13:13:13.13')
date: 传入字符串'2018-01-01'即可
boolan: 属性的值可以是 true/false
array: array 里的必须是字符串。关于 array 类型限制请见数据格式。

6 其他

1 如果你想使用代码生成工具生成集成代码

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

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

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

神策 JavaScript SDK 使用说明

1. 获取和集成 JavaScript SDK

1.1 获取 JS SDK

我们这里推荐第三种通过 npm 安装的方式使用ES6导入的方式引用

1.2 集成 JavaScript SDK

1.2.1 SDK配置文件引入指南

1.2.2 如何埋点

1.3 配置 JavaScript SDK参数

1.4 如何确认数据发送成功

2. 如何标识用户

2.1 在登录和注册成功后，调用sa.login(user_number) 来标识真实用户

2.2 使用 sa.identify 来修改匿名 id

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

3. 自定义事件追踪

3.1 SDK 默认属性

3.1.1 获取前端 JS SDK 采集的预置属性

3.2 事件公共属性

3.2.1 sa.registerPage(object)

4. 设置用户属性

4.1 sa.setProfile(properties[, callback])

4.2 sa.setOnceProfile(properties[, callback])

4.3 sa.appendProfile(properties[, callback])

4.4 sa.incrementProfile(properties[, callback])

4.5 sa.deleteProfile([callback])

4.6 sa.unsetProfile(property[, callback])

5 数据类型说明

6 其他

1 如果你想使用代码生成工具生成集成代码

相关文章

网友评论

延伸阅读

深度阅读

栏目导航

热点阅读

神策 JavaScript SDK 使用说明

1. 获取和集成 JavaScript SDK

1.1 获取 JS SDK

我们这里推荐第三种 通过 npm 安装的方式 使用ES6导入的方式引用

1.2 集成 JavaScript SDK

1.2.1 SDK配置文件引入指南

1.2.2 如何埋点

1.3 配置 JavaScript SDK参数

1.4 如何确认数据发送成功

2. 如何标识用户

2.1 在登录和注册成功后，调用sa.login(user_number) 来标识真实用户

2.2 使用 sa.identify 来修改匿名 id

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

3. 自定义事件追踪

3.1 SDK 默认属性

3.1.1 获取前端 JS SDK 采集的预置属性

3.2 事件公共属性

3.2.1 sa.registerPage(object)

4. 设置用户属性

4.1 sa.setProfile(properties[, callback])

4.2 sa.setOnceProfile(properties[, callback])

4.3 sa.appendProfile(properties[, callback])

4.4 sa.incrementProfile(properties[, callback])

4.5 sa.deleteProfile([callback])

4.6 sa.unsetProfile(property[, callback])

5 数据类型说明

6 其他

1 如果你想使用代码生成工具生成集成代码

相关文章

网友评论

延伸阅读

深度阅读

栏目导航

热点阅读

我们这里推荐第三种通过 npm 安装的方式使用ES6导入的方式引用