Node.js

Overview

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 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:

# 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:

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:

itly.load({ environment: 'development' });
Option
contextObject
Context
requiredAn 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.
disabledBooleanoptionalSpecifies 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.
environmentStringoptionalSpecifies 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.
destinationsObject
DestinationsOptions
optionalSpecifies any analytics provider-specific configuration. The Itly SDK passes these objects in when loading the underlying analytics provider libraries.
validationObject
ValidationOptions
optionalConfigures 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.
pluginsArrayoptionalAn 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.

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.

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.

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.

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
optionsObject
Options
requiredThe 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;
ArgumentTypeDescription
userIdStringrequiredThe 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).
previousIdStringrequiredThe 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;
ArgumentTypeDescription
userIdStringrequiredThe 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.
propertiesObject
Properties
requiredThe 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;
ArgumentTypeDescription
userIdStringrequiredAlways undefined in the Browser SDK.
eventObject
Event
requiredThe 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;
ArgumentTypeDescription
userIdStringrequiredAlways undefined in the Browser SDK.
groupIdStringrequiredThe ID of the group (for example, the user's department or company) to associate the user with.
propertiesObject
Properties
optionalThe 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;
ArgumentTypeDescription
userIdStringrequiredAlways undefined in the Browser SDK.
categoryStringoptionalThe page's category. Useful when many pages might live under a single category.
nameStringoptionalThe page's name.
propertiesObject
Properties
optionalThe 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;