# Custom events

nanolytics tracks pageviews for you. Anything else you want to count, such as a signup, a purchase or a button click, is a custom event. You can send custom events from the browser with `nl.track()`, or from your server with the Events API.

## Sending events from the browser

Once the script has loaded, you can call it through `window.nl`:

```js
nl.track('signup')
nl.track('checkout', { plan: 'pro', seats: 3 })
```

- **Name:** up to 256 bytes.
- **Props:** an object with up to 30 keys. Each key can be up to 64 bytes, and each value must be either a string of up to 256 bytes or a finite number.

If an event goes over a limit, or has a prop that isn't a string or a number, the whole event is dropped rather than truncated. Your site's health report lists it as `over_limit` or `bad_prop`.

You can query events by name (`event_name`) and by any of their props (`prop.plan`), and use them in goals. See [API](/docs/api).

### Calling nl before the script loads

The script loads with `defer`, so `nl` isn't available yet while your page's first scripts run. If you need to call it earlier, add this line before the script tag. It queues your calls, and the script runs them in order before it sends its first pageview.

```html
<script>window.nl=window.nl||{q:[]};"track identify consent use error".split(" ").forEach(function(m){nl[m]=nl[m]||function(){nl.q.push([m,[].slice.call(arguments)])}})</script>
<script defer src="https://app.nanolytics.dev/s/pk_….js"></script>
```

## Identifying signed-in users

```js
nl.identify('user_8f2c')   // on sign-in
nl.identify(null)          // on sign-out
```

When you identify a user, nanolytics links their events from before and after they signed in, across all their devices, so funnels and paths follow the same person. The ID stays in the browser's local storage until you call `identify(null)`. Use an ID from your own system rather than an email address. IDs can be up to 256 bytes.

## Consent

By default, the script stores a random visitor ID in the browser's local storage so it can recognize returning visitors. If your site asks for consent, or a visitor declines, call:

```js
nl.consent(false)
```

This deletes the visitor ID and the user ID from the browser, and the choice is remembered on later pages. From then on, the visitor is counted with a hash that changes every day, and their sessions aren't recorded. Call `nl.consent(true)` to go back to the default. If you use the snippet above, calling `consent(false)` before the script loads applies to the very first pageview. See [Privacy](/docs/privacy).

## Reporting handled errors

If you've turned on the Errors option, you can report errors that your code catches:

```js
try {
  await checkout()
} catch (err) {
  nl.error(err, { step: 'payment' })
}
```

See [Errors](/docs/errors).

## Sending events from your server

`POST https://api.nanolytics.dev/v1/events` accepts up to 1,000 events, and up to 1 MiB, per request. Authenticate with a secret key (`sk_…`), which you can create in your site's **Settings → API keys**.

```sh
curl -s -X POST https://api.nanolytics.dev/v1/events \
  -H "Authorization: Bearer $NANOLYTICS_KEY" \
  -H 'content-type: application/json' \
  -d '[{
    "event_id": "0f8a2c1e9b7d4e6fa3c5b1d2e4f60718",
    "kind": "custom",
    "name": "subscription_renewed",
    "url": "https://example.com/billing",
    "props": { "plan": "pro" },
    "visitor": { "user_id": "user_8f2c" }
  }]'
```

Once the accepted events are stored, the API responds with `200` and one result for each event, in the order you sent them:

```json
{ "results": [{ "status": "accepted" }] }
```

A rejected event comes back with `"status": "rejected"`, a `code` and a `message`. The other events in the same request are still stored.

### Fields

| Field | Description |
|---|---|
| `event_id` | Required. 32 hex digits or a UUID. If you send the same ID twice, the event is stored only once, so retries are safe. |
| `kind` | Required. `custom`, `pageview`, `identify`, `error`, `revenue`, `engagement` or `vitals`. |
| `name` | The event's name, for `custom` events. Up to 256 bytes. |
| `url` | The page where the event happened. |
| `referrer` | The page the visitor came from. |
| `props` | The same as in the browser: up to 30 keys, with string or number values. |
| `error` | For `error` events: `type` or `message` is required; `stack`, `mechanism`, `handled`, `count` and `release` are optional. |
| `ts` | When the event happened, in RFC 3339 format. It must be within the last 7 days and no more than 5 minutes in the future. If you leave it out, the time the event arrives is used. |
| `visitor` | Required. Who the visitor was, in one of the three forms below. |

### Identifying the visitor

- `{ "user_id": "…" }`: your signed-in user, using the same ID you pass to `nl.identify()`. Use this whenever you have it.
- `{ "visitor_id": "…" }`: a visitor ID. If you pass the script's own ID, read from `localStorage.nl_v` in that visitor's browser, the event is linked to their visits. Any other string is treated as your own ID.
- `{ "ip": "…", "user_agent": "…" }`: the visitor's IP address and user agent. The visitor is counted with the same daily hash used for visitors who haven't given consent. Make sure you pass the visitor's IP and user agent, not your server's.

Events sent from your server don't have a country, region or city, because the request's location would be your server's, not the visitor's.

### Responses

| Status | Meaning |
|---|---|
| `200` | The result for each event, as shown above. |
| `401` | The secret key is missing or not recognized. |
| `413` | The request has more than 1,000 events or is larger than 1 MiB. |
| `400` | The body isn't valid JSON. |
| `503` | Nothing was stored. Send the request again. |

## Limits

| Limit | Value |
|---|---|
| Event name | 256 bytes |
| Props per event | 30 |
| Prop key | 64 bytes |
| Prop string value | 256 bytes |
| User ID | 256 bytes |
| Events API request | 1,000 events, 1 MiB |
| Events API `ts` | 7 days back, 5 minutes ahead |
