Repository navigation
Add an events guide for AI agents #79
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
7 commits
Select commit
Hold shift + click to select a range
a4eebbf
Give AI agents a guide to collect events
6b154e2
Tell agents what differs for server events and namespaces
605fb78
Cover links added later, link URLs, the placeholder and user agents
c3e7935
Use the namespaced function in the placeholder too
0182181
Say links with a title don't send their URL
29d6ffd
Apply review suggestions to the events and install guides
38559a0
Say light.js sends no events, which downloads count and which links c…
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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: | ||
|
|
||
| ```html | ||
| <script async src="https://scripts.simpleanalyticscdn.com/auto-events.js"></script> | ||
|
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" }); | ||
|
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). | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.