Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 63 additions & 0 deletions events.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
---
layout: null
permalink: /events.md
sitemap: false
---
# Collect events with Simple Analytics

How to collect events, like signups and button clicks, with Simple Analytics and check that they work. Written for AI agents, like Claude Code, Codex and Cursor, and for developers.

Came here from the Simple Analytics dashboard or its MCP tools? They gave you the hostname and the script host of the website, use those.

## 1. Before you start

- Events in the browser need the Simple Analytics script on every page, `latest.js` and not [`light.js`]({{ site.url }}/light), which doesn't send events. Not there yet? Follow [the install guide]({{ site.url }}/install.md) first. Events from a server or app don't need the script, see option 4 below.
- Load event scripts the same way as the main script: from the same custom domain or proxy. Does the script have an uncommon [`data-namespace`]({{ site.url }}/events#the-variable-sa_event-is-already-used), like `data-namespace="ba"`? Then the function is `ba_event` instead of `sa_event`.
- Look for events the website already sends, like `sa_event` calls and `data-simple-event` attributes, so you don't send them twice.

## 2. Send events

Use the first option that covers the event:

1. **Outbound links, downloads, email and phone links:** add the [automated events script]({{ site.url }}/automated-events) next to the main script. No code needed. It stores the address or number that's already on the website's link, not what visitors type:
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

```html
<script async src="https://scripts.simpleanalyticscdn.com/auto-events.js"></script>
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
```

With a custom domain or the proxy, load it from that domain. In the rare case that `data-namespace="ba"` is used, add `data-sa-global="ba_event"` to it.

Downloads are links to pdf, csv, docx, xlsx, zip, doc and xls files, set `data-extensions` for other files. Outbound and download links can send their full URL as `url` metadata, email and phone links their address or number. Does a link have personal data or a token in it, like a download link per customer or the visitor's own email address? Give that link a `data-simple-event` name instead, the automated script then skips it.

2. **Clicks and form submissions:** add `data-simple-event="signup_form"` to the element, from script version 12. Add metadata with `data-simple-event-` attributes, like `data-simple-event-logged-in="true"` for `logged_in` metadata. See [inline events]({{ site.url }}/events/inline).
3. **Everything else,** like a signup that succeeded: call `sa_event` in JavaScript.

```js
sa_event("signup_completed", { plan: "starter" });
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
```

Add the [placeholder function]({{ site.url }}/events#placeholder-event-function) to `<head>`, before other scripts. It queues events that happen before the script loads, and keeps `sa_event` defined when an ad blocker blocks the script, so the call doesn't throw. With `data-namespace="ba"`, replace every `sa_event` in it with `ba_event`, like [the namespace example]({{ site.url }}/events#the-variable-sa_event-is-already-used).

4. **From a server or app:** send them to our endpoint, see [server-side events]({{ site.url }}/events/server-side). Send the visitor's user agent when the event comes from their request, so robots stay robots. Otherwise use one like `ServerSide/1.0 (+https://www.example.com/)`: user agents with `bot`, `spider`, `crawl` or `agent` in them are stored as robots.

## 3. Name events and add metadata

- **Names:** letters, numbers and underscores, like `signup_completed`. Names are case-sensitive. The script replaces other characters with `_`, server-side names are stored as you send them. See [valid event names]({{ site.url }}/events#valid-event-names).
- **When:** send an event when something happened, like a signup that succeeded, not when someone clicks a button that might fail.
- **Metadata:** add details to an event as [metadata]({{ site.url }}/metadata), like `{ plan: "starter" }`. Values are text, numbers, booleans or dates.
- **No personal data:** never put a visitor's email address, name, ID, what they type or other personal data in an event, metadata, button label or link title. It's not allowed, and the account might be suspended.

## 4. Check that it works

1. **In the browser:** trigger the event and find its `simple.gif` request. Its `simple-analytics-feedback` response header says `Thanks for sending this event!` when it works. Avoid replaying the request with curl or other tools, because it adds fake events. Only do that when nothing else works, and tell the user.
2. **From a server or app:** our endpoint answers `201` with `"ok": true` when it stores the event. Otherwise `message` says what's wrong.
3. With access to Simple Analytics, through its MCP tools or a token the user approved, `get_recent_hits` with `type: "events"` shows the latest events, including robots. Headless browsers, like the ones AI agents use, can count as robots, so a test event by an agent might only show up there.
4. `get_events` counts the events that aren't robots per name, and `get_metadata` shows their metadata. On an existing website, new events show up within minutes. On a new website, it can take longer because of caching or DNS changes.

## 5. Use events

- **[Goals]({{ site.url }}/goals)** count events or funnels of events and pages: `create_goal` with the MCP tools, then `get_goal_results`.
- **The [Events Explorer]({{ site.url }}/events-explorer)** shows events with their metadata, and the [export]({{ site.url }}/export-data) has the raw events: `export_data` with the MCP tools.
- **Event counts are how often an event happened,** not how many people did it.

Need help? See [our support channels](https://simpleanalytics.com/contact).
7 changes: 4 additions & 3 deletions install.txt
Original file line number Diff line number Diff line change
Expand Up @@ -57,18 +57,19 @@ With a custom domain, allow that domain instead of both. The Free plan badge als
- `IP in excluded IP list for website`: the website settings exclude this IP address.
- Anything else explains what is wrong.
2. No `simple.gif` request? Check the console for `Simple Analytics:` warnings and Content Security Policy errors.
3. Never replay the `simple.gif` request with curl or other tools, it adds fake page views.
3. Avoid replaying the `simple.gif` request with curl or other tools, because it adds fake page views. Only do that when nothing else works, and tell the user.

JavaScript on the page can't read this header. Server-side page views, like `trackPageview` in Next.js middleware, don't show up in the browser at all.

With access to Simple Analytics, through its MCP tools or a token the user approved, `check_installation` checks the live website and `get_recent_hits` shows the latest page views and events.

Headless browsers, like the ones AI agents use, count as robots. Simple Analytics stores robots but doesn't show them in the dashboard, so a test visit by an agent only shows up in the recent hits, marked as a robot.
Headless browsers, like the ones AI agents use, can count as robots. Simple Analytics stores robots but doesn't show them in the dashboard, so a test visit by an agent might only show up in the recent hits, marked as a robot.

If the recent hits show nothing, that doesn't mean the installation failed. A page view that got `Thanks for sending this page view!` is almost always stored, also when the website isn't added yet. Hits of new websites can take over an hour to show up.
If the recent hits show nothing, that doesn't mean the installation failed. A page view that got `Thanks for sending this page view!` is almost always stored, also when the website isn't added yet. Hits of new websites can take longer to show up because of caching or DNS changes.

## 4. Collect the right data

- **Events,** like signups and button clicks: follow [the events guide]({{ site.url }}/events.md).
- **URL parameters:** we only keep UTM codes and `ref`. To collect another parameter, like `product-id`, add it to [`data-allow-params`]({{ site.url }}/allow-params) first. It's only collected from then on.
- **No personal data:** never put email addresses, names, user IDs or other personal data in paths, URL parameters, [events]({{ site.url }}/events) or [metadata]({{ site.url }}/metadata). It's not allowed, and the account might be suspended.
- **Missing data,** for example because of ad blockers? Set up a [custom domain]({{ site.url }}/bypass-ad-blockers), or even better the [proxy]({{ site.url }}/proxy).
Expand Down
Loading