Device Mode integration allows tracking customer events on mobile or web platforms through embedding a Javascript tracker on the store that listens to the desired events and allows partners to process these events in realtime.
App Snippet Requirement#
Using Device Mode integration requires an App Snippet to inject the Javascript tracker to listen and process e-commerce events.
Getting Started#
Prerequisites#
Node.js (version 16 or higher)
pnpm (recommended) or npm
1. Cloning the Starter Kit & Installing Dependencies#
To prepare the tracker, Salla provides a starter kit that allows you to quickly implement the events you are interested in listening and process them easily.Once you have cloned the repository, it's time to install the required dependencies.2. Preview Events#
The starter kit ships with an example.html in the root of the project, which allows you to easily verify existing events as well as any new events you may add.To preview the events, run the development server:Then, open the example.html file in your browser and interact with the page to trigger the events and verify them in the browser console.3. Customizing Event Logic#
The starter kit provides boilerplate code for each event located in the /src/listeners/ directory.You can easily customize the logic as required for each event.
In this example, we modify the Cart Updated listener to post the event payload to a webhook URL:4. Adding New Events#
As we continue to add more events, you may update your project anytime by creating your own listeners to observe those events. The build system automatically wires new listeners as long as you follow the existing pattern.Create a new TypeScript file in /src/listeners/
5. Publishing Your Tracker#
Once you are happy with your tracker, it's time to publish and start testing it.Follow these steps to publish your tracker:5.1. Create an App in Salla Partners Portal#
Sign in with your Salla Partners account
Create a new app and configure its basic settings
Note down your app's details for the next steps
5.2. Build and Upload the Tracker#
Build your tracker for production:
dist/tracker.js file containing your compiled tracker.Upload the dist/tracker.js file to your preferred CDN service (e.g., AWS CloudFront, Cloudflare, or any other CDN)
Make note of the CDN URL where your tracker.js file is hosted
5.3. Add Tracker as Snippet#
Add a new Snippet with the CDN URL of your tracker.js file
5.4. Test in Demo Store#
Install your app in the demo store provided by Salla Partners Portal
Navigate through the demo store and perform various actions (view products, add to cart, checkout, etc.)
Open browser developer tools and check the console to verify your event listeners are working correctly
Test all the events you've customized to ensure they're tracking properly
5.5. Publish the App#
Once you've verified everything works correctly in the demo store
Navigate to your app and publish the changes
Your tracker will now be available for merchants to install and use
Development Commands#
Start development server:
Preview production build:
Debugging#
Use browser developer tools to inspect console logs
Check the Network tab for any failed requests
Verify that the Twilight SDK is properly loaded before the tracker initializes
Use TypeScript's type checking to catch errors early: pnpm type-check
Important Notes#
Testing: Always thoroughly test your tracker in the demo store before publishing
Performance: Ensure your tracker doesn't negatively impact store performance
Error Handling: The built-in error handling ensures individual listener failures don't break the entire tracking system
Updates: When you make changes to your tracker, repeat the build and upload process, then update the snapbit URL if necessary
Troubleshooting#
Events not firing: Check that the Salla Twilight SDK is properly loaded before your tracker
Console errors: Review your event listener implementations for any JavaScript errors
Missing events: Verify that all your custom event listeners are properly exported and follow the correct pattern
Modified at 2025-11-27 13:04:50
