1.a iFrame embed

Learn how to embed the Loyalty Microsite in a website using an iFrame, manage authentication, configure permissions, and handle dynamic content height adjustments for seamless integration.

Embed the Loyalty Microsite in a website

Embedding the Loyalty Microsite in a website via an iFrame provides a seamless way to integrate WLL’s loyalty features directly into an existing webpage, allowing users to interact with the loyalty program without leaving your site. Here’s how to set up and configure the microsite in an iFrame.

For a sample iFrame implementation, see our embedding example on GitHub.

---

Handling user authentication

This step is only required if you are using embedded authentication to allow users to access the microsite without additional login steps.

1. Requesting a Session Token: Make a secure HTTP request from your server to the microsite’s authentication endpoint, as outlined in 2. Microsite authentication. This ensures that your “Client ID” remains protected.

2. Passing the Session Token: Pass the returned session token to the microsite within the iFrame by using a session query parameter or as a session cookie.

Using a session query parameter

Append the microsite URL with ?session=$sessionToken.

Using cookies

If using cookies, ensure the user’s browser receives the session cookie before loading the iFrame:

• From the Browser Context: The endpoint will automatically set the cookie.

• From the Server Context: The “Set-Cookie” header in your response should forward to the browser, or you can construct the cookie as explained in 2. Microsite authentication.

To ensure authentication functions correctly across all browsers, ensure the 3. Custom domain configured for your microsite matches that of the webpage hosting the iFrame.

---

Configuring the iFrame

Add an iFrame element on your webpage pointing to the microsite’s root URL, for example:

<iframe src="https://LOYALTY.YOURDOMAIN.COM"></iframe>

iFrame permissions

To enable location services (for reward redemption and receipt upload) and clipboard access (for email receipt uploads and refer-a-friend URL copying), add the following attributes to the <iframe> tag:

allow="clipboard-write self https://MICROSITEURL.COM; geolocation self MICROSITEURL.COM;"

iFrame postMessage communication

When embedded in an iFrame, the Loyalty Microsite uses the postMessage() feature to communicate with the iFrame parent window. You can use these messages to respond to navigation changes or dynamically adjust the iFrame’s height.

NAVIGATION message

Sent when a user navigates within the microsite. Contains the type, url, and contentHeight properties.

Message example

{
  type: "NAVIGATION",
  url: "https://example.com",
  contentHeight: 1000,
}

RESIZE_BODY message

Sent when the height of the microsite content changes. Contains the type and contentHeight properties.

The contentHeight value represents the height of the microsite content in pixels, specifically derived from the window.document.body.scrollHeight property. This allows the iFrame to dynamically adjust its height based on the actual content height within the microsite, ensuring smooth user experience without scrollbars.

Message example

{
  type: "RESIZE_BODY",
  contentHeight: 1000,
}

Example implementation for resizing the iFrame

function receiveMessage(event) {
  // must check that the message origin is legitimate
  if (!event.origin.endsWith("https://HOSTDOMAIN.COM")) {
    // return immediately to prevent further processing
    return console.info(
      "Received a potentially malicious message from an unexpected origin",
      event.origin
    );
  }

  if (event.data.type === "NAVIGATION") {
    var eFrame = document.getElementById("REPLACE_WITH_HTML_ID_ATTACHED_TO_YOUR_IFRAME_ELEMENT");
    window.scrollTo(0, 0);
    eFrame.height = event.data.contentHeight + event.data.contentHeight * 0.2;
  }
}

window.addEventListener("message", receiveMessage, false);

---

FAQs

Is it possible to load specific pages of the microsite directly in an iFrame?

Yes, you can add URL parameters to load specific microsite pages. For example, to load the Activity page, modify the iFrame src URL to include redirect_path=/activity (e.g., https://MICROSITEURL.COM?redirect_path=/activity).

What if my iFrame content height changes dynamically?

Use the postMessage() feature to handle dynamic height changes. The microsite sends a RESIZE_BODY message when the content height changes, allowing your iFrame to adjust its height based on the contentHeight value provided.