Events and Error Handling

The WL App SDK communicates with the embedded Loyal Guru module through postMessage. The SDK validates messages from the configured module origin and exposes callbacks to the host app.

Event Flow

Core Callbacks

Callback	When it fires	Host action
`onLoad`	The iframe loads.	Hide loading state or mark module as ready.
`onError`	SDK or iframe setup fails.	Show fallback UI and log the integration error.
`onServerError`	The embedded module receives a backend error.	Map to host error handling or support logging.
`onSize`	The module sends a size update.	Resize container manually if `autoResize` is disabled.
`onData`	The module emits a module-specific data message.	Update host state, analytics, or native UI elements.
`onTokenRefreshRequested`	The module needs a fresh JWT.	Fetch a new token and call `refreshToken(newToken)`.

Message Types

Message	Direction	Description
`AUTH_TOKEN`	SDK -> module	Sends the current token and locale after load or refresh.
`REQUEST_NEW_TOKEN`	Module -> SDK	Requests a fresh Customer JWT.
`SIZE`	Module -> SDK	Provides iframe height/width.
`SERVER_ERRORS`	Module -> SDK	Provides backend error details.
`LG_DATALAYER_EVENT`	Module -> SDK	Sends analytics payloads to the host data layer when enabled.
`DATA_TYPE`	Module -> SDK	Sends module-specific data, for example Rewards or game result information.
`NAVIGATION_EXTERNAL`	Module -> SDK	The Customer tapped an external URL that the host should open outside the embedded module.
`COUPON_REDEEMED`	Module -> SDK	A coupon redemption completed inside the embedded experience.
`POINTS_UPDATED`	Module -> SDK	Customer points balance changed.
`GAME_RESULT`	Module -> SDK	Customer completed a game play and received a win/lose result.
`CHALLENGE_COMPLETED`	Module -> SDK	Customer completed a Challenge.
`SESSION_EXPIRED`	Module -> SDK	Session expired and could not be refreshed.

Server Error Payload

Example:

{
  "type": "SERVER_ERRORS",
  "payload": {
    "status": 422,
    "message": "Validation error",
    "url": "https://api.loyalguru.com/...",
    "errorCode": "VALIDATION_ERROR",
    "errorBody": {},
    "ts": 1731612345123
  }
}

Recommended handling:

Status	Recommended host behavior
`400`	Show validation fallback or log integration contract issue.
`401`	Refresh token if possible; otherwise redirect to login.
`403`	Show access-denied or unavailable module state.
`404`	Show module/content not found fallback and verify module URL.
`422`	Show user-facing validation copy when relevant, otherwise log for support.
`500`	Show generic fallback and retry option; log error context.

Data Events

Example:

{
  "type": "DATA_TYPE",
  "payload": {
    "module": "Rewards",
    "message": "{ Json with rewards info }",
    "ts": 1731612345123
  }
}

Use onData only for host-level reactions. The embedded Loyal Guru module remains the source of truth for loyalty UI and state.

Analytics Bridge

When analytics is enabled, the embedded module can emit LG_DATALAYER_EVENT messages. The SDK can push them into window.dataLayer so the host can route events to GTM, GA4, Segment, Mixpanel, or another analytics tool.

Set up the host data layer before initializing the SDK:

window.dataLayer = window.dataLayer || [];

EmbedLoyaltyApp.init({
  containerId: 'loyalty-container',
  iframeOrigin: 'https://your-loyalty-module.loyal.guru',
  token: 'CUSTOMER_JWT',
  module: 'loyalty',
  gtmEnabled: true,
});

If the retailer manages tracking entirely outside the embedded module, disable the analytics bridge where supported.

Troubleshooting

Symptom	What to check
Nothing renders	`containerId` exists before `init()`, module origin is reachable, SDK script/package loaded.
`CONTAINER_NOT_FOUND`	The host calls `init()` before the DOM node exists.
Iframe fails to load	Wrong `iframeOrigin`, blocked network request, CSP restriction, or environment mismatch.
Token refresh loop	Refresh endpoint returns an expired token or does not map to the same Customer.
401 from module	Invalid token, expired token, unknown Customer, wrong Company slug, or unsupported signing key.
Auto-resize does not work	`autoResize` disabled, parent container fixed height/overflow, or module not emitting `SIZE`.
Cross-origin blocked	Missing allowed origin, strict CSP, or production origin validation mismatch.
Analytics not visible	`gtmEnabled` disabled, `window.dataLayer` missing, consent disabled, or host tag manager not listening.

Production Checklist

Area	Check
Origins	Use strict allowlists for host and iframe origins.
CSP	Allow the SDK script and Loyal Guru module origin.
Token refresh	Implement `onTokenRefreshRequested` before go-live.
Error logging	Log `onServerError` payloads with enough context for support.
Responsive layout	Test mobile, tablet, and desktop widths.
Consent	Confirm analytics and tracking behavior respects Customer consent.

Event Flow​

Core Callbacks​

Message Types​

Server Error Payload​

Data Events​

Analytics Bridge​

Troubleshooting​

Production Checklist​