SDK Reference
This page summarizes the SDK contract from the WL App & SDK commercial offer. Use it to align integration scope before choosing the specific web or hybrid-app implementation path.
Some implementation packages expose slightly different parameter names. For example, current Web SDK examples use token for the Customer JWT and iframeOrigin for the module URL, while the commercial SDK contract refers to jwt, tenantId, and environment. Confirm the exact package version and parameter names with the Loyal Guru integration team during project kickoff.
Init Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
jwt | string | Yes | Customer JWT issued by the retailer authentication system. Recommended TTL is 15-60 minutes. |
tenantId | string | Yes | Loyal Guru tenant identifier for the Company environment. |
environment | string | Yes | Target environment, such as production, staging, or sandbox. |
module | string | No | Specific module to load, such as coupons, wallet, Scratch & Win, Rewards, or full app. |
analytics | boolean | No | Set to false to disable analytics tracking inside the SDK. Defaults to enabled where configured. |
onTokenRefreshRequested | function | Yes | Callback fired when the SDK needs a fresh JWT. The host must call refreshToken(newToken). |
theme | object | No | Runtime theme overrides applied on top of the configured WL App brand style. |
locale | string | No | Force a specific locale, such as es-ES or it-IT, instead of using device/browser detection. |
postMessage Events
The SDK emits postMessage events from the iframe/WebView module to the host app for key interactions.
| Event | Payload | Host responsibility |
|---|---|---|
REQUEST_NEW_TOKEN | Empty payload. | Fetch a fresh Customer JWT and call refreshToken(newToken). |
NAVIGATION_EXTERNAL | URL to open externally. | Open the URL in the browser or native external-link handler. |
COUPON_REDEEMED | Coupon identifier and redeemed code. | Optionally update host UI or analytics after coupon redemption. |
POINTS_UPDATED | Updated balance and delta. | Optionally update native/header points balance outside the embedded module. |
GAME_RESULT | Game identifier, win flag, and optional prize payload. | Optionally trigger native animations, host analytics, or notifications. |
CHALLENGE_COMPLETED | Challenge identifier and reward payload. | Optionally update host UI or analytics after challenge completion. |
SESSION_EXPIRED | Empty payload. | Redirect to login or close the embedded session when refresh fails. |
Payload schemas can evolve by SDK version. Validate the final event list and payload shape during implementation.
Environments
| Environment | Purpose | Notes |
|---|---|---|
| Sandbox | Development and initial integration testing. | Pre-populated tenant with the Company's configured modules, Customers, campaigns, points rules, and Rewards where applicable. |
| Production | Live Customer traffic. | Fully managed by Loyal Guru. Autoscaled infrastructure and contractual SLA apply. |
The sandbox is a production-grade environment for integration testing. Do not treat it as disposable or unrestricted test infrastructure; data handling rules still apply.
Privacy and Compliance
| Requirement | How to handle it |
|---|---|
| GDPR | Registration, consent, account deletion, data access, and consent audit must follow the Company configuration and contractual setup. |
| Apple ATT | iOS tracking should respect App Tracking Transparency permission. |
| Google Play Data Safety | App store declarations are part of the deployment process for mobile apps. |
| CMP / Iubenda | Pass or respect consent state; disable SDK analytics when the host owns tracking. |
| Data residency | Confirm per contract before documenting or promising a region. |
| PCI DSS | Loyal Guru does not handle payment card data in the WL App SDK flow. |