Send events

Sending events is useful for tracking unique interactions, such as clicks on buttons, as well as monitoring conversions and goals, like adding items to the cart or subscribing to a newsletter. Custom events also help with testing and optimization, such as in A/B tests to analyze the impact of different interface variations. This expands analytics, allowing for flexible data collection and in-depth analysis of user behavior.

There are two ways to send attributes. The simpler and more convenient method is to attach HTML attributes to the elements you want to track clicks on. When the element is clicked, the analytics script will send the event. Alternatively, you can use JavaScript, which is more flexible as it allows sending events not only on clicks.

HTML attributes:

• data-s:event - sets the event name.
• data-s:event-path - sets the path that will represent the page where the event occurred.
• data-s:event-props - sets the properties that will be sent with the event.

<button data-s:event="Button click">
  Click
</button>

window.stonks.event("Button click");

Properties

Sending custom props with an event allows you to pass additional data for analyzing user behavior. This helps with:

• User segmentation: Track user-specific information (e.g., subscription type, region) to analyze different user groups.
• Contextual data: Pass data related to a specific page or user action (e.g., product category, page ID).

The properties that will be sent with page views or events can be compared in the widgets.

Syntax & Rules

• To separate props, use the ; symbol.
• To create key-value pairs, use the = symbol.
• Excess whitespace around the symbols will be trimmed: " theme = dark ;lang = en ; logged_in = true " → "theme=dark;lang=en;logged_in=true".
• Do not use the ; and = symbols in prop keys and values.
• Incorrect key-value pairs will be removed from the prop list.
• The values of the parameters will always be of type string.

<button
  data-s:event="Event"
  data-s:event-props="theme=dark;lang=en;logged_in=true"
>
  Click
</button>

window.stonks.event("Event", {
  theme: "dark",
  logged_in: "true",
  lang: "en"
});

// With path and props
window.stonks.event("Event", "/new-path", {
  theme: "dark",
  logged_in: "true",
  lang: "en"
});

Custom path

By default, the analytics script sends the current page URL, trimming query parameters and the trailing slash. For example, https://example.com/home/ and https://example.com/home?param=value will be sent as https://example.com/home.

It is possible to modify the path that the analytics script sends.

If you need to merge routes, for example, send /dashboard/29ab9322-0ba1-449a-ab9f-539dc3a62683/setting as /dashboard/[userId]/settings, you can do it by overriding the path:

<button 
  data-s:event="Event" 
  data-s:event-path="/dashboard/[userId]/settings"
>
  Button
</button>

// With event name and path
window.stonks.event("Button click", "/dashboard/[userId]/settings");

// With event name, path and props
window.stonks.event("Button click", "/dashboard/[userId]/settings", {
  theme: "dark",
  logged_in: "true",
  lang: "en",
});

The script will send https://example.com/dashboard/[userId]/settings