Send events

Pageviews, videos, downloads, and outbound clicks are recorded for you. Send an event for anything specific to your site:

webstats('event', 'signup', { plan: 'pro', price: 29, trial: false });

The name is yours to choose. Keep it short, lowercase, and stable, because it becomes a filter value in your dashboard. You can then break down by any key in the detail object.

Names run 1 to 64 characters. Outside that range the event is discarded rather than trimmed, which is the only way a webstats('event', ...) call can be lost entirely.

Calling webstats() before the pixel exists

An inline <script> runs before the deferred pixel, so webstats is not defined yet. Make it type="module" and it runs after. From app or framework code, guard it with if (window.webstats) unless that code is ordered after the snippet. See webstats() commands.

What a detail object can hold

Rule	Limit
Value types	Text, numbers, and true/false. No arrays, no nested objects.
Keys per event	32
Key length	64 characters, trimmed beyond that
Value length	1024 characters, trimmed beyond that

Over-length keys and values are truncated. A value the system cannot use, such as an array or a nested object, drops that one key. Keys past the 32nd are dropped. The event still records in every one of those cases, so one bad field never costs you the whole event.

Naming that stays readable

• One name per thing that happened, with the variation in the detail object. Send webstats('event', 'signup', { plan: 'pro' }), not signup_pro and signup_free.
• Verb or noun, but pick one and keep it across your site.
• No personal data. No email addresses, names, or payment details. Use your own account id if you need to join the data up later.

Examples

// A form was submitted
form.addEventListener('submit', () => {
  webstats('event', 'contact-form', { topic: form.topic.value });
});

// A plan was chosen
webstats('event', 'purchase', { plan: 'annual', price: 290, currency: 'EUR' });

// A search was run, with the result count but not the query
webstats('event', 'search', { results: hits.length });

Downloads and outbound links

Two events need no code at all:

Event	Fires when	Recorded with
download	A click on a file link (pdf, zip, mp4, mkv, and so on), or any link with a download attribute	The URL and the filename
outbound	A click on a link to a different site	The URL and the destination host

The automatic event knows the filename, not what the file is. To get title, quality, or format into your reports, read them off the element:

<a href="/files/278-1080p.mkv"
   data-download
   data-title="The Shawshank Redemption"
   data-quality="1080p">Download 1080p</a>

document.querySelectorAll('[data-download]').forEach((link) => {
  link.addEventListener('click', () => {
    webstats('event', 'download-detail', {
      title: link.dataset.title,
      quality: link.dataset.quality,
    });
  });
});

Give it a name of its own, as above. The automatic download event still fires on the same click, so reusing the name download gives you two events with that name and different fields, and every download count doubles.

To group downloads by film or show rather than by filename, name the page as well. See Name movies and shows.

Verify

Trigger the action on your own site, then open Audience and click your own visit. The event appears in that visitor’s Custom events list within seconds, with its detail keys attached.