Using the JavaScript SDK
Follow the instructions below to include and initialize the JavaScript SDK. No extra steps are required for headless or SPA setups since the SDK does not rely on full page reloads to function.Include the JavaScript SDK
Follow the instructions for including the JavaScript SDK. You can either use the script tag approach or include the npm package using a bundler like Vite or Webpack.
Generate the customer token
Use a backend service to generate a customer token that identifies the currently-logged-in customer. It’s important that this occurs on the backend to avoid exposing your signing key to the general public.
Identify resources to preload
Read the guide on preloading resources and identify the loyalty data that you want to use or include on every page. Preloading resources helps improve performance by reducing the number of API calls made, and is especially useful for headless or SPA setups where full page reloads occur less frequently (or not at all).
Initialize the JavaScript SDK
Follow the instructions for initializing the JavaScript SDK, passing the customer token you generated as well as the list of resources you want to preload.
Start using the SDK
Once the SDK is included and initialized, you can start using it to fetch and interact with customer and loyalty data! Refer to the JavaScript SDK documentation for details on all of the available methods and resources.
Using Smile UI
Follow the instructions below to include and initialize Smile UI, and optionally load the JavaScript SDK alongside it.Key considerations
- Nudges — Nudges are not triggered or visible when using Smile UI on a custom storefront or on any site where the panel is manually added.
- Page reloads — The panel and launcher rely on full page reloads to detect when a customer has logged in or logged out, and to refresh customer state. On sites that do not trigger a full page reload when customer data changes, you must manually trigger a full reload so that Smile UI re-initializes correctly. Calling
SmileUI.initialize()again without a full page reload is not sufficient.
Integration instructions
Include Smile UI
Follow the instructions for including Smile UI to add a script tag on each page where you want the panel and launcher to appear.
Generate the customer token
Use a backend service to generate a customer token that identifies the currently-logged-in customer. It’s important that this occurs on the backend to avoid exposing your signing key to the general public.
Initialize Smile UI
Follow the instructions for initializing Smile UI, passing the customer token you generated in the previous step. If you want to load the JavaScript SDK alongside Smile UI, pass
includeSdk: true when initializing.Trigger page reloads after key customer actions
Since Smile UI relies on full page reloads to refresh customer data, you’ll need to ensure that a full page reload occurs whenever:
- A customer logs in or logs out,
- An action takes place outside of the Smile loyalty panel that might change the customer’s points balance or rewards status. For instance, redeeming points via the JavaScript SDK or completing a custom activity (that would cause them to earn points).
window.location.reload() or using a suitable equivalent for your frontend framework or setup.Reloading is only necessary when the customer is logged in; if no customer is logged in, a full page reload is not required.
Add links to open the panel
Once Smile UI is included and initialized, you can add links to your website (like menu items or buttons) that will open the panel to a specific page. Refer to the deep links guide for details on the different ways this can be accomplished.