Node.js SDK

Docs

Getting started

Start here

What should I track?

Quickstart

Install

Identify users & companies

Track behaviour

SDKs

Web

Browser React & Next.js

Server

Node.JS Python Ruby

HTTP API

Authentication Identify Group Track Page

Help center

Go to June home

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:

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

Alternatively, use yarn:

1
yarn add @june-so/analytics-node

Configuration

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

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

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

1
const analytics = new Analytics('YOUR_WRITE_KEY');

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

API Reference

1
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 (such as one supporting proxy). Accepts either an HTTPClient instance or a fetch function. Default: an HTTP client that uses globalThis.fetch, with node-fetch as a fallback.	No

Example:

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

Tracking Events

To track events, you can use the track method:

1
analytics.track({
2
  userId: 'USER_ID',
3
  event: 'Signed In',
4
  properties: {
5
    browser: 'chrome',
6
  },
7
});

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 (for example, the "anonymousId" generated by analytics.js).	No
event	String	The name of the event you’re tracking. It is recommended to use human-readable names like "Song Played" or "Status Updated".	Yes
properties	Object	A dictionary of properties for the event. For instance, if the event was "Product Added", it might have properties like price or product.	No
timestamp	Date	A JavaScript date object representing when the track took place. If the track just happened, leave it out and the server’s time will be used. If you’re importing data from the past, make sure to send a timestamp.	No
context	Object	A dictionary of extra context to attach to the call. Note: "context" differs from "traits" because it is not attributes of the user itself.	No

Identifying Users & Setting User Traits

To identify users, you can use the identify method:

1
analytics.identify({
2
  userId: 'USER_ID',
3
  traits: {
4
    email: 'test@example.com',
5
    // Optional
6
    name: 'Joe Bloggs',
7
    avatar: 'https://avatar.com/asd809sdhoif9as10nc29.png',
8
    // Add anything else about the user here
9
  },
10
});

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.	No
anonymousId	String	An ID associated with the user when you don’t know who they are (for example, the "anonymousId" generated by analytics.js).	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. If the identify just happened, leave it out as Segment uses the server’s time. If you’re importing data from the past, make sure to send a timestamp.	No
context	Object	A dictionary of extra context to attach to the call. Note: "context" differs from "traits" because it is not attributes of the user itself.	No

Grouping Users

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

1
analytics.group({
2
  userId: 'USER_ID',
3
  groupId: 'GROUP_ID',
4
  traits: {
5
    name: 'Acme Inc',
6
    // Optional
7
    avatar: 'https://avatar.com/asd809sdhoif9as10nc29.png',
8
    // Add anything else about the company here
9
  },
10
});

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.	No
anonymousId	String	An ID associated with the user when you don’t know who they are (for example, the "anonymousId" generated by analytics.js). Note: At least one of "userId" or "anonymousId" must be included in any group call.	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. If the group just happened, leave it out as Segment uses the server’s time. If you’re importing data from the past, make sure to send a timestamp.	No
context	Object	A dictionary containing any context about the request.	No

Serverless environments

In serverless environemnts 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

1
await analytics.closeAndFlush();

Flush events automatically

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

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