Custom events

Track actions that matter to you, such as signups, purchases or button clicks, from the browser.

Track an event

Once the script is on the page, call window.mosaicdeck.track(name, props?):

if (window.mosaicdeck) window.mosaicdeck.track("signup");
if (window.mosaicdeck) window.mosaicdeck.track("recipe_saved", { recipe: "banana-bread", servings: 8, vegan: false });

The script loads with defer. With the snippet's first line (the stub) in place, calls made before it has loaded are queued and sent once it loads, up to 50. Still guard every call, so a page without the snippet or with the script blocked can never throw. Use if as above in plain scripts; ?. is fine in modules and transpiled code, but in an untranspiled classic script it breaks the whole file in older browsers. For example, from a click handler in a module:

<button id="buy">Buy now</button>
<script type="module">
  document.getElementById("buy").addEventListener("click", () => {
    window.mosaicdeck?.track("buy_clicked", { plan: "pro" });
  });
</script>

Limits

Each custom event counts as one event toward your plan's monthly total, like a page view.

Built-in events

• outbound, with url, when you add data-outbound="true" to the script tag.
• JavaScript errors are captured automatically as errors, not custom events (turn off with data-errors="false").

Where events show up

• The site's Events tab, with counts over time and recent occurrences with their properties.
• Your dashboard: once an event is common, Mosaicdeck suggests widgets for it.
• Your AI assistant, through the custom_events tool.

Good practice

• No personal data. Don't put names, email addresses or other personal details in event names or properties.
• Every event carries the page's path, with IDs and email addresses masked like page views (see private IDs and email addresses in URLs). Properties are sent as you set them, so don't copy the page's URL or IDs into them.
• Use short, stable names in snake_case, like signup or checkout_started.
• Event names and properties can be sent by anyone who has your site ID, so treat them as untrusted in your own tooling. Mosaicdeck always shows them as plain text, and labels them as visitor-supplied for your AI.

TypeScript

// global.d.ts
declare global {
  interface Window {
    mosaicdeck?: { track(name: string, props?: Record<string, string | number | boolean>): void };
  }
}
export {};