Node.js SDK

Instant insights from any Node.js app

This documentation provides guidance on how to integrate the June SDK with your Node.js application. June SDK is a powerful library for tracking user interactions and events, offering similar functionality to the underlying Segment SDK.

Getting Started

Installation

To install the June SDK in your Node.js project, use the npm package manager:

npm install @june-so/analytics-node --save

Alternatively, use yarn:

yarn add @june-so/analytics-node

Configuration

First, you'll need to import the SDK into your application:

import { Analytics } from '@june-so/analytics-node';

Next, instantiate the client using the write key you've received when you created your June account:

const analytics = new Analytics('YOUR_WRITE_KEY');

Now you can use the analytics instance to track events, identify users, and more.

API Reference

const analytics = new Analytics('YOUR_WRITE_KEY', options);

Analytics options

Parameter	Type	Description	Required
writeKey	String	Your June project's write key.	Yes
options	Object	Configuration options.	No

Configuration options

Parameter	Type	Description	Required
maxRetries	Number	The number of times to retry flushing a batch. Default: 3	No
maxEventsInBatch	Number	The number of messages to enqueue before flushing. Default: 15	No
flushInterval	Number	The number of milliseconds to wait before flushing the queue automatically. Default: 10000	No
httpRequestTimeout	Number	The maximum number of milliseconds to wait for an http request. Default: 10000	No
disable	Boolean	Disable the analytics library. All calls will be a noop. Default: false.	No
httpClient	HTTPFetchFn , HTTPClient	Supply a default http client implementation.	No

Example:

const analytics = new Analytics('YOUR_WRITE_KEY', {
  maxEventsInBatch: 50,
  flushInterval: 30000, // flush every 30 seconds
});

Tracking Events

To track events, you can use the track method:

analytics.track({
  userId: 'USER_ID',
  event: 'Signed In',
  properties: {
    browser: 'chrome',
  },
});

Parameters:

Parameter	Type	Description	Required
userId	String	The ID for this user in your database. Note: At least one of "userId" or "anonymousId" must be included in any track call.	No
anonymousId	String	An ID associated with the user when you don’t know who they are.	No
event	String	The name of the event you’re tracking. It is recommended to use human-readable names like "Song Played".	Yes
properties	Object	A dictionary of properties for the event. For instance, if the event was "Product Added", it might have properties like price.	No
timestamp	Date	A JavaScript date object representing when the track took place.	No
context	Object	A dictionary of extra context to attach to the call.	No

Identifying Users & Setting User Traits

To identify users, you can use the identify method:

analytics.identify({
  userId: 'USER_ID',
  traits: {
    email: 'test@example.com',
    name: 'Joe Bloggs',
    avatar: 'https://avatar.com/asd809sdhoif9as10nc29.png',
  },
});

Parameters:

Parameter	Type	Description	Required
userId	String	The ID for this user in your database. Note: At least one of "userId" or "anonymousId" must be included in any identify call.	Yes
anonymousId	String	An ID associated with the user when you don’t know who they are.	No
traits	Object	A dictionary of traits you know about the user. Things like: email, name, or friends.	No
timestamp	Date	A JavaScript date object representing when the identify took place.	No
context	Object	A dictionary of extra context to attach to the call.	No

Grouping Users

To group users by organization or company, use the group method:

analytics.group({
  userId: 'USER_ID',
  groupId: 'GROUP_ID',
  traits: {
    name: 'Acme Inc',
    avatar: 'https://avatar.com/asd809sdhoif9as10nc29.png',
  },
});

Parameters:

Parameter	Type	Description	Required
userId	String	The ID for this user in your database. Note: At least one of "userId" or "anonymousId" must be included in any group call.	Yes
anonymousId	String	An ID associated with the user when you don’t know who they are.	No
groupId	String	The ID of the group.	Yes
traits	Object	A dictionary of traits you know about the group. For a company, they might be things like name, address, or phone.	No
timestamp	Date	A JavaScript date object representing when the group took place.	No
context	Object	A dictionary containing any context about the request.	No

Serverless environments

In serverless environments like AWS Lambda, your environment may finish the code execution before June SDK is able to send events to June API.

You can use the flush method to send all queued events to June or you can configure the SDK to flush events automatically.

Flush events manually

await analytics.closeAndFlush();

Flush events automatically

If you set flushAt to 1, the SDK will flush events automatically after every event.

const analytics = new Analytics('YOUR_WRITE_KEY', {
  maxEventsInBatch: 1,
});