Widget Events

The loyalty widget communicates with your application through the browser's postMessage API. This allows you to handle widget lifecycle events, authentication errors, and user interactions.

All events from the widget include source: "Scrimmage" in the payload to identify the sender.

Listen for widget events

Add a message event listener to your application:

window.addEventListener('message', (event) => {
  // Verify the event origin matches your loyalty widget domain
  // Replace WIDGET_ORIGIN with your actual widget URL from the environment table
  const WIDGET_ORIGIN = 'https://p<project_id>.p.loyalty.<environment>.xtremepush.com';
  
  if (event.origin !== WIDGET_ORIGIN) {
    return;
  }

  const { source, type, payload } = event.data;

  if (source !== 'Scrimmage') {
    return;
  }

  switch (type) {
    case 'ready':
      console.log('Widget loaded successfully');
      break;
    case 'error':
      console.error('Widget error:', payload);
      break;
    case 'redirect':
      handleRedirect(payload);
      break;
  }
});

Replace <project_id> and <environment> in WIDGET_ORIGIN with your actual widget URL. See Load the Widget for the correct URL format.

Outbound events

The widget sends the following events to your application

ready

Fired when the widget has successfully loaded and the user can interact with the loyalty program.

Payload:

{
  "source": "Scrimmage",
  "type": "ready",
  "payload": {}
}

When to use: Show a loading indicator until this event fires, or track widget load analytics.

error

Fired when authentication or initialisation fails.

Payload:

{
  "source": "Scrimmage",
  "type": "error",
  "payload": {
    "type": "auth:init-failed",
    "message": "Initializing user failed",
    "data": {
      "status": 403
    }
  }
}

Error types:

For all authentication errors, verify your token generation logic and public key configuration. See Manage User Authentication for token requirements. Contact support if errors persist.

When to use: Display error messages to the user or log authentication failures for debugging.

redirect

Fired when a user clicks a deep link configured in a quest, achievement, or other loyalty feature.

Payload:

{
  "source": "Scrimmage",
  "type": "redirect",
  "payload": {
    "redirect": "some_deep_link",
    "parameters": {
      "target": "quest",
      "quest": {
        "status": "not-started",
        "progress": 0,
        "periodDeadline": null,
        "challenges": [
          { "completed": false, "progress": 0 }
        ],
        "user": { "id": "user_12345" },
        "quest": {
          "id": "20245278-f038-4053-b77a-63c74f5e80e8",
          "title": "Place 5 live bets",
          "onClickRedirect": "some_deep_link"
          // ...full quest configuration
        }
      },
      "userResources": {
        "tokens": 500,
        "levelConfig": { "level": 1, "name": "Level 1" },
        "nextLevelConfig": { "level": 2, "name": "Level 2" },
        "attributes": {
          "level.current": 1,
          "reward.primaryReward": 500,
          "quest.completionsTotal": 0
          // ...all user attributes and segment memberships
        }
      }
    }
  }
}

📘

The example above is trimmed for readability. The actual payload includes the full quest definition (challenges, reward bundle, schedule) and the complete user-attribute/segment map.

Payload fields:

• redirect: The deep-link string configured in the loyalty feature's onClickRedirect field. Clicking the link does not trigger any navigation within the widget. The value is passed to your application, which handles the navigation.
• parameters.target: Identifies which feature triggered the redirect (for example, quest).
• parameters.quest: Snapshot of the user's progress on the quest plus the full quest configuration. Present when target is quest.
• parameters.userResources: Snapshot of the user's resources at the moment of the click, including current and next level configuration, plus an attributes map containing all of the user's system attributes, custom attributes, and segment memberships. For a full list of system attributes, see Manage Loyalty Attributes.

When to use: Navigate to the specified URL in your application, or use parameters to customise the destination based on user state.

Inbound events

Your application can send the following events to the widget.

auth:token

Send a new authentication token to refresh an expired session without reloading the widget.

How to send:

const widgetIframe = document.getElementById('loyalty-widget-iframe');

// Replace with your actual widget URL from the environment table
widgetIframe.contentWindow.postMessage(
  {
    type: 'auth:token',
    payload: {
      token: 'eyJhbGc...' // New JWT token
    }
  },
  'https://p<project_id>.p.loyalty.<environment>.xtremepush.com'
);

Replace <project_id> and <environment> with your actual widget URL. See Load the Widget for the correct URL format.

When to use: When you receive an auth:token-expired error event, generate a new token on your back end and send it to the widget using this event. This prevents disrupting the user's session.

📘

Token refresh is seamless to the user. The widget automatically re-authenticates and continues loading content without a page reload.