Tracking events

An event is one thing that happened, with a name and, if you like, a few properties: a newsletter signup, a recipe saved, an export that failed. Page views and, if you turn them on, link clicks are sent for you. Everything else is one line of code.

What is sent without code

• Page views. The script tag sends a page_view when the page loads and each time the path changes. From the package, init({ pageViews: "history" }) does the same; see single-page applications.
• Link clicks and downloads, once you turn them on: outbound_click, file_download, email_click and phone_click. See link events.
• Where a visit came from and which page it is on, as properties of every event. See what is captured automatically.

In an extension, installs, active users and, with uninstallTracking: true, uninstalls are counted for you. Everything a person does in it is yours to name.

On a website, from the package

init returns the client. Call track with the event's name, and an object of properties if the event has any:

import { init } from "@analyticstrend/web";

const analytics = init({ writeKey: "wk_your_key_here", pageViews: "history" });

document.querySelector("#newsletter").addEventListener("submit", () => {
  analytics.track("newsletter_signup", { placement: "footer" });
});

track never throws, so it can sit in any handler without a try, and there is no need to await it: a bad name is reported to onError and dropped. Events are queued and sent in batches, and whatever is left is sent as the visitor leaves the page.

On a website, from the script tag

The script tag puts the same client on the page as window.analyticstrend:

<button id="save-recipe">Save this recipe</button>

<script>
  document.getElementById("save-recipe").addEventListener("click", () => {
    window.analyticstrend?.track("recipe_saved", { category: "dessert" });
  });
</script>

The ?. keeps the button working when the tag did not load, for example under a content blocker.

In a browser extension

The background owns the queue, so track there with the client initBackground returns:

// background.js
import { initBackground } from "@analyticstrend/extension";

const analytics = initBackground({ writeKey: "wk_your_key_here", uninstallTracking: true });

chrome.contextMenus.onClicked.addListener((info) => {
  analytics.track("selection_saved", { menu: info.menuItemId });
});

A popup or content script sends its events to the background with trackFromContentScript:

// popup.js
import { trackFromContentScript } from "@analyticstrend/extension";

document.getElementById("export").addEventListener("click", () => {
  trackFromContentScript("export_started", { format: "csv" });
});

If the background is not running at that moment, a content-script event is dropped rather than queued; see the Chrome guide.

Names and properties

• Names are lowercase letters, digits and underscores, up to 64 characters, such as newsletter_signup. Name what happened, in the past tense where it reads naturally.
• Properties are up to 2048 bytes of JSON per event. Keep them to a few values you will group by, such as a plan or a format, rather than free text.
• Never personal data: no email addresses, names or ids from your own system.
• One name per action, with the varying part as a property. A project can have 200 distinct event names, and a name built from an id uses them up in an hour.

The naming guide has the rules in full, with examples of each.

Check that it arrived

Open the project's Events report. Every event name the project has received is listed with its count, and the latest events are shown below as they arrive. If an event is not there, it did not arrive: check the browser's network panel for the request to analyticstrend.com, and the onError option for a rejected name.

Then make it a goal

An event that matters, such as newsletter_signup, can become a goal, with its conversion rate by source, page, country and device, and goals in order make a funnel.