Custom Events

Salla’s standard event tracking covers core e-commerce flows, but you can define custom events to handle everything else. Whether you need to monitor custom widget interactions, track unique user journeys, or log specific app behaviors, you can push customized payloads directly into the analytics pipeline from either the frontend or backend.

Where to Implement Frontend Events

You can trigger frontend custom events from several locations within the Salla ecosystem:

Salla App Snippets

Track specific actions related to your app's custom functionality.

Salla Themes

Embed tracking directly in your store theme to capture user interactions with unique UI elements.

Google Tag Manager

Manage and deploy custom tracking for complex scenarios or multi-platform analytics.

Tracking Custom Events

To fire a custom event from the frontend, use the Salla.analytics.track method.

`Salla.analytics.track(eventName, properties)`

Parameter	Type	Description
`eventName`	`string`	The name of your custom event (e.g., "Promotion Viewed").
`properties`	`object`	Key-value pairs containing the event payload.

Scenario: Tracking Promotions and Rewards

Here is how you would track a user viewing a seasonal promotion and subsequently claiming a loyalty reward. Always ensure you wrap your tracking calls inside Salla.onReady() so the analytics module is fully loaded.

Managing Event Context

Every event emitted by Salla automatically includes a context object containing environment data (browser, device, page, campaign). You can extend this context with custom properties, such as an A/B test variant or loyalty tier, using one of the following methods.

Global App Context (Recommended)

Use setAppContext to define context properties that will automatically attach to all subsequent events fired by your app or theme. The appId ensures isolation, preventing your context from overwriting data from other apps.

Per-Event Context (Not Recommended)

You can attach context to a single event by nesting a context key inside your properties object.

This approach is generally discouraged as it can lead to inconsistent data. We highly recommend using setAppContext or Scoped Context for isolated, reliable context management.

Scoped Context (Advanced)

Scoped context is ideal for components like Quick Add widgets, where a single user action might trigger multiple events, but you do not want the contextual data persisting into the broader, site-wide event stream.

Temporary Callback Scope

Use withAppScope to attach context exclusively within a specific code block. Once the block executes, the context is automatically stripped, preventing data leaks into unrelated events.

Advanced Configurations

Custom Trackers

If you need to send analytics data to a third-party destination not natively supported by Salla, you can register a custom tracker.

For complete implementation details, refer to the Custom Trackers API Reference.

Custom Tracker Best Practices:

Performance

Optimize your tracker to ensure it does not block the main thread or impact page load speeds.

Error Handling

Wrap custom trackers in try/catch blocks to prevent third-party failures from breaking the storefront UI.

Privacy Compliance

Ensure your implementation respects user consent settings and local data privacy regulations.

Avoid Duplication

Before building a custom tracker, verify if Salla already offers a native integration for your target platform.

A dedicated Debug Mode for Custom Events is currently in development and will be available soon

Where to Implement Frontend Events#

Tracking Custom Events#

Salla.analytics.track(eventName, properties)#

Managing Event Context#

Scoped Context (Advanced)#

Temporary Callback Scope#

Advanced Configurations#

Custom Trackers#

Where to Implement Frontend Events

Tracking Custom Events

`Salla.analytics.track(eventName, properties)`

Managing Event Context

Scoped Context (Advanced)

Temporary Callback Scope

Advanced Configurations

Custom Trackers