Node SDK 使用说明

最后更新于:2019-08-19 11:22:07

在使用前,请先阅读数据模型的介绍。

1. 集成神策分析 SDK

在 NodeJS 中集成 神策分析 SDK,使用神策分析采集并分析用户数据。

我们推荐使用 npm 管理 Node 模块并获取神策分析 SDK:

npm install sa-sdk-node --save

注: 目前只支持 4.x 及以上 Node 版本

2. 注意事项

在1.0.8及之后版本中,添加了一个 allowReNameOption 选项,默认值为 true,在此情况下将属性值和键值格式化为下划线风格命名格式,例如:

sa.track('user-id', 'userHappy', {
  '$appVersion': '1.0.0',
  'orderId': '123'
})

//then we get data

{
...
'event': 'user_happy'
'properties': {
  '$app_version': '1.0.0',
  'order_id': '123'
}
...
}

可以通过调用 sa.disableReNameOption() 来设置 allowReNameOptionfalse。这种情况下,传递默认属性时,需要传递如 $app_version 风格的命名规范的键值和属性值,自定义属性如 orderId 会被保留当前驼峰的命名风格。默认属性格式规范请查看数据格式的介绍。

3. 使用 Node SDK

3.1 获取配置信息

首先从神策分析的主页中,获取数据接收的 URL 和 Token(Cloud 版)。

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

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

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

其中 {$host_name} 可以是集群中任意一台机器。

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

3.2 导入 SDK

在程序中初始化的代码段中构造神策分析 SDK 的实例:

ES6:

import SensorsAnalytics from 'sa-sdk-node'

const sa = new SensorsAnalytics()
sa.disableReNameOption()

non-ES6:

var SensorsAnalytics = require('sa-sdk-node')
var sa = new SensorsAnalytics;
sa.disableReNameOption()

sa.submitTo('http://{$service_name}.datasink.sensorsdata.cn/sa?project={$project_name}&token={$project_token}')

3.3 追踪事件

用户通过 track() 接口记录事件,对于任何事件,必须包含用户标志符(distinct_id)和事件名(event_name)两个参数。同时,用户可以在 track() 的第三个参数为事件添加自定义事件属性,在自定义属性中需要包含 $is_login_id 属性来说明 distinct_id 是否为登录 ID。以电商产品为例,可以这样追踪一次购物行为:


var distinct_id = 'ABCDEF123456'
var properties = {
    // '$time' 属性是系统预置属性,传入 datetime 对象,表示事件发生的时间,如果不填入该属性,则默认使用系统当前时间
    '$time' : datetime.datetime.now(),
    // '$ip' 属性是系统预置属性
    '$ip' : '123.123.123.123',
    // $is_login_id 属性判断 distinct_id 是否为登录 ID,如果是则设置为 true,否则为 false,默认为 false
    '$is_login_id' : True,
    // 商品 ID
    'ProductId' : '123456',
    // 商品类别
    'ProductCatalog' : 'Laptop Computer',
    // 是否加入收藏夹,Boolean 类型的属性
    'IsAddedToFav' : True,
}

// 记录用户浏览商品事件
sa.track(distinct_id, 'ViewProduct', properties)

var properties = {
    // 用户 IP 地址
    '$ip' : '123.123.123.123',
    // $is_login_id 属性判断 distinct_id 是否为登录 ID,如果是则设置为 true,否则为 false,默认为 false
    '$is_login_id' : True,
    // 商品 ID 列表,list<str> 类型的属性
    'ProductIdList' : ['123456', '234567', '345678'],
    // 订单价格
    'OrderPaid' : 12.10,
}

// 记录用户订单付款事件
sa.track(distinct_id, 'PaidOrder', properties)

3.3.1 系统预置属性

如前文中样例,事件属性中以 '$' 开头的属性为系统预置属性,在自定义事件属性中填入对应 '$' 开头的属性值可以覆盖这些预置属性:

  • $ip - 填入该属性,神策分析会自动根据 IP 地址解析用户的省份、城市信息,该属性值为 str 类型;
  • $time - 填入该属性,神策分析将事件时间设置为属性值的时间,该属性值必须为 datetime.datetimedatetime.date 类型。请注意,神策分析默认会过滤忽略 365 天前或 3 天后的数据,如需修改请联系我们。

关于其他更多预置属性,请参考 数据格式 中 '预置属性' 一节。

3.3.2 事件公共属性

特别地,如果某个事件的属性,在所有事件中都会出现,可以通过 registerSuperProperties() 将该属性设置为事件公共属性。例如,应用版本设置为所有事件共有属性方法如下:

sa.registerSuperProperties({
  $appVersion: '1.0.0',
  env: 'production'
});

成功设置事件公共属性后,再通过 track() 追踪事件时,事件公共属性会被添加进每个事件中。

4. 用户识别

在服务端应用中,神策分析也要求为每个事件设置用户的 Distinct Id,这有助于神策分析提供更准确的留存率等数据。

对于注册用户,推荐使用系统中的用户 ID 作为 Distinct Id,不建议使用用户名、Email、手机号码等可以被修改的信息。

4.1 用户注册/登录

当同一个用户的 Distinct Id 发生变化时(一般情况为匿名用户注册行为),可以通过 trackSignup() 将旧的 Distinct Id 和新的 Distinct Id 关联,以保证用户分析的准确性。例如:


// 匿名 ID 由前端传过来
var anonymousId = "9771C579-71F0-4650-8EE8-8999FA717761";

String registerId = "0012345678";
// 用户注册/登录时,将用户注册 ID 与 匿名 ID 关联
sa.trackSignup(registerId, anonymousId);

注意,对同一个用户,trackSignup() 一般情况下建议只调用一次(通常在用户 注册 时调用),用户 登录 前后的行为的关联建议在业务端实现。在神策分析 1.13 版本之前,多次调用 trackSignup() 时,只有第一次关联行为是有效的。神策分析 1.13 版本之后提供了多设备 id 关联的方法。更详细的说明请参考 如何准确的标识用户,并在必要时联系我们的技术支持人员。

5. 设置用户属性

为了更准确地提供针对人群的分析服务,神策分析 SDK 可以设置用户属性,如年龄、性别等。用户可以在留存分析、分布分析等功能中,使用用户属性作为过滤条件或以用户属性作为维度进行多维分析。

使用 profileSet() 设置用户属性:


var properties = {
// 设置用户等级属性(Level)为 VIP
  'UserLv': 'Elite VIP',
// $is_login_id 属性判断 distinct_id 是否为登录 ID,如果是则设置为 true,否则为 false,默认为 false
  '$is_login_id' : True,
}

sa.profileSet(distinctId, properties);

对于不再需要的用户属性,可以通过 profileUnset() 接口将属性删除。

用户属性中,属性名称与属性值的约束条件与事件属性相同,详细说明请参考 数据格式

5.1 记录初次设定的属性

对于只在首次设置时有效的属性,我们可以使用 profileSetOnce() 记录这些属性。与 profileSet() 接口不同的是,如果被设置的用户属性已存在,则这条记录会被忽略而不会覆盖已有数据>,如果属性不存在则会自动创建。因此,profileSetOnce() 比较适用于为用户设置首次激活时间、首次注册时间等属性。例如:


var distinctId = "ABCDEF123456789";

// 设置用户渠道属性(AdSource)为 "App Store"
sa.profileSetOnce(distinctId, {
  "AdSource": "App Store"
// $is_login_id 属性判断 distinct_id 是否为登录 ID,如果是则设置为 true,否则为 false,默认为 false
  '$is_login_id' : True,

});

// 再次设置用户渠道属性(AdSource),设定无效,属性 "AdSource" 的值仍为 "App Store"
sa.profileSetOnce(distinctId, {
   "AdSource": "Search Engine",
// $is_login_id 属性判断 distinct_id 是否为登录 ID,如果是则设置为 true,否则为 false,默认为 false
  '$is_login_id' : True,
});

6. 物品元数据上报

在神策推荐项目中,客户需要将物品元数据上报,以开展后续推荐业务的开发与维护。神策分析 SDK 提供了设置与删除物品元数据的方法。

item_id(物品 ID )item_type (物品所属类型)共同组成了一个物品的唯一标识。所有的 item 系列方法都必须同时指定物品 ID物品所属类型这两个参数,来完成对物品的操作。

6.1 设置物品

直接设置一个物品,如果已存在则覆盖。除物品 ID 与 物品所属类型外,其他物品属性需在 properties 中定义。

物品属性中,属性名称与属性值的约束条件与事件属性相同,详细说明请参考 数据格式


// 商品 Type
const itemType = 'book'
// 商品 ID
const itemId = '0321714113'
// 商品信息
const properties = {
  name: 'C++ Primer',
  price: 31.54,
}
// 添加商品
sa.itemSet(itemType, itemId, properties)

6.2 删除一个物品

如果物品不可被推荐需要下线,删除该物品即可,如不存在则忽略。

除物品 ID 与 物品所属类型外,不解析其他物品属性。


// 商品 Type
const itemType = 'book'
// 商品 ID
const itemId = '0321714113'
// 删除商品
sa.itemDelete(itemType, itemId)

7. 设置 Node SDK

7.1 设置数据发送参数

ES6


import SensorsAnalytics from )'sa-sdk-node'

const url = 'http://xxx.datasink.sensorsdata.cn/sa?token=xxx'

const sa = new SensorsAnalytics()

sa.disableReNameOption()

sa.submitTo(url)

采用自定义配置项目


import SensorsAnalytics from 'sa-sdk-node'

const url = 'http://xxx.datasink.sensorsdata.cn/sa?token=xxx'

const sa = new SensorsAnalytics()

sa.disableReNameOption()

const submitter = sa.submitTo({ url, gzip: true, mode: 'track', timeout: 10 * 1000 })
// gzip: 是否支持gzip,默认为 true
// mode:
//   三种模式: track(生产环境使用),debug(校验数据并上传),dryRun(只校验数据,不上传),默认模式是 track
// timeout: http超时,单位毫秒(ms),默认值为 10s

import SensorsAnalytics, { Submitter } from 'sa-sdk-node'

const url = 'http://xxx.datasink.sensorsdata.cn/sa?token=xxx'

const sa = new SensorsAnalytics()

const submitter = new Submitter(url)

sa.disableReNameOption()

sa.subscribe(submitter)
import SensorsAnalytics, { Submitter } from 'sa-sdk-node'

const url = 'http://xxx.datasink.sensorsdata.cn/sa?token=xxx'

const sa = new SensorsAnalytics()

sa.disableReNameOption()

const submitter = new Submitter({ url, gzip: true, mode: 'track', timeout: 10 * 1000 })

sa.subscribe(submitter)

7.2 批量发送

Batch Submit

WARN 批量发送不支持 debugdryRun,会出现 400 错误。

按照数量大包发送


// Submit when 20 events are tracked
sa.submitTo(url, { count: 20 })

按时间发送

// Submit when every 5 seconds
sa.submitTo(url, { timeSpan: 5 * 1000 })

时间和数据量结合


// Submit every 5 seconds, but also submit immediately if 20 events tracked
sa.submitTo(url, { count: 20, timeSpan: 5 * 1000 })

8. 使用LoggingConsumer

Node SDK 中还提供了 LoggingConsumer ,如果启用,将不通过 Node 模块进行数据发送,而将所有数据都写到本地的日志文件里,然后用户再使用 LogAgent 读取日志文件,将数据导入我们的系统。

WARN 注意在生产环境下使用 pm2 的情况下,需要初始化时添加pm2Mode(bool),设置为true。另外,还需要执行pm2 install pm2-intercom


// 初始化 sa 实例后,不需要设置数据发送地址,只需要通过调用如下语句,设置日志文件存放的目录,这里建议使用绝对路径
var customPath = '/Users/user/logs';
sa.initLoggingConsumer(customPath, pm2Mode)

调用 LoggingConsumer 初始化语句后,后续数据发送仍然调用原有模式下的接口,如 track 等,SDK 将自动将数据写入当前设置的日志路径里面。 对应的 SDK 版本最低为 sdk-sa-node@1.0.11sa-sdk-node@1.1.1

9. 更多信息

更多信息请访问 Github主页