Skip to content

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:

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.

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.

<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

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.

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:

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.

Reporting handled errors

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

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

See 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.

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:

{ "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

FieldDescription
event_idRequired. 32 hex digits or a UUID. If you send the same ID twice, the event is stored only once, so retries are safe.
kindRequired. custom, pageview, identify, error, revenue, engagement or vitals.
nameThe event's name, for custom events. Up to 256 bytes.
urlThe page where the event happened.
referrerThe page the visitor came from.
propsThe same as in the browser: up to 30 keys, with string or number values.
errorFor error events: type or message is required; stack, mechanism, handled, count and release are optional.
tsWhen 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.
visitorRequired. 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

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

Limits

LimitValue
Event name256 bytes
Props per event30
Prop key64 bytes
Prop string value256 bytes
User ID256 bytes
Events API request1,000 events, 1 MiB
Events API ts7 days back, 5 minutes ahead