1. Node SDK use introduction

Before using, please readdata model introduction.

2. Integrated Sensors Analytics SDK

Integration in NodeJS Sensors Analytics SDK, collect and analyze user data using sensors analytics.

We recommended use npm manage the Node module and get the strategy analysis SDK:

npm install sa-sdk-node --save

Note: Currently, only Node versions 4.x and later are supported.

2.1. Matters needing attention

In 1.0.8 and above, add one allowReNameOption option, the default value is true, in this case, format the property values and key values into an underline style naming format, for example:

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

Can call sa.disableReNameOption() 来设置 allowReNameOption  false. In this case, when passing the default property, you need to pass such as$app_version Style naming conventions for key values and attribute values, custom attributes such asorderId The current naming style of the hump will be retained.See the default attribute format specificationdata format introduction.

2.2. Initialization Sensors analytics SDK

2.2.1. Get configuration information

Get the data receiving address as shown below:

2.2.2. Initialize the SDK in the program

Construct an instance of the analysis SDK in the code snippet initialized in the program:

Note:submitTo methodis the network that sends data directly, for testing,Do not use this Consumer in any online service,Recommended use online 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}')

At this point, we can use the Smart Analysis SDK normally. To learn more about how to use the SDK, skip to the Control Strategy Analysis SDK section at the end of this article.

3. Set Sensors Analytics SDK

Node SDK mainly consists of the following two components

  • SensorsAnalytics: Interface object used to send data
  • Consumer: The consumer actually sends the data and initializes different consumers through different initialization methods

In order to allow developers to access data more flexibly, the Sensors Analytics SDK implements the following consumers:

  • LoggingConsumer
  • NWConsumer

3.1. LoggingConsumer (recommended)

Used to output data to the specified directory and split files by day. It supports specifying whether to split files by hour through parameters. It's generally used to process real-time data, generate log files, and import them using tools like LogAgent.

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

The first parameter of LoggingConsumer is the prefix to save the file, and all files are kept when split by day at 00:00.

  • When the daily split is turned off, the file will be saved in prefix.YYYY-MM-DD format (e.g., assuming the prefix is /data/sa/access.log and the current day is 2018-04-13, the output file will be /data/sa/access.log.2018-03-13)


  1. In the production environment using pm2, you need to add Log-agent in the initialization. Set pm2Mode (bool) to true. In addition, you need to execute pm2 install pm2-intercom.
  2. After calling the initialization statement of LoggingConsumer, subsequent data sending still calls the interface in the original mode, such as track. The SDK will automatically write the data to the currently set log path.
  3. The corresponding SDK version has a minimum requirement of sdk-sa-node@1.0.11 and sa-sdk-node@1.1.1.

3.2. NWConsumer

Starting from version 1.2.0 of the Node SDK, the NWConsumer is also provided in the Node SDK. The main role of NWConsumer is to report data to the SA environment in real-time. When a network exception occurs, the data will be cached locally and will be reported when the application restarts.

  • Initialization interface
// option 包含 url 数据接受地址,cachePath 缓存路径及 timeout 发送数据超时时间 sa.initNWConsumer(option)
  • Example
// 初始化 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 // 发送数据超时时间 }) // ...


After calling NWConsumer initialization statement, subsequent data transmission still calls the interface under the original mode, such as track, etc. The SDK writes the failed data into the currently set cache database and will report the cached data when the application starts next time. The corresponding minimum version of the SDK is sdk-sa-node@1.2.0.

4. API Interface

For the usage documentation of the API interface, please refer to the basic API documentation.