ironSource.atom SDK for Node-JS
atom-node is the official ironSource.atom SDK for Node.JS Javascript runtime
Installation
Installation using npm
$ npm install atom-node --save
Usage
High Level SDK - "Tracker"
The tracker is used for sending events to Atom based on several conditions
- Every 10 seconds (default)
- Number of accumulated events has reached 250 (default)
- Size of accumulated events has reached 128KB (default)
Case of server side failure (500) the tracker uses an exponential back off mechanism with jitter.
For a list of all available tracker config options, check the docs
const AtomTracker = Tracker;;
Tracker Flow Control
The methods: track() and flush() are decoupled and independent of each other.
track() method behaviour:
Tracks data to backlog, returns a Promise which will be resolved only when data is tracked to backlog.
The function rejects the Promise in 3 cases:
- Stream and/or Data are missing.
- Tracker has been stopped.
- In Non-blocking mode and
trackingTimeout
has been reached.
track() by default is blocking, but you can set it as non-blocking.
Note: blocking means that it will block new track() calls and not the whole event loop.
If block is true (the default) => block if necessary until a free slot is available.
If block is false and timeout is a positive number: blocks at most timeout seconds (10 seconds by default)
and emit and error event if no free slot was available within that time.
Tracker Error Handling
All track() errors need to be handled by a regular try-catch block.
All flush() errors are handled by error
event.
See here for all usage examples
Error event is mandatory and you must listen to it.
tracker;
Tracker Events:
Except for 'error', the tracker emits this optional events:
- retry - on first retry to server (500)
The following are called only when there is a graceful shutdown: - stop - when stop() is called or when tracker gets a killing signal
- empty - when the backlog is empty and there are no more in-flight msgs
tracker;tracker;tracker;
Tracker Backlog
The tracker is using a simple in memory storage for its backlog
You can replace it with a custom backlog using the same interface
const AtomTracker = Tracker;const params = backlog: let tracker = params;
Tracker Logger
The tracker is using a simple logger based on console, you can replace it with your own (bunyan for example)
const AtomTracker = Tracker;const params = logger: myLoggerModulelet tracker = params;
Low Level (Basic) SDK
The Low Level SDK has 2 methods:
- putEvent - Sends a single event to Atom
- putEvents - Sends a bulk (batch) of events to Atom (must be an array)
'use strict';const AtomReporter = ISAtom;const options = endpoint: "https://track.atom-data.io/" auth: "YOUR_API_KEY"; let atom = options;let params = stream: "STREAM_NAME" // Your target stream name data: JSON // Object / Stringified Json// With co (POST):; // With Promisesparamsmethod = 'POST';atom; // PutEvents (batch):let batchPayload = stream: "STREAM_NAME" // Your target stream name data: name: "iron" last_name: "Beast" name: "iron2" last_name: "Beast2" // Array with Json / Stringified Json;atom;
Change Log
v1.6.0
- Changed flow control to make it more clear and reliable (see Usage)
- Removed FlushOnExit param - tracker will always try to flush on exit
- Added a tracking timeout option - works only on non-blocking mode
- Added a blocking / non-blocking toggle.
- Tracker flush mechanism now emits events on: stop, first retry, empty & error
- onError callback replaced with "error" event.
v1.5.2
- Fixed broken headers
- Added more parameters to the onError func
- Added Limits to SDK Bulk Length and Bulk Size & Flush Interval
v1.5.1
- Updated npm package conf
- Updated readme
- Changed project directory structure
v1.5.0
- Refactored Request class
- Refactored Atom class
- Refactored Tracker
- Fixed a bug in Tracker exit handler (there was no delay on graceful shutdown)
- Added an option to add a callback on error (after max retries reached)
- Changed example
- Added more options to conf
- Rewrote all tests and increased coverage
- Updated README
- Updated all docs and changed them from apiDoc to JSDoc
- Fixed a bug with headers not being sent
- Added AtomError custom Error
v1.2.0
- Fixed tracker retry bug - caused by mutating an object that was passed by reference
- increased test coverage
- Updated README.MD
v1.1.2
- Fixed tests and removed unused dependencies
- Updated tests to run on LTS
v1.1.0
- Added tracker
- Added Backoff mechanism
v1.0.0
- Basic features: putEvent & putEvents functionalities
Example
You can use our example for sending data to Atom.
node example/example.js -h Usage: example [options] Options: -h, --help output usage information -V, --version output the version number -p, --putevent Run the putEvent examples -P, --putevents Run the putEvents examples -H, --health run the health check example -t, --tracker run the tracker example -a, --all Run all of the examples