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:

Set the loyalty endpoint to connect the widget to your specific project
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.
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.

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.

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

Implement the LoyaltyTokenHandler in your application class.

public class XPushApplication extends Application implements LoyaltyTokenHandler

Add the implementation to your PushConnector.Builder configuration.

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

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. You can optionally pass a path to open a specific section of the widget, and custom parameters to configure it.

On the web, the widget can be loaded as a floating overlay or embedded directly into your page.

Android and iOS

Full Screen View

Use openLoyalty to open the loyalty interface as a full-screen view. It can be called in three ways: to open the default view, to open a specific section using a path, or to open a specific section with custom parameters.

// Open default view
mPushConnector.openLoyalty(activity);

// Open a specific path
mPushConnector.openLoyalty(activity, "THE_PATH");

// Open a specific path with custom parameters
JSONObject params = new JSONObject();
params.put("color-mode", "dark");
params.put("lang", "es");
mPushConnector.openLoyalty(activity, "THE_PATH", params);

// Open default view
[XPush openLoyalty];

// Open a specific path
[XPush openLoyaltyWithPath:@"THE_PATH" params:nil];

// Open a specific path with custom parameters
NSDictionary *params = @{
    @"color-mode": @"dark",
    @"lang": @"es"
};
[XPush openLoyaltyWithPath:@"THE_PATH" params:params];

// Open default view
XPush.openLoyalty()

// Open a specific path
XPush.openLoyalty(withPath: "THE_PATH", params: nil)

// Open a specific path with custom parameters
let params = [
    "color-mode": "dark",
    "lang": "es"
]
XPush.openLoyalty(withPath: "THE_PATH", params: params)

Embedded View

To load loyalty content within your own web view instance, retrieve the loyalty URL and load it directly. The URL can be retrieved in three ways: for the default view, for a specific section using a path, or for a specific section with custom parameters.

WebView webview = (WebView) findViewById(R.id.loyalty_webview);
webview.getSettings().setJavaScriptEnabled(true);
webview.setWebViewClient(new WebViewClient());
webview.addJavascriptInterface(new LoyaltyJSInterface(), "loyaltyInterface");

// Load default view
webview.loadUrl(mPushConnector.getLoyaltyUrl(context));

// Load a specific path
webview.loadUrl(mPushConnector.getLoyaltyUrl(context, "THE_PATH"));

// Load a specific path with custom parameters
JSONObject params = new JSONObject();
params.put("color-mode", "light");
params.put("category", "promotions");
webview.loadUrl(mPushConnector.getLoyaltyUrl(context, "THE_PATH", params));

WKWebView *webView = [[WKWebView alloc] initWithFrame:CGRectZero];
webView.navigationDelegate = self;

// Load default view
[XPush getLoyaltyURLWithCompletion:^(NSURL * _Nullable url, NSError * _Nullable error) {
    if (url && !error) {
        NSURLRequest *request = [NSURLRequest requestWithURL:url];
        [webView loadRequest:request];
    }
}];

// Load a specific path
[XPush getLoyaltyURLWithPath:@"THE_PATH"
                      params:nil
                  completion:^(NSURL * _Nullable url, NSError * _Nullable error) {
    if (url && !error) {
        NSURLRequest *request = [NSURLRequest requestWithURL:url];
        [webView loadRequest:request];
    }
}];

// Load a specific path with custom parameters
NSDictionary *params = @{
    @"color-mode": @"light",
    @"category": @"promotions"
  };
  [XPush getLoyaltyURLWithPath:@"THE_PATH"
                        params:params
                    completion:^(NSURL * _Nullable url, NSError * _Nullable error) {
    if (url && !error) {
        NSURLRequest *request = [NSURLRequest requestWithURL:url];
        [webView loadRequest:request];
    }
}];

let webView = WKWebView(frame: .zero)
webView.navigationDelegate = self

// Load default view
XPush.getLoyaltyURL { url, error in
    if let url = url, error == nil {
        webView.load(URLRequest(url: url))
    }
}

// Load a specific path
XPush.getLoyaltyURL(withPath: "THE_PATH", params: nil) { url, error in
    if let url = url, error == nil {
        webView.load(URLRequest(url: url))
    }
}

// Load a specific path with custom parameters
let params = [
    "color-mode": "light",
    "category": "promotions"
]
XPush.getLoyaltyURL(withPath: "THE_PATH", params: params) { url, error in
    if let url = url, error == nil {
        webView.load(URLRequest(url: 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);