THE MAINTENANCE IS MOVED TO OFFICIAL REPO:

https://github.com/sensorsdata/sa-sdk-node

Sensors Analytics

This is the home-brewed version of Node SDK for Sensors Analytics.

Install

Install using npm.

$ npm install sa-sdk-node --save

Usage

Basic Usage

1import SensorsAnalytics from 'sa-sdk-node'
2
3const sa = new SensorsAnalytics()
4
5sa.submitTo('http://xxx.cloud.sensorsdata.cn:8006/sa?token=xxx')
6
7// Super Properties that assigned to every event tracking
8sa.registerSuperProperties({ $appVersion: '1.0.0', env: 'production' })
9
10// Track event
11sa.track('user-id', 'userHappy')
12
13// Track event with custom properties
14sa.track('user-id', 'newOrder', { orderId: '12323' })
15
16// Track Signup
17sa.trackSignup('user-id', 'anonymous-id/device-id')
18
19// Track Signup with custom properties
20sa.trackSignup('user-id', 'anonymous-id/device-id', { userType: 'administrator' })
21
22// Manipuate user project
23sa.profileSet('user-id', { age: 18 })
24sa.profileSetOnce('user-id', { registerTime: new Date().valueOf() })
25sa.profileIncrement('user-id', { scoreCount: 100, issueCount: -1 })
26sa.profileAppend('user-id', { tags: ['student', 'developer'] })
27sa.profileUnset('user-id', ['temporaryTag'])
28

For more detailed information about each api, checkout Sensors Analytics manual

Override event time

By default, the library uses current time as the time when event occurs, but the behavior can be overrode by $time property.

• Both track and trackSignup support this feature.
• $time can be Date, number, string, Moment instance

1import moment from 'moment'
2
3sa.track('user-id', 'newOrder', { orderId: '12323', $time: new Date(2016,7,30) })
4sa.track('user-id', 'newOrder', { orderId: '12323', $time: '2016-07-30T00:00:00+08:00' })
5sa.track('user-id', 'newOrder', { orderId: '12323', $time: 1469808000000 })
6sa.track('user-id', 'newOrder', { orderId: '12323', $time: moment() })
7
8sa.trackSignup('user-id', 'anonymous-id/device-id', { $time: new Date(2016,7,30) })
9sa.trackSignup('user-id', 'anonymous-id/device-id', { $time: '2016-07-30T00:00:00+08:00' })
10sa.trackSignup('user-id', 'anonymous-id/device-id', { $time: 1469808000000 })
11sa.trackSignup('user-id', 'anonymous-id/device-id', { $time: moment() })

Parse Geolocation

SensorsData support parsing user geo location from IP address.

• Both track and trackSignup support this feature.

1router.post('/api/new-order', (req, res) => {
2  sa.track(req.session.userId, 'newOrder', { $ip: req.ip })
3
4  // ...
5})

Parse User Agent

Node SDK supports parsing client OS, OS version, Browser, Browser version, Browser Engine, Model from client's User Agent

• Both track and trackSignup support this feature.

1router.post('/api/new-order', (req, res) => {
2  sa.track(req.session.userId, 'newOrder', { $userAgent: req.get('user-agent') })
3  // ...
4})

Config Submitter

By default, submitter can be created with server url

1import SensorsAnalytics from 'sa-sdk-node'
2
3const url = 'http://xxx.cloud.sensorsdata.cn:8006/sa?token=xxx'
4
5const sa = new SensorsAnalytics()
6
7const submitter = sa.submitTo(url)

But it also can be created with explicit config

1import SensorsAnalytics from 'sa-sdk-node'
2
3const url = 'http://xxx.cloud.sensorsdata.cn:8006/sa?token=xxx'
4
5const sa = new SensorsAnalytics()
6
7const submitter = sa.submitTo({ url, gzip: true, mode: 'track', timeout: 10 * 1000 })
8// gzip: whether enable gzip, default to true
9// mode: could be 'track' (production use), 'debug' (diagnosis data), 'dryRun' (diagnosis with no data recorded),
10//       also supports the values that aligned to other SDKs: debug_off, debug_and_track and debug_only,
11//       default to track
12// mode:
13// timeout: Http timeout in ms, default to 10s

Submitter can be create manually and attach to SensorsAnalytics manually

Created with url with default config

1import SensorsAnalytics, { Submitter } from 'sa-sdk-node'
2
3const url = 'http://xxx.cloud.sensorsdata.cn:8006/sa?token=xxx'
4
5const sa = new SensorsAnalytics()
6
7const submitter = new Submitter(url)
8
9sa.subscribe(submitter)

Or with explicit config

1import SensorsAnalytics, { Submitter } from 'sa-sdk-node'
2
3const url = 'http://xxx.cloud.sensorsdata.cn:8006/sa?token=xxx'
4
5const sa = new SensorsAnalytics()
6
7const submitter = new Submitter({ url, gzip: true, mode: 'track', timeout: 10 * 1000 })
8
9sa.subscribe(submitter)

Network error handling

1submitter.catch((err) => console.error(err))

Batch Submit

WARN Batch submit is not supported by debug or dryRun mode. It causes 400 bad-request error

Suppose

1import SensorsAnalytics, { Submitter } from 'sa-sdk-node'
2
3const url = 'http://xxx.cloud.sensorsdata.cn:8006/sa?token=xxx'
4
5const sa = new SensorsAnalytics()

Batch with count

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

Batch with time

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

Batch with time or count

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

Create batch manually

Batch can be created manually if needed, which can be subscribed with submitter later

1const batch = sa.inBatch({ count: 20, timeSpan: 5 * 1000 })
2
3batch.subscribe(new Submitter(url))

Advanced Usage

This library is powered by Microsoft's RxJS.

SensorsAnalytics is an Observable, which yields tracking data.

Submitter is an Observer, which consume the tracking data.

Submitter is also an Observable, which yields next when submitted succeeded, and yields Error when network errors.

Ideally, you can use all RxJS tricks with this library

Filtering

1// All the event that raised by debug build app won't be submitted
2sa.filter((event) => event.properties.releaseType !== 'debug')
3  .subscribe(submitter)

Debounce

1// Useful while tracking user input or other case
2// The event won't be tracked unless user has stopped typing for 500ms
3sa.debounce(500)
4  .subscribe(submitter)
5
6textInput.onChange((text) => sa.track(userId, 'userType', { text }))

More Detail

For more detail, checkout Microsoft's Rx documentation

License

MIT