Embed a microsite in a website or app

Learn how to embed the Loyalty Microsite in a website using an iFrame or a mobile app using WebView.

Embed in a website (iframe)

Embed in a mobile app (WebView)

Embed in a website (iframe)

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.

Requesting a Session Token: Make a secure HTTP request from your server to the microsite’s authentication endpoint, as outlined in Authenticate users in a microsite. This ensures that your “Client ID” remains protected.
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 Authenticate users in a microsite.

To ensure authentication functions correctly across all browsers, ensure the 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://microsite.url.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://microsite.url.com; geolocation self https://microsite.url.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);

Website embed 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.

Embed in a mobile app (WebView)

Embedding the Loyalty Microsite in a mobile app enables your loyalty program to integrate directly with your app’s user interface, providing a smooth experience without needing a deep-level API integration.

To configure a mobile WebView for the Loyalty Microsite, complete the following key steps:

Set up the correct permissions for the app’s platform (iOS or Android).
Ensure necessary UI handlers, such as dialogs and file access, are supported.
Pass the generated session token within the WebView request.
Load the appropriate URL based on the user’s locale.

The root URL to load within the WebView is the custom domain your microsite lives on.

iOS configuration

Permissions

Add the following permissions to the Info.plist to ensure correct functionality. Camera and photo permissions are needed if using receipt scanning.

<dict>
    <key>NSAppTransportSecurity</key>
    <dict>
        <key>NSAllowsArbitraryLoads</key>
        <true/>
    </dict>
    <key>NSCameraUsageDescription</key>
    <string>Camera access required to scan receipts.</string>
    <key>NSLocationWhenInUseUsageDescription</key>
    <string>Location verification needed for voucher redemption.</string>
    <key>NSPhotoLibraryUsageDescription</key>
    <string>Photo library access required to select receipt photos.</string>
</dict>

UI handlers

The view controller housing the WebView should implement the WKUIDelegate protocol to handle native confirmation dialogs:

func webView(_ webView: WKWebView,
                 runJavaScriptConfirmPanelWithMessage message: String,
                 initiatedByFrame frame: WKFrameInfo,
                 completionHandler: @escaping (Bool) -> Void) {
        let alertController = UIAlertController(title: message,
                                                message: nil,
                                                preferredStyle: .alert)

        alertController.addAction(UIAlertAction(title: "OK",
                                                style: .default,
                                                handler: { (action) in
            completionHandler(true)
        }))

        alertController.addAction(UIAlertAction(title: "Cancel",
                                                style: .cancel,
                                                handler: { (action) in
            completionHandler(false)
        }))

        present(alertController, animated: true, completion: nil)
    }

Android configuration

Permissions

Include the following permissions in the Android manifest. Camera and photo permissions are required if you plan to enable receipt scanning.

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

UI handlers

The Android WebView configuration requires additional setup. Refer to the example configuration in this repository for detailed setup instructions.

Language support

The Loyalty Microsite supports multiple languages, enabling you to offer a localized experience to your users. You can set a default language in the microsite settings, but you can specify a different language using the ?lang= parameter in the URL.

Currently, supported languages include French (fr), German (de), and Italian (it).

To load the microsite in French, for example, you would use the URL format: https://MICROSITEURL.COM?lang=fr

If you plan to deploy your microsite in a language other than English, please consult WLL Support to ensure proper configuration. See 4. Language support for more information.

PreviousConfigure a microsite domain NextAuthenticate users in a microsite

Last updated 4 days ago

Was this helpful?