---
title: "Load the Widget"
slug: "load-the-widget"
updated: 2026-06-16T10:00:53Z
published: 2026-06-16T10:00:53Z
canonical: "docs.xtremepush.com/load-the-widget"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xtremepush.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Load the Widget

Embed the loyalty widget on your website or mobile application using the Xtremepush SDK

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.

![](https://cdn.document360.io/b056e88b-f6c1-4bd2-b5b8-08e9336a17c9/Images/Documentation/6bfd59b165e1f122eb18195e62b82727cf11af6169f22c9948e739bfc5ac6e27-Screenshot_2026-03-23_at_15.40.16(1).png)

Loyalty Widget Preview on Android/iOS

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

![](https://cdn.document360.io/b056e88b-f6c1-4bd2-b5b8-08e9336a17c9/Images/Documentation/07b52185751fe0f428e6a86fe3129fec2b41265be68b2110f839e7bc4711f9a4-image_2(1).png)

![](https://cdn.document360.io/b056e88b-f6c1-4bd2-b5b8-08e9336a17c9/Images/Documentation/3484c19b58b91ac468498367842c44c39be9f8e1421037718927bd827b34e8a3-Screenshot_2026-03-23_at_15.47.18(1).png)

Loyalty Widet Preview in Websites

> [!NOTE]
> Widget Parameters
> 
> You can pass the following options to configure the widget through the Xtremepush SDK:
> 
> - `token `(required): A signed JWT generated by your back end to verify the user's identity. See [Manage User Authentication](/documentation/docs/manage-user-authentication) for details.
> - `lang` (optional): The language to display in the widget. Supported values include `en` (English), `es` (Spanish), `pt `(Portuguese), and others configured in your project.
> - color-mode (optional): Visual theme for the widget. Supported values:
>   - `auto`: Matches the user's system preference
>   - `light`: Forces light theme
>   - `dark`: Forces dark theme

> [!NOTE]
> 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](/documentation/docs/android-sdk-releases), [iOS SDK Releases](/documentation/docs/ios-sdk-releases) and [Web SDK Releases](/documentation/docs/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](/documentation/docs/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.

1. Set the Loyalty endpoint

**Java**

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

**Objective-C**

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

**JavaScript**

```javascript
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.

**Java**

```java
mPushConnector.setLoyaltyToken(context, token);
```

**Objective-C**

```objectivec
+ (void)registerLoyaltyTokenHandler:(XPLoyaltyTokenHandler)handler;
```

**JavaScript**

```javascript
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.

```java
public class XPushApplication extends Application implements LoyaltyTokenHandler
```

1. Add the implementation to your `PushConnector.Builder` configuration.

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

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

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

## iOS and Web

**Objective-C**

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

**JavaScript**

```javascript
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.

**Java**

```java
// 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);
```

**Swift**

```swift
// 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)
```

**Objective-C**

```objectivec
// 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];
```

#### 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.

**Java**

```java
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));
```

**Swift**

```swift
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))
    }
}
```

**Objective-C**

```objectivec
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];
    }
}];
```

### Web

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

```javascript
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.

```javascript
xtremepush('mountLoyalty', 420, 640);
```

#### Embedded Mode

Add the widget into a specific element on your page.

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