Node.js

Iteratively supports tracking analytics events from Node.js apps written in JavaScript (ES6 and above) and TypeScript (2.1 and above). The generated tracking library is packaged as a CJS module.

In TypeScript, the tracking library exposes a type-safe function for every event in your team’s tracking plan. The function’s arguments correspond to the event’s properties and are strongly typed to allow for code completion and compile-time checks.

Since JavaScript is not a type-safe language, the library won't expose type-safe functions for the events in your team’s tracking plan. Instead, the auto-generated library performs those checks at runtime.

Installation#

Generate the SDK#

If you have not yet installed the Itly CLI, install it now.

To generate the Itly SDK, run itly init and itly pull {source} in the folder with your package.json file. By default, the SDK will be generated in ./src/itly/.

Tip

{source} is the name of the source you created in your tracking plan (e.g. backend).

Install dependencies#

The generated Itly SDK has several dependencies. To install them, run:

npm
Yarn

npm install @itly/sdk \
            @itly/plugin-iteratively-node \
            @itly/plugin-schema-validator

If you're using Segment, Amplitude, or Mixpanel, the SDK will also depend on a few additional plugins that must be installed before your project will compile:

npm
Yarn

# if you're using Segment
npm install @itly/plugin-segment-node
# if you're using Mixpanel
npm install @itly/plugin-mixpanel-node
# if you're using Amplitude
npm install @itly/plugin-amplitude-node

Note

To validate your analytics events, the SDK depends on ajv (MIT).
To send events to Segment, the SDK depends on analytics-node (MIT).
To send events to Mixpanel, the SDK depends on mixpanel (MIT).
To send events to Amplitude, the SDK depends on amplitude.

Import into your app#

To use the library, you'll need to import it first:

TypeScript
JavaScript

import itly from './itly';

You can now call functions on itly directly.

Note

Adjust the relative import path to the location where itly pull generated your SDK. By default, this path is ./src/itly.

API#

Load#

Load the Itly SDK once when your application starts. The load() function accepts an options object to configure the SDK's behavior:

TypeScript
JavaScript

itly.load({ environment: 'development' });

Option
`context`	Object `Context`	required	An object with a set of properties to add to every event sent by the Itly SDK. Only available if there is at least one source template associated with your your team's tracking plan.
`disabled`	Boolean	optional	Specifies whether the Itly SDK does any work. When `true`, all calls to the Itly SDK will be no-ops. Useful in local or development environments. Defaults to `false`.
`environment`	String	optional	Specifies the environment the Itly SDK is running in: `production` or `development`. Environment determines which Access Token is used to load the underlying analytics provider libraries. The option also determines safe defaults for handling event validation errors. In production, when the SDK detects an invalid event, it will log an error but still let the event through. In development, the SDK will throw an exception to alert you that something is wrong. Defaults to `development`.
`destinations`	Object `DestinationsOptions`	optional	Specifies any analytics provider-specific configuration. The Itly SDK passes these objects in when loading the underlying analytics provider libraries.
`validation`	Object `ValidationOptions`	optional	Configures the Itly SDK's behavior when events or traits fail validation against your tracking plan. Supports the following properties: `disabled` Disables validation altogether. Defaults to `false`. `trackInvalid` Secifies whether events that failed validation should still be tracked. Defaults to `false` in development, `true` in production. `errorOnInvalid` Specifies whether the SDK should throw an exception when validation fails. Defaults to `true` in development, `false` in production.
`plugins`	Array	optional	An array of additional plugins to load into the Itly SDK. Plugins allow you to extend the Itly SDK's event validation and event tracking functionality with your own. For example, a plugin can be used to implement a custom destination or a custom event validator. Click here to learn about writing a custom destination plugin. Click here to see a sample custom destination plugin written in JavaScript. Click here to see a sample custom destination plugin written in TypeScript.

Identify#

Call identify() to set a particular user's traits.

Just as Iteratively creates types for events and their properties (and validates them at runtime), Iteratively creates types for user traits (and validates them at runtime).

The identify() function accepts a required userId and required traits.

For example, in the code snippet below, our tracking plan contains a user trait called role. The trait's type is a string.

TypeScript
JavaScript

itly.identify('user-id', { role: 'admin' });

Group#

Call group() to associate a user with their group (for example, their department or company), or to set the group's traits.

Just as Iteratively creates types for events and their properties (and validates them at runtime), Iteratively creates types for group traits (and validates them at runtime).

The group() function accepts a required userId, groupId, and optional traits.

For example, in the code snippet below, our tracking plan contains a group trait called name. The trait's type is a string.

TypeScript
JavaScript

itly.group('user-id', 'group-id', { name: 'Iteratively, Inc.' });

Track#

To track an event, call the event’s corresponding function. Every event in your tracking plan gets its own function in the Itly SDK.

For example, in the code snippet below, our tracking plan contains an event called Process Started. The event was defined with one required property called availableProcessors. The property's type is an integer.

TypeScript
JavaScript

itly.processStarted({ availableProcessors: os.cpus().length });

Custom Destination#

Advanced

If you're using Iteratively with Segment, Amplitude, Mixpanel, or Snowplow, you can safely skip this section!

To send clean, valid events to custom analytics destinations, or those not yet supported by the Itly SDK natively, the SDK is extensible via plugins. Writing a plugin is easy! Extend the PluginBase class, override track(), and include your new plugin in the plugins array when calling itly.load().

Plugins allow you to implement your own processing logic for analytics tracking. When you call a function on the Itly SDK, the SDK will first validate your event (or user, group, and page properties) against your tracking plan, then call into your plugin's implementation.

The following functions are available to override when developing your plugin. Only override those functions that matter to your custom destination.

Examples

A sample custom destination plugin is available here in JavaScript and here in TypeScript.

ID#

Every plugin has a unique ID. To set one, override id() and return your plugin's ID. The function has the following signature:

id(): string;

Load#

Called when the Itly SDK is being loaded and is ready to load your plugin. The function has the following signature:

load(options: Options): void;

Argument
`options`	Object `Options`	required	The same configuration object passed to `itly.load()` when the SDK was being initialized.

Alias#

Called when Itly SDK's alias() function is called to associate one user ID with another (typically a known user ID with an anonymous one). The alias() function has the following signature:

alias(userId: string, previousId: string): void;

Argument	Type		Description
`userId`	String	required	The ID that the user will be identified by going forward. This is typically the user's database ID (as opposed to an anonymous ID), or their updated ID (for example, if the ID is an email address which the user just updated).
`previousId`	String	required	The ID the user has been identified by so far.

Identify#

Called when Itly SDK's identify() function is called to identify a user with a specific ID or set the user's traits. The identify() function has the following signature:

identify(userId: string, properties: Properties): void;

Argument	Type		Description
`userId`	String	required	The user's ID, if it was provided to `itly.identify()`. The ID may not be provided if `identify()` was called only to update the user's traits.
`properties`	Object `Properties`	required	The user's traits.

Track#

Called when an event is tracked. The function receives a validated event with its complete set of properties (a combination of the event's own properties any any other properties associated with the source via a source template) The track() function has the following signature:

track(userId: string, event: Event): void;

Argument	Type		Description
`userId`	String	required	Always undefined in the Browser SDK.
`event`	Object `Event`	required	The event that was tracked by the Itly SDK. The event object contains the following properties: `name` The event's name. `properties` The event's properties. `id` The event's unique ID in Iteratively. `version` The event's version, e.g. 2.0.1.

Group#

Called when Itly SDK's group() function is called to associate the user with a specific account (for example, their department or company) or set the group's properties. The group() function has the following signature:

group(userId: string, groupId: string, properties?: Properties | undefined): void;

Argument	Type		Description
`userId`	String	required	Always undefined in the Browser SDK.
`groupId`	String	required	The ID of the group (for example, the user's department or company) to associate the user with.
`properties`	Object `Properties`	optional	The group's traits.

Page#

Called when Itly SDK's page() function is called to track a page view in a web application. The page() function has the following signature:

page(userId: string, category: string | undefined, name: string | undefined, properties: Properties | undefined): void;

Argument	Type		Description
`userId`	String	required	Always undefined in the Browser SDK.
`category`	String	optional	The page's category. Useful when many pages might live under a single category.
`name`	String	optional	The page's name.
`properties`	Object `Properties`	optional	The page's traits.

Reset#

Called when Itly SDK's reset() function is called to reset the SDK's (and all plugins') state. This method is usually called when a user logs out. The reset() function has the following signature:

reset(): void;