Node SDK 使用说明

最后更新于：2018-08-07 17:33:49

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

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() 来设置 allowReNameOption 为 false。这种情况下，传递默认属性时，需要传递如 $app_version 风格的命名规范的键值和属性值，自定义属性如 orderId 会被保留当前驼峰的命名风格。默认属性格式规范请查看数据格式的介绍。

3. 使用 Node SDK

3.1 导入 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}.cloud.sensorsdata.cn:8006/sa?project={$project_name}&token={$project_token}')

3.2 追踪事件

用户通过 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.2.1 系统预置属性

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

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

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

3.2.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() 只可调用一次（通常在用户注册时调用），多次调用 trackSignup() 时，只有第一次关联行为是有效的。用户登录前后的行为的关联建议在业务端实现。更详细的说明请参考如何准确的标识用户，并在必要时联系我们的技术支持人员。

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. 设置 Node SDK

6.1 设置数据发送参数

ES6

import SensorsAnalytics from )'sa-sdk-node'

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

const sa = new SensorsAnalytics()

sa.disableReNameOption()

sa.submitTo(url)

采用自定义配置项目

import SensorsAnalytics from 'sa-sdk-node'

const url = 'http://xxx.cloud.sensorsdata.cn:8006/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.cloud.sensorsdata.cn:8006/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.cloud.sensorsdata.cn:8006/sa?token=xxx'

const sa = new SensorsAnalytics()

sa.disableReNameOption()

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

sa.subscribe(submitter)

6.2 批量发送

Batch Submit

WARN 批量发送不支持 debug 和 dryRun，会出现 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 })

7. 使用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.11 和 sa-sdk-node@1.1.1。

8. 更多信息

更多信息请访问 Github主页