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-outWhen 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:
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
Identifying the visitor
{ "user_id": "…" }: your signed-in user, using the same ID you pass tonl.identify(). Use this whenever you have it.{ "visitor_id": "…" }: a visitor ID. If you pass the script's own ID, read fromlocalStorage.nl_vin 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.