WL App SDK
The WL App SDK lets an external website, e-commerce site, customer portal, kiosk, or hybrid mobile app embed Loyal Guru loyalty modules without rebuilding the loyalty UI.
The host system owns the surrounding experience and, by default, customer authentication. Loyal Guru renders the loyalty module inside a secure iframe/WebView and handles the module logic, localization, token refresh, sizing, analytics bridge, and server error propagation. Prefer retailer-issued JWT into the SDK; LG-managed login is an exception for approved very small Full WL App clients only — see Authentication.
Start with the SDK Reference to align the commercial integration contract, then use the Web SDK or React Native guide for implementation details.
What you can embed
| Module | Typical use |
|---|---|
loyalty | Full loyalty area. |
rewards | Rewards catalog and redemption flows. |
tiers | Tier status and progress. |
challenges | Challenge list, detail, and progress. |
games | Scratch & Win or Spin the Wheel entry point and play flow. |
cart | Cart-related loyalty view when enabled for the deployment. |
The exact module list and URLs are provided by the Loyal Guru integration team for each Company and environment.
Integration paths
| Path | Use it when |
|---|---|
| SDK Reference | You need the common SDK contract: init parameters, postMessage events, environments, privacy, and compliance. |
| Web SDK | You want to embed loyalty modules in a website, e-commerce site, customer portal, or web app. |
| React Native / hybrid app | You want to embed the SDK inside an existing React Native or hybrid mobile app using a WebView. |
| Authentication | You need to implement JWT generation, refresh, and supported signing algorithms. |
| Events and error handling | You need to handle sizing, token refresh, data events, server errors, and analytics bridge messages. |
High-level flow
Responsibilities
| Responsibility | External system | Loyal Guru |
|---|---|---|
| Host website or app shell | Owns navigation, page placement, native app shell, and surrounding UX. | Provides the embedded loyalty module. |
| Customer authentication | Recommended: owns login/IAM and issues or refreshes Customer JWTs. | Validates JWTs and maps them to the Customer. LG-managed login only for approved very small Full WL App clients. |
| Loyalty UI | Provides container/WebView and styling context around the embed. | Renders loyalty module UI and business behavior. |
| Loyalty configuration | Uses the Loyal Guru platform to configure campaigns, Rewards, Games, Challenges, and content. | Serves the configured module in real time. |
| Analytics | Receives SDK events if enabled and routes them to the external analytics stack. | Emits module events through SDK callbacks/dataLayer bridge where configured. |
Before You Start
You need:
| Requirement | Description |
|---|---|
| Module origin | Loyal Guru URL for the embedded module in the target environment. |
| SDK access | CDN URL or package access to @loyalguru/embed-sdk. |
| JWT endpoint | Server-side endpoint that generates short-lived Customer JWTs. |
| Allowed origins | Production allowlist for the host and iframe origins. |
| Container | A DOM element or WebView host where the module will render. |
For product context, see WL App.