1. Node SDK 使用说明

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

2. 集成神策分析 SDK

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

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

npm install sa-sdk-node --save

JS

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

2.1. 注意事项

在 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'
}
...
}

JS

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

2.2. 初始化神策分析 SDK

2.2.1. 获取配置信息

如下图所示获取数据接收地址：

2.2.2. 在程序中初始化 SDK

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

注意：submitTo 方式是网络直接发送数据，测试时候使用，不要在任何线上的服务中使用此 Consumer，线上推荐使用 LoggingConsumer。

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}')

CODE

至此，我们已经可以正常使用神策分析 SDK 了。需了解更多关于 SDK 的使用方法，可以跳到本文末尾的控制神策分析 SDK 一节。

3. 设置神策分析 SDK

Node SDK 主要由以下两个组件构成:

SensorsAnalytics：用于发送数据的接口对象
Consumer：Consumer 会进行实际的数据发送，通过不同的初始化方法，初始化不同的 Consumer

为了让开发者更灵活的接入数据，神策分析 SDK 实现了以下 Consumer：

LoggingConsumer
NWConsumer

3.1. LoggingConsumer（推荐）

用于将数据输出到指定目录并按天切割文件，支持通过参数指定是否按小时切割，一般用来处理实时数据，生成日志文件并使用 LogAgent 等工具导入。

初始化接口

var customPath = '/Users/user/logs';
sa.initLoggingConsumer(customPath, pm2Mode)

CODE

例子

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

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

CODE

LoggingConsumer 的第一个参数是保存文件前缀，每天 0 点切割保留所有文件。

按日切割关闭的情况下，文件将保存在以 prefix.YYYY-MM-DD（例如：假设 prefix 为 /data/sa/access.log，当天是 2018-04-13，则输出文件为 /data/sa/access.log.2018-03-13）

注意:

在生产环境下使用 pm2 的情况下，需要初始化时添加 pm2Mode(bool)，设置为 true。另外，还需要执行 pm2 install pm2-intercom。
调用 LoggingConsumer 初始化语句后，后续数据发送仍然调用原有模式下的接口，如 track 等，SDK 将自动将数据写入当前设置的日志路径里面。
对应的 SDK 版本最低为 sdk-sa-node@1.0.11 和 sa-sdk-node@1.1.1。

3.2. NWConsumer

从 1.2.0 版本开始 Node SDK 中还提供了 NWConsumer ，NWConsumer 的主要作用是实时上报数据到 SA 环境中，当网络发生异常的时候会把数据缓存在本地，在下次应用启动的时候会上报缓存的数据。

初始化接口

// option 包含 url 数据接受地址，cachePath 缓存路径及 timeout 发送数据超时时间
sa.initNWConsumer(option)

CODE

例子

// 初始化 sa 实例后，不需要设置数据发送地址，只需要通过调用如下语句，设置日志文件存放的目录，这里建议使用绝对路径
const cachePath = '/Users/user/cachePath';
const url = 'http://xxx.datasink.sensorsdata.cn/sa?token=xxx'
sa.initNWConsumer({
  url: URL, // 数据接收地址
  cachePath: __dirname, // 缓存路径
  timeout: 30 * 1000 // 发送数据超时时间
})
// ...

CODE

注意：

调用 NWConsumer 初始化语句后，后续数据发送仍然调用原有模式下的接口，如 track 等，SDK 将发送失败的数据写入当前设置的缓存数据库里面，并在下次应用启动的时候会上报缓存的数据。对应的 SDK 版本最低为 sdk-sa-node@1.2.0。

4. API 接口

针对 API 接口的使用文档，参照基础 API 使用文档介绍。