Web SDK

Use the Web SDK when a website, e-commerce frontend, customer portal, or kiosk-style web experience needs to render Loyal Guru loyalty modules.

The SDK injects an iframe into a host container, passes the Customer JWT to the Loyal Guru module, listens for module events, and can automatically resize the iframe height.

Installation

CDN

Use the CDN when you want a simple script tag integration.

<script src="https://cdn.loyal.guru/sdk/v1.1.3/embed-sdk.umd.js"></script>

This exposes window.EmbedLoyaltyApp.

NPM

Use the package when the host app is built with a bundler such as React, Angular, Vue, or Next.js.

npm install @loyalguru/embed-sdk

If the package is distributed through the private Loyal Guru GitHub Packages registry, configure .npmrc with the registry and a token with read:packages access:

@loyalguru:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

Basic HTML Integration

<div id="loyalty-container"></div>

<script src="https://cdn.loyal.guru/sdk/v1.1.3/embed-sdk.umd.js"></script>
<script>
  EmbedLoyaltyApp.init({
    containerId: 'loyalty-container',
    iframeOrigin: 'https://your-loyalty-module.loyal.guru',
    token: 'CUSTOMER_JWT',
    locale: 'en',
    module: 'loyalty',
    autoResize: true,
    onLoad: () => console.log('Loyalty module loaded'),
    onError: (error) => console.error('Loyalty iframe error', error),
    onServerError: (serverError) => console.warn('Loyalty server error', serverError),
    onSize: ({ height }) => console.log('iframe height', height),
    onData: (message) => console.log('Loyalty data event', message),
  });

  EmbedLoyaltyApp.onTokenRefreshRequested(async () => {
    const response = await fetch('/api/loyalty-token/refresh');
    const { token } = await response.json();
    EmbedLoyaltyApp.refreshToken(token);
  });
</script>

React Example

import { useEffect, useId } from 'react';
import EmbedLoyaltyApp from '@loyalguru/embed-sdk';

type LoyaltyEmbedProps = {
  iframeOrigin: string;
  token: string;
  locale?: string;
  module?: string;
};

export function LoyaltyEmbed({
  iframeOrigin,
  token,
  locale = 'en',
  module = 'loyalty',
}: LoyaltyEmbedProps) {
  const containerId = `loyalty-container-${useId()}`;

  useEffect(() => {
    EmbedLoyaltyApp.init({
      containerId,
      iframeOrigin,
      token,
      locale,
      module,
      autoResize: true,
      onLoad: () => console.log('Loyalty module loaded'),
      onError: (error) => console.error('Loyalty iframe error', error),
      onServerError: (serverError) => console.warn('Loyalty server error', serverError),
      onData: (message) => console.log('Loyalty data event', message),
    });

    EmbedLoyaltyApp.onTokenRefreshRequested(async () => {
      const response = await fetch('/api/loyalty-token/refresh');
      const { token: refreshedToken } = await response.json();
      EmbedLoyaltyApp.refreshToken(refreshedToken);
    });

    return () => EmbedLoyaltyApp.destroy();
  }, [containerId, iframeOrigin, token, locale, module]);

  return <div id={containerId} style={{ width: '100%' }} />;
}

For Next.js, load the component from a client module using 'use client'.

Init Parameters

Field	Required	Description
containerId	Yes	DOM element where the iframe will be mounted.
iframeOrigin	Yes	Loyal Guru module origin provided for the Company/environment.
token	Yes for retailer-issued auth	Customer JWT generated by the host backend.
locale	No	Locale code such as en, es, it, or hr.
module	Yes	Module to load, such as loyalty, rewards, tiers, challenges, or games.
autoResize	No	If true, the SDK updates iframe height from module SIZE messages.
onLoad	No	Called when the iframe loads.
onError	No	Called when the SDK or iframe fails before a server response is available.
onServerError	Recommended	Receives backend errors emitted by the embedded module.
onSize	No	Receives iframe sizing messages.
onData	No	Receives module-specific data messages.

Loading Specific Modules

The module value is appended to the Loyal Guru module origin. Confirm the supported values for the Company with the Loyal Guru integration team.

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

Resizing

When autoResize is enabled, the embedded module posts SIZE messages and the SDK updates the iframe height.

EmbedLoyaltyApp.init({
  containerId: 'loyalty-container',
  iframeOrigin: 'https://your-loyalty-module.loyal.guru',
  token: 'CUSTOMER_JWT',
  module: 'challenges',
  autoResize: true,
  onSize: ({ height, width, origin }) => {
    console.log({ height, width, origin });
  },
});

If the host layout requires manual control, set autoResize: false and use onSize to update the container.