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

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

Alternatively, use yarn:

```sh
yarn add @june-so/analytics-node
```

## Configuration

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

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

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

```js
const analytics = new Analytics('YOUR_WRITE_KEY');
```

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

## API Reference

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

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

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

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

```javascript
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

```javascript
await analytics.closeAndFlush();
```

## Flush events automatically

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

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