Device Mode allows you to capture E-commerce events directly from the storefront using a JavaScript tracker. The tracker listens for customer interactions and lets your application process them in real time.

Common use cases include:

Analytics and event tracking

Marketing automation

Personalization and UI reactions

Forwarding events to external services

Quickstart (5 Minutes)

If you just want to see events working quickly:

Then open:

example.html

Trigger actions on the page and check the browser console to see emitted events.

Once confirmed, you can customize listeners inside:

/src/listeners

Integration Overview

Device Mode works by injecting a tracker script into the storefront using an App Snippet.

The flow looks like this:

User Action
     │
     ▼
Twilight SDK emits event
     │
     ▼
tracker.js receives event
     │
     ▼
Your listener processes payload
     │
     ▼
Analytics / Webhook / API

App Snippet Requirement

To load your tracker in the merchant storefront, Device Mode requires an App Snippet.

The snippet injects your hosted tracker.js file into the store.

Learn more:
https://salla.dev/blog/a-guide-to-app-snippet/

Prerequisites

Before starting, install:

Node.js ≥ 16

pnpm (recommended) or npm

1. Clone the Starter Kit

Salla provides a starter kit that includes:

event listeners

build tooling

a testing page

TypeScript types for events

Clone the repository:

Install dependencies:

2. Run the Development Environment

Start the dev server:

Open the provided testing page:

example.html

Trigger interactions to simulate events and verify them in the browser console.

Project Structure

The starter kit follows a simple modular structure:

store-events-tracker-starter-kit
│
├── src
│   ├── listeners
│   │   ├── cart-updated.ts
│   │   ├── product-added.ts
│   │   └── checkout-started.ts
│   │
│   ├── tracker.ts
│   └── index.ts
│
├── example.html
├── package.json
└── vite.config.ts

Key directories:

Directory	Purpose
`/src/listeners`	Event handlers
`/src/tracker.ts`	Tracker initialization
`example.html`	Local testing page

3. Customize Event Logic

Each event has a dedicated listener inside:

/src/listeners

Example: sending the Cart Updated event to a webhook.

import {
  CartUpdatedPayload,
  EcommerceEvents,
} from "@salla.sa/ecommerce-events-base";

export const eventName = EcommerceEvents.CART_UPDATED;

export default async (payload: CartUpdatedPayload): Promise<void> => {
  try {
    const response = await fetch("https://acme.com/webhook", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        event: eventName,
        payload,
      }),
    });

    if (!response.ok) {
      console.error(
        `Webhook failed: ${response.status} ${response.statusText}`
      );
    }
  } catch (error) {
    console.error("Webhook error:", error);
  }
};

Example Event Payload

Example payload for Cart Updated:

{
  "event": "cart.updated",
  "timestamp": "2026-03-09T10:15:20Z",
  "store_id": 12345,
  "customer_id": 99821,
  "cart": {
    "id": "cart_abc123",
    "total": 320,
    "currency": "SAR",
    "items": [
      {
        "product_id": 54321,
        "name": "Wireless Headphones",
        "quantity": 1,
        "price": 320
      }
    ]
  }
}

This payload can be used for:

analytics pipelines

marketing attribution

webhook forwarding

personalization systems

4. Add New Event Listeners

To listen for new events:

Create a new file inside:

/src/listeners

Example:

import { EventPayload, EcommerceEvents } from "@salla.sa/ecommerce-events-base";

export const eventName = EcommerceEvents.YOUR_EVENT_NAME;

export default (payload: EventPayload): void => {
  console.log("Event received:", payload);

  // Custom logic
};

The build system will automatically register new listeners.

5. Deploy the Tracker

Once your tracker is ready, deploy it so merchants can install it.

Build the Tracker

This generates:

dist/tracker.js

Upload to a CDN

Upload the file to a CDN such as:

AWS CloudFront

Cloudflare

Vercel

Netlify

Example:

https://cdn.example.com/tracker.js

Add the App Snippet

Open the Salla Partners Portal

Navigate to your app

Go to Snippet

Add the CDN URL of tracker.js

The snippet will automatically inject the tracker into merchant stores.

Testing in a Demo Store

Before publishing:

Install the app in a demo store

Perform actions such as:

viewing products

adding items to cart

starting checkout

Open Developer Tools

Verify events in:

Console

Network tab

Publish the App

After successful testing:

Return to the Salla Partners Portal

Publish the app

Merchants can now install your tracker.

Recommended Architecture

For production apps, a common pattern is forwarding events to your backend.

Storefront
    │
    ▼
tracker.js
    │
    ▼
Webhook / API Gateway
    │
    ▼
Processing Service
    │
    ├── Analytics (Segment / Amplitude)
    ├── Data Warehouse
    └── Automation Systems

Benefits:

centralized event processing

scalable analytics pipelines

easier integrations with external services

Development Commands

Start dev server

pnpm dev

Build tracker

pnpm build

Preview production build

pnpm preview

Type check

pnpm type-check

Debugging Tips

If events are not firing:

Check browser console logs

Inspect network requests

Ensure Twilight SDK loads before tracker

Run TypeScript validation

pnpm type-check

Troubleshooting

Events not firing

Ensure the snippet is installed correctly

Confirm the Twilight SDK loads first

Console errors

Check listener implementation for runtime errors

Missing events

Verify event listener exports

Ensure files follow the required listener pattern

Device Mode

Quickstart (5 Minutes)#

Integration Overview#

App Snippet Requirement#

Prerequisites#

1. Clone the Starter Kit#

2. Run the Development Environment#

Project Structure#

3. Customize Event Logic#

Example Event Payload#

4. Add New Event Listeners#

5. Deploy the Tracker#

Build the Tracker#

Upload to a CDN#

Add the App Snippet#

Testing in a Demo Store#

Publish the App#

Recommended Architecture#

Development Commands#

Debugging Tips#

Troubleshooting#