# simple-track

> A simple client side library for creating and firing off analytics events.

Latest version **1.2.0** (published 2023-01-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install simple-track
pnpm add simple-track
yarn add simple-track
bun add simple-track
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.0 |
| Published | 2023-01-03 |
| First published | 2020-12-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 16 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Richie Casto |
| Maintainers | rcasto |

## Links

- npm: https://www.npmjs.com/package/simple-track
- Repository: https://github.com/rcasto/simple-track
- Homepage: https://github.com/rcasto/simple-track#readme
- Issues: https://github.com/rcasto/simple-track/issues
- npm.io page: https://npm.io/package/simple-track

## Recent versions

- 1.2.0 (latest) — 2023-01-03
- 1.1.1 — 2021-12-29
- 1.1.0 — 2021-09-18
- 1.0.0 — 2021-09-13
- 0.0.3 — 2020-12-30
- 0.0.2 — 2020-12-29
- 0.0.1 — 2020-12-29

## README

# simple-track
A simple client side library for creating and firing off analytics events.

## Setup

### npm
```
npm install --save simple-track
```

### script tag
```html
<script type="module" src="https://cdn.jsdelivr.net/npm/simple-track"></script>
```

**Note:** The browser global is `SimpleTrack`

## Usage
1. Create an event generator using `createEventGenerator`
```javascript
const appName = '<your-app-name>';
const analyticsApiUrl = '<your-analytics-endpoint-url>';

const eventGenerator = window.SimpleTrack.createEventGenerator({
    appName,
    analyticsApiUrl,
});
```

2. Fire off an event using `track`!
```javascript
const eventType = '<your-event-type-or-name>';
const eventData = { foo: 'bar' };

eventGenerator.track(eventType, eventData);
```

**Note:** Providing event data is optional, if not provided it defaults to `null`

## Parameters/Customization
When creating an event generator, you have the ability to additionally pass in more than an `appName`, which is already optional, and the `analyticsApiUrl`, which is required.

```typescript
export interface IEventGeneratorInfo {
    analyticsApiUrl: string;
    appName?: string;
    storageKey?: string;
    storage?: Pick<Storage, 'getItem' | 'setItem'>;
    generateIdentifier?: () => string;
    doNotTrack?: boolean;
}
```

- `storageKey` represents the key at which to store the analytics id generated by `generateIdentifier` in the `storage` implementation.

    The default storage key, if none specified, is `analytics-session-id`.

- `storage` is an implementation of the [Storage interface](https://developer.mozilla.org/en-US/docs/Web/API/Storage), only requiring `getItem` and `setItem` be implemented.

    The default storage, if none specified, is [sessionStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage).  
    You are also free to not provide a storage implementation at all (`null`).

- `generateIdentifier` is a function that broadly outputs an idenfitier to associate with the client/browser instance/user. You could always no-op (`() => ''`) this if you didn't want to associate an identifier.

    The default `generateIdentifier` function, simply generates a [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) utilizing an [internal implementation](https://github.com/rcasto/simple-track/blob/ea302a24446f1b505cbda62c520749723ef6e7dd/src/index.ts#L14).

- `doNotTrack` is a boolean indicating whether calls to `track` should call out to the `analyticsApiUrl` or not. If true it will, otherwise it won't.

## Additional Info
Internally this library utilizes the [Beacon API](https://developer.mozilla.org/en-US/docs/Web/API/Beacon_API) to fire off the event to the analytics endpoint provided from the client.

If the Beacon API is not supported by the client, however, it will fallback to using the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).

At the end of the day your analytics endpoint service will receive a `POST` request with event as a JSON object of the following shape:
```typescript
export interface IEventInfo<T> {
    appName: string;
    analyticsId: string;
    type: string;
    data: T;
}

export interface IEvent<T> extends IEventInfo<T> {
    timeString: string;
    eventId: string;
    version: number;
}
```

```json
{
	"appName": "your-app-name",
	"analyticsId": "66eacd05-6624-4589-9c9e-9ef4f194d07a",
	"type": "your-event-type-or-name",
	"data": {
		"foo": "bar"
    },
    "timeString": "2020-12-30T23:18:34.191Z",
	"eventId": "1ff1d482-079b-4f2b-85ff-5f93d832f951",
	"version": 1
}
```

As an added bonus, the library itself also exports a function called `generateUUID` that allows you to generate a [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier).

---
_Source: https://npm.io/package/simple-track · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._