# Event Tracking
BETA

This feature is currently in beta testing and may be subject to changes.

Event tracking allows you to capture specific user interactions on your website, such as button clicks, file downloads, or form submissions. This goes beyond simple page views to help you understand how visitors are engaging with your content. ## Enabling Event Tracking To start tracking events, you need to add the `?events` parameter to your existing Tinylytics embed script. Update your script tag to look like this: ```html ``` If you are already using other parameters (like `?kudos` or `?hits`), you can combine them: ```html ``` **Note:** When hit tracking is disabled (for example via your site’s settings or the `?ignore` parameter on the script URL), event tracking will not trigger either. Events are only sent when hit collection is enabled. ## How to Track Events Once the script is updated, you can track events by adding specific `data-` attributes to any HTML element on your page (links, buttons, divs, etc.). The script listens for clicks on these elements and automatically sends the event data to Tinylytics. ### Basic Usage Use the `data-tinylytics-event` attribute to define the event name. ```html ``` ### Event Naming Convention Event names **must** follow the `category.action` format. * **Good:** `button.click`, `file.download`, `form.submit`, `video.play` * **Bad:** `click`, `download`, `submit` (missing category) The script will automatically convert arrows `->` to dots `.`, so `button->click` becomes `button.click`. ### Adding Event Values You can optionally provide a value for the event using `data-tinylytics-event-value`. This is useful for distinguishing between similar events, like downloading different files. ```html Download Pricing Guide ``` ## Examples ### Tracking File Downloads ```html Get Whitepaper ``` ### Tracking External Links ```html Follow us on Twitter ``` ### Tracking Form Submissions You can add the attribute to the submit button of a form: ```html
``` ## Advanced Configuration ### Using Beacons vs. Fetch By default, Tinylytics uses the standard `fetch` API to send event data. This is reliable for most interactions. However, for links that navigate away from the current page (like external links), the browser might cancel the request before it completes. To ensure events are sent even when the user leaves the page, you can enable **Beacon** mode by adding `?beacon` to your script URL. ```html ``` This uses `navigator.sendBeacon`, which queues the data to be sent asynchronously by the browser, ensuring it reaches our servers even if the page unloads immediately. **Note:** Beacons may be blocked by some privacy-focused browsers (like Brave) or ad-blocking extensions, as they are sometimes associated with third-party tracking. If 100% data completeness is critical and your audience uses these tools heavily, consider testing which method works best for your specific use case. ### Debouncing To prevent accidental double-clicks from skewing your data, the script automatically "debounces" events. If a user clicks the same element multiple times rapidly, only one event will be recorded every 500 milliseconds.