To load the widget on your application or website, you must use the Xtremepush SDK.

For Android and iOS applications, the widget can appear as a full screen view or an embedded web view.

For websites, the widget can appear as a floating overlay or is added as a specific element on your page.

📘

Prerequisites

You must use the Xtremepush SDK version from March 2026. This version is required to use Xtremepush Loyalty and embed the widget on your application See Android SDK Releases, iOS SDK Releases and Web SDK Releases.

The integration involves the following steps:

1. Set the loyalty endpoint to connect the widget to your specific project
2. Set the loyalty token to authenticate the user session. See Manage User Authentication for more information on how to generate and provide this token.
   1. Handle token expiry to prevent session disruption.
3. Load the widget on your app or website. You must set the endpoint and token before loading the widget. If the token is missing during the load attempt, an error occurs and the content will not load.

Set the Loyalty Endpoint

The loyalty endpoint is unique to your project and environment. It is required to route requests to the correct instance on the Xtremepush platform.

1. Identify your endpoint.

The endpoint follows the following format: p<project_id>.p.loyalty.<environment>.xtremepush.com:

• environment: Your specific region, for example, live, eu, or us.
• project_id: Your unique project ID in the Xtremepush platform.

The endpoint must be hardcoded in your SDK configuration. It currently cannot be derived automatically. Contact your Xtremepush onboarding team to confirm the correct endpoint for your project.

2. Set the Loyalty endpoint

new PushConnector.Builder(XPUSH_APP_KEY, GOOGLE_PROJECT_NUMBER)
                ...
                .setLoyaltyEndpoint("LOYALTY ENDPOINT")

+ (void)setLoyaltyEndpoint:(NSString *)endpoint;

xtremepush('set','loyalty_endpoint','value')

For web integrations, this function stores the endpoint in localStorage under the xtremepush.data object and within the XPStoreInstance. The value must be the specific loyalty endpoint string for your project as identified in the previous step.

Set the Loyalty Token

The loyalty token authenticates the user within the widget. You must use the JWT generated by your backend as described in Manage User Authentication.

mPushConnector.setLoyaltyToken(context, token);

+ (void)registerLoyaltyTokenHandler:(XPLoyaltyTokenHandler)handler;

xtremepush('set','loyalty_token','value')

For web integrations, this function stores the token in localStorage under xtremepush.data and sets it through the XPLoyaltyManagerInstance. The value must be the encoded string for your JSON Web Token.

Handle Token Expiry

Tokens expire based on the duration defined during the authentication process. See Manage User Authentication for more details.

You can implement a callback to allow your backend to refresh the token without disrupting the user session.

Android

1. Implement the LoyaltyTokenHandler in your application class.

public class XPushApplication extends Application implements LoyaltyTokenHandler

2. Add the implementation to your PushConnector.Builder configuration.

new PushConnector.Builder(XPUSH_APP_KEY, GOOGLE_PROJECT_NUMBER)
	.setLoyaltyTokenHandler(this)
	...

3. Implement the following callback to handle new token retrieval. This process should be asynchronous and must call setLoyaltyToken once the new token is received.

@Override
public void retrieveToken() {
    //custom handle new token retrieval, should be async and you should call set loyalty token when retrieved
}

iOS and Web

[XPush registerLoyaltyTokenHandler:^(XPLoyaltyTokenHandlerCompletion completion) {
        // Fetch/refresh JWT from client controlled service
        completion(jwt, error);
    }];

xtremepush('on','loyalty_token_expired', function(){
     //custom implementation
  });

Load the Widget

Once you have configured the endpoint and the token, you can load the widget. On mobile platforms, the widget supports both a full-screen view and an embedded web view. On the web, you can mount the UI as a floating widget or embed it directly into your page layout.

Android and iOS

Full Screen View

Use these methods to open the loyalty interface as a full-screen overlay:

mPushConnector.openLoyalty(context);

+ (void)openLoyalty;

Embedded View

To load loyalty content within your own web view instance, do the following:

Android

Retrieve the loyalty token and add the loyalty interface to your web view.

mPushConnector.openLoyalty(context);
webview.addJavascriptInterface(new LoyaltyJSInterface(), "loyaltyInterface");

iOS

Request the loyalty URL and load it into your web view.

[XPush getLoyaltyURLWithCompletion:^(NSURL * _Nullable url, NSError * _Nullable error) {
        dispatch_async(dispatch_get_main_queue(), ^{
            if (!error && url) {
                [self.webView loadRequest:[NSURLRequest requestWithURL:url]];
            }
        });
    }];

Web

Use mountLoyalty to render the widget. This method removes the need to retrieve a URL manually.

xtremepush('mountLoyalty', width, height, element);

• width (int): Define the width of the widget in pixels This value defaults to 400 if omitted.
• Height (int): Define the height of the widget in pixels. This value defaults to 600 if omitted.
• element: A DOM element that specifies the div element to inject the widget into. If you omit this parameter, the widget renders as a floating overlay.

Widget Mode

The widget renders as a standalone floating overlay.

xtremepush('mountLoyalty', 420, 640);

Embedded Mode

Add the widget into a specific element on your page.

const host = document.getElementById('loyalty-container'); 
xtremepush('mountLoyalty', 900, 600, host);