> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mx.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Integrate the Insights Widget
This guide shows you how to integrate the Insights Widget on a [website using an iFrame](#integrate-on-a-website-iframe), on a [website using the Widget Loader](#integrate-on-a-website-widget-loader), or on the [mobile app](#integrate-on-a-mobile-app).
For information on widget behavior, reference the [Widget Overview](/products/experience/insights/widget-overviews/insights-widget).
**INFO**
Before you can integrate the widget, you must have worked with MX to enable your access to insights.
For this guide, you'll either use the Platform API or SSO API. The API you use depends on what you have purchased and have enabled. If you have the Nexus API enabled, you'll use the SSO API.
## Integrate on a Website (iFrame)
This shows how to integrate the widget on a website using an iFrame.
#### Step 1
Create an iFrame.
Make sure the width and height uses the widget's [supported dimensions](../../insights/widget-overviews/insights-widget#supported-dimensions).
If you use `sandbox`, some attributes must be whitelisted for the widget to work: `sandbox="allow-forms allow-same-origin allow-scripts"`.
```html Example focus=1-5 theme={null}
```
#### Step 2
In the iFrame's `src`, you'll need to request a widget URL and specify `pulse_widget` as the `widget_type` using the [Platform API](/api-reference/platform-api/reference/request-widget-url) or [SSO API](/api-reference/sso/v3/reference/widget-urls/get-widget-with-config-options).
The URL you'll receive is single-use and expires after 10 minutes. You must request a new URL every time the page is rendered.
See [Example API Requests](#example-api-requests) for different configurations.
```html Example focus=1-5 theme={null}
```
#### Step 3
Optionally create listeners for [application events](#application-events).
See [Postmessage UI Events](#postmessage-ui-events) for more info.
```html Example focus=6-19 theme={null}
```
#### Step 4
Configure event listeners for each [Insights Widget event](#insights-widget-events).
See [Postmessage UI Events](#postmessage-ui-events) for general info on our postMessage events.
```html Example focus=19-22 theme={null}
```
**SUCCESS**
Congrats! You've integrated the Insights Widget!
## Integrate on a Website (Widget Loader)
This shows how to integrate the widget on a website using the widget loader.
#### Step 1
Add the widget loader script to the page. Place this file before any other code related to the widgets. This custom script loads the widgets onto the page.
You can load the widget loader from the MX production server or download and store it in your local environment. We update the widget loader when needed, so if you're caching it on your server, refresh your cached version monthly.
```html Example focus=4 theme={null}
My Web Page
```
#### Step 2
Add a widget placeholder element. Our widget loader will use this placeholder element to embed an iframe containing the widget. The element must have an `id` of `md-widget`.
```html Example focus=14 theme={null}
My Web Page
```
#### Step 3
Load the widget into the placeholder element.
Create a new instance of the `MoneyDesktopWidgetLoader` class, which is defined in the widget loader script. When you instantiate `MoneyDesktopWidgetLoader`, you must pass in an object with at least the required URL parameter (see step 4), and possibly one or more [optional parameters](#widget-loader-parameters).
The widget loader will wait until the page has been loaded, and then load the widget into the placeholder element.
Make sure the widget uses its [supported dimensions](/products/experience/insights/widget-overviews/insights-widget#supported-dimensions).
```html Example focus=5-11 theme={null}
My Web Page
```
#### Step 4
You'll need to request a widget URL through the Platform API or SSO API and set it in the URL parameter.
The URL you'll receive is single-use and expires after 10 minutes. You must request a new URL every time the page is rendered.
You can request a widget URL for the Insights Widget by specifying `pulse_widget` as the `widget_type`, using the [Platform API](/api-reference/platform-api/reference/request-widget-url) or [SSO API](/api-reference/sso/v3/reference/widget-urls/get-widget-with-config-options).
```html Example focus=7 theme={null}
My Web Page
```
#### Step 5
Optionally create listeners for [application events](#application-events).
See [Postmessage UI Events](#postmessage-ui-events) for more information.
```html Example focus=15-29 theme={null}
My Web Page
```
#### Step 6
Configure event listeners for the [Insights Widget events](#insights-widget-events).
See [Postmessage UI Events](#postmessage-ui-events) for general info on our postMessage events.
```html Example focus=28-33 theme={null}
My Web Page
```
**SUCCESS**
Congrats! You've integrated the Insights Widget!
***
## Integrate on a Mobile App
To integrate the widget on a mobile application:
1. Request `pulse_widget` as the `widget_type`, using the [Platform API](/api-reference/platform-api/reference/request-widget-url) or [SSO API](/api-reference/sso/v3/reference/widget-urls/get-widget-with-config-options). The URL you'll receive is single-use and expires after 10 minutes. You must request a new URL every time the page is rendered.
2. Load the URL received from the previous request into a WebView.
3. See [Events in Mobile WebViews](#events-in-mobile-webviews).
4. Capture and parse URLs for [application events](#application-events).
5. Capture and parse URLs for [Insights Widget events](#insights-widget-events).
### Common Problems
This section covers some common problems with loading a widget URL into a WebView.
#### Minimum Size
To embed our mobile widgets into a WebView, we require a device width of at least 320 pixels. Depending on the implementation of the WebView, smaller devices may not be provided the full width, leading to display issues.
#### WKWebView vs. UIWebView (iOS)
In apps that run in iOS 8 and later, MX only supports WKWebView. If you previously implemented UIWebView, update your implementation to use WKWebView.
Apple recommends this. For more information, see Apple's developer documentation for [UIWebView](https://developer.apple.com/documentation/uikit/uiwebview) and [WKWebView](https://developer.apple.com/documentation/webkit/wkwebview).
#### Default Padding (iOS)
iOS adds padding to its WebViews by default, which can cause problems.
To fix this:
1. Select the WebView providing the widgets in your application and navigate to the size inspector.
2. Change the layout margins from "Default" to "Explicit."
3. Update the left and right margins to "0."
4. Ensure the Width is at least 320 pixels.
#### Default Margin (iOS and Android)
Most browsers will have a default margin (set in the user agent stylesheet) on the body element when rendering the HTML page responsible for loading a widget. This margin is deducted from the total available width of the containing element, which will cause a problem.
To fix this:
1. Determine the computed width available on the body element. The width available to the iframe can be confirmed by inspecting the iframe injected by MX and typing window\.innerWidth in the javascript console. The width available to the iframe must be at least 320 pixels.
2. Confirm the body and HTML elements have their padding and margin set to "0."
#### Viewport (iOS and Android)
For mobile widgets to render properly, the viewport must be set in a meta tag on the HTML page used to load the widget URL.
The viewport is the size of the window through which a page is seen. It can be smaller or larger than the actual size of a page or device screen.
On most mobile devices, the virtual viewport is larger than the actual screen size; web pages render according to the viewport size, then shrunk down to the actual screen size. This helps when viewing pages that aren't optimized for mobile, but for pages that are optimized for mobile (like the mobile widgets), the viewport meta tag is used to guarantee that the page renders correctly.
Set a meta tag within the `` element as follows.
```html Example theme={null}
```
## Example API Requests
The following examples are for requesting a Micro Widget URL in the Platform API.
Request a widget to **embed on a website.**
```curl theme={null}
curl -L -X POST 'https://int-api.mx.com/users/{user_guid}/widget_urls' \
-H 'Content-Type: application/json' \
-H 'Accept: application/vnd.mx.api.v20231004+json' \
-H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}' \
--data '{
"widget_url": {
"widget_type": "pulse_widget"
}
}'
```
Request a widget to **embed on a mobile app through a WebView.**
```curl theme={null}
curl -L -X POST 'https://int-api.mx.com/users/{user_guid}/widget_urls' \
-H 'Content-Type: application/json' \
-H 'Accept: application/vnd.mx.api.v20231004+json' \
-H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}' \
--data '{
"widget_url": {
"is_mobile_webview": true,
"widget_type": "pulse_widget"
}
}'
```
**Request the widget in Spanish** by adding the `Accept-Language` header and setting it to `es`.
```curl theme={null}
curl -L -X POST 'https://int-api.mx.com/users/{user_guid}/widget_urls' \
-H 'Content-Type: application/json' \
-H 'Accept: application/vnd.mx.api.v20231004+json' \
-H 'Accept-Language: es' \
-H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}' \
--data '{
"widget_url": {
"widget_type": "pulse_widget"
}
}'
```
## PostMessage UI Events
When certain events are triggered in our UI, we send you a postMessage UI event. These events have the information you need to take action in your codebase in response to the event.
If integrating on mobile through a WebView, an alternative to standard postMessage UI events is required. See [Events in Mobile WebViews](#events-in-mobile-webviews) for more information.
**WARNING**
Don't use postMessage UI events for keeping data in sync between platforms. [Webhooks](/resources/webhooks) are a more reliable way of coordinating events between your servers and MX servers.
PostMessage UI events from MX have the following properties:
* The `mx` field that lets you filter out postMessage UI events coming from MX.
* The `type` field that identifies what the event represents at a high level.
* The `metadata` object field that has information related to the `type`.
The following is an example integration that lets you listen to the events we send.
```js Example Integration theme={null}
function handleEvent(event) {
if (event.data.mx) {
// handle the mx post message using event.data.type and event.data.metadata.
}
}
window.addEventListener('message', handleEvent)
```
### Events in Mobile WebViews
**NOTE**
This section only applies if you are embedding the widget in a WebView.
Because of the technical limitations of WebView-based widget integrations, an alternative to standard postMessage UI events is required if embedding the widget into a WebView.
When requesting widget URLs using the Platform API or SSO API, you must include the `is_mobile_webview` field with a value of true in your request to access WebView event messages.
In WebView integrations, you must capture the URLs delivered via `window.location = "someurl"` calls within the iframe and use the information provided in those calls to build the necessary logic for coordinating events.
All MX URL message events will have the `mx://` prefix as well as the following format: `mx:///?metadata=`.
The following is an example URL message:
`mx://account/created?metadata="{'guid':'ACT-1'}"`.
You must capture the URL, parse out the path and query string, then JSON-decode the `metadata` field.
### Application Events
You must create listeners for our postMessage UI application events.
#### Widget Load
This event is triggered when the widget is loaded.
```json theme={null}
{
"type": "mx/load",
"mx": true
}
```
#### Widget Ping
This event is used to keep the widget session alive.
```json theme={null}
{
"type": "mx/ping",
"mx": true,
"metadata": {
"user_guid": "USR-123",
"session_guid": "ANS-123"
}
}
```
#### Widget focusTrap
This event is triggered when popover content which traps the focus onto a particular element is opened or closed, but only in the case that no other popover content is already open. This event is triggered by some drawers, menu buttons, and modals.
```json theme={null}
{
"type": "mx/focusTrap",
"mx": true,
"metadata": {
"trapped": "true"
}
}
```
### Insights Widget Events
When displayed in the Insights Widget, some insights contain a call-to-action (CTA). Some CTAs will direct the user to the appropriate location by default, but others will require you to send the user somewhere to complete an action.
This process is as follows:
1. We detect that a user has clicked a call-to-action (CTA) on one of our insights that require you to send the user somewhere outside of our widget.
2. We send you a postMessage UI event to let you know a user has clicked this CTA. Depending on the CTA and associated insight that the user clicked, we'll send you additional information about the event inside the postMessage UI event.
3. The listener **you** create for this event sends the user to the appropriate location within your mobile app or website based on the details we sent through the postMessage.
You must create listeners for each of the following insight templates (only create listeners for the templates MX has enabled for you).
| Insight Template | When MX Sends This Event | What You Must Do |
| :----------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DesignateEmergencySavingsAccount` | When the user clicks the **Open Savings Account** CTA in the scenario where the user doesn't have a savings account. | Send the user to open a savings account. |
| `EmergencyFundWithdrawal` | When the user clicks the **View my emergency savings** CTA or the **Transfer funds** CTA. The CTA that appears depends on if you have transfers for funds enabled. | When MX sends you this event, you must either send the user to view their emergency savings or create a transfer, depending on whether you have transfers for funds enabled or disabled. |
| `LowAccountBalance` | When the user clicks the **Transfer funds** CTA. | Send the user to transfer funds to their low balance account. |
| `MonthlyEmergencyFundReview` (scenario 1) | When the user clicks the **View my emergency savings** CTA. | Send the user to where they can view their emergency savings amount. |
| `MonthlyEmergencyFundReview` (scenario 2) | When the user clicks the **Create new goal** CTA. | Send the user to the Goals Widget. |
| `MonthlyEmergencyFundReview` (scenario 3) | When the user clicks the **Create transfer** CTA. | Send the user somewhere where they can transfer money. |
| `MonthlyObligationsStatus` | When the user clicks the **Make a transfer** CTA. | Send the user somewhere where they can transfer money. |
| `MonthlySpendingPlanCelebration` | When the user clicks the **Visit spending plan** CTA. | Send the user to the Spending Plan Widget. |
| `ReplenishSavings` | When the user selects the **Create Transfer** CTA. | Send the user to create a transfer to their savings account. |
| `SaveAnExtra100Dollars` | When the user selects the **Make A Transfer** CTA. | Send the user to where they can make a transfer. |
| `SavingsAccountDeposit` | When the user selects either the **View my emergency savings** or **Start saving for emergencies** CTA. | Send the user to the Goals Widget. From there the user can see their emergency savings goal or start an emergency savings goal. |
| `SavingsMilestoneEmergencyFund` | When the user selects the **View my emergency savings** CTA. | Send the user to where they can view the Goals Widget. |
| `SavingsOpportunityV2` (scenario 1) | This insight template has two scenarios. This covers scenario 1, where `"action": 'op_1'`. We'll send you a postMessage for this scenario when the user already has an eligible savings account to transfer money to and selects the **Transfer Funds** CTA. | Send the user to create a transfer to their savings account. |
| `SavingsOpportunityV2` (scenario 2) | This insight template has two scenarios. This covers scenario 2, where `"action": 'op_2'`. We'll send you a postMessage for this scenario when the user doesn't have an eligible savings account to transfer money to and selects the **Open Savings Account** CTA. | Send the user to open a savings account. |
| `SpendingPlanCreatedCelebration` | When the user clicks either the **Start Spending Plan** or **Visit Spending Plan** CTA. | Send the user to the Spending Plan Widget. |
| `SwitchDirectDeposit` | When the user clicks the **Switch Direct Deposit** CTA. | When MX sends you this event, you must activate your direct deposit integration. |
| `TransparentOverdraft` | When the user clicks the **Transfer funds** CTA. | Send the user to transfer funds to their potentially overdrawn account. |
| `UnifiedDepositEmergencyFund` (scenario 1) | When the user clicks the **Start saving for emergencies** CTA. | Send the user to the Goals Widget. |
| `UnifiedDepositEmergencyFund` (scenario 2) | When the user clicks the **Transfer funds** CTA. | Send the user to a location where they can transfer funds to their emergency savings fund. |
| `UnifiedDepositEmergencyFund` (scenario 3) | When the user clicks the **View my emergency savings** CTA. | Send the user to the Goals Widget. |
| `WeeklyNoSpendDays` | When the user clicks the **Visit Spending Plan** CTA. | Send the user to the Spending Plan Widget, where they can see the widget as normal or onboard to it. |
These are the base metadata fields for each event we send. Fields specific to certain insight templates appear in the sections that follow.
| Field | Type | Definition |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `action` | String | Represents the scenarios within the insight. This value, and additional fields relating to this value, are listed in the sections that follow. Most insights only have one scenario. The `SavingsOpportunityV2` insight will require you to configure events for two possible scenarios within that insight. |
| `beat_guid` | String | Insights were previously called "beats." This is the unique identifier for the insight. Defined by MX. |
| `beat_template` | String | Insights were previously called "beats." This is a short label for the insight being delivered. For example, `DesignateEmergencySavingsAccount`. |
```json Example theme={null}
{
"type": "mx/pulse/beat/cta",
"mx": true,
"metadata": {
"action": "op_1",
"beat_guid": "BET-123",
"beat_template": "DesignateEmergencySavingsAccount"
}
}
```
#### DesignateEmergencySavingsAccount Action
`"action": 'op_1'`.
#### EmergencyFundWithdrawal Action
`"action": 'op_1'`
#### LowAccountBalance Action
`"action": 'op_1'`.
| Field | Type | Definition |
| -------------- | ------ | ----------------------------------------------------- |
| `account_guid` | String | The unique identifier for the account. Defined by MX. |
#### MonthlyEmergencyFundReview Actions
The following values for used for different scenarios in the insight and don't have any fields beyond the base metadata fields.
* `"action": 'op_1'`.
* `"action": 'op_2'`.
* `"action": 'op_3'`.
#### MonthlyObligationsStatus Action
`"action": 'op_1'`.
#### MonthlySpendingPlanCelebration Action
`"action": 'op_1'`.
#### ReplenishSavings Action
`"action": 'op_1'`.
| Field | Type | Definition |
| ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------ |
| `account_guid` | String | The unique identifier for the account. Defined by MX. |
| `account_name` | String | The human-readable name of the account. |
| `accounts` | Array | An array of account objects, each of which contains the `account_guid` and `account_name` described in this table. |
| `total_amount_withdrawn` | Integer | The total amount withdrawn from all included accounts. |
#### SaveAnExtra100Dollars Action
`"action": 'op_1'`.
#### SavingsAccountDeposit Action
`"action": 'op_1'`.
| Field | Type | Definition |
| :------------------------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------- |
| `account_guid` | String | The unique identifier for the account. Defined by MX. |
| `goal_guid` (if available) | String | The unique identifier for the goal. Defined by MX. This field will return an empty string for the "start saving for emergencies" scenario. |
| `user_guid` | String | The unique identifier for the user. Defined by MX. |
#### SavingsMilestoneEmergencyFund Action
`"action": 'op_1'`.
| Field | Type | Definition |
| :------------- | :----- | :---------------------------------------------------- |
| `account_guid` | String | The unique identifier for the account. Defined by MX. |
| `goal_guid` | String | The unique identifier for the goal. Defined by MX. |
| `user_guid` | String | The unique identifier for the user. Defined by MX. |
#### SavingsOpportunityV2 Actions
`"action": 'op_1'`.
| Field | Type | Definition |
| ------------------------- | ------- | --------------------------------------------------------------------------------- |
| `amount` | Integer | The amount the user would like to transfer to savings. |
| `destination_account_ids` | Array | The partner-defined identifiers for the accounts eligible to transfer funds to. |
| `source_account_ids` | Array | The partner-defined identifiers for the accounts eligible to transfer funds from. |
`"action": 'op_2'`.
| Field | Type | Definition |
| -------------------- | ------- | --------------------------------------------------------------------------------- |
| `amount` | Integer | The amount the user would like to transfer to savings. |
| `source_account_ids` | Array | The partner-defined identifiers for the accounts eligible to transfer funds from. |
#### SpendingPlanCreatedCelebration Action
`"action": 'op_1'`.
#### TransparentOverdraft Action
`"action": 'op_1'`.
| Field | Type | Definition |
| ---------------------------- | ------- | --------------------------------------------------- |
| `destination_account_ids` | Array | Array of potentially overdrawn account numbers. |
| `projected_overdraft_amount` | Integer | The projected amount the account will be overdrawn. |
| `user_guid` | String | The unique identifier for the user. Defined by MX. |
#### UnifiedDepositEmergencyFund Actions
`"action": 'op_1'`.
| Field | Type | Definition |
| :------------- | :----- | :---------------------------------------------------------------------------------------------------------------- |
| `account_guid` | String | The unique identifier for the account. Defined by MX. |
| `goal_guid` | String | The unique identifier for the goal. Defined by MX. For this action, the `goal_guid` will be an empty string `''`. |
| `user_guid` | String | The unique identifier for the user. Defined by MX. |
`"action": 'op_2'`.
| Field | Type | Definition |
| :------------- | :----- | :---------------------------------------------------- |
| `account_guid` | String | The unique identifier for the account. Defined by MX. |
| `goal_guid` | String | The unique identifier for the goal. Defined by MX. |
| `user_guid` | String | The unique identifier for the user. Defined by MX. |
`"action": 'op_3'`.
| Field | Type | Definition |
| :------------- | :----- | :---------------------------------------------------- |
| `account_guid` | String | The unique identifier for the account. Defined by MX. |
| `goal_guid` | String | The unique identifier for the goal. Defined by MX. |
| `user_guid` | String | The unique identifier for the user. Defined by MX. |
#### WeeklyNoSpendDays Action
`"action": 'op_1'`.
## Widget Loader Configurations
This section is for integrating a widget on desktop using the Widget Loader.
It shows the [parameters](#widget-loader-parameters) you'll use to set things like the widget's height and width, [additional configurations](#additional-configurations) that let you set configurations for specific widgets, and also has the following sections to further help your integration:
* [Create a Loading Message](#create-a-loading-message)
* [Keeping a Session Alive and Logging Out](#keeping-a-session-alive-and-logging-out)
* [Loading Multiple Widgets](#loading-multiple-widgets)
* [Loading Widgets at Different Times](#loading-widgets-at-different-times)
* [Master Widget Deep Linking](#master-widget-deep-linking)
### Widget Loader Parameters
When you instantiate `MoneyDesktopWidgetLoader`, you must pass in an object with at least the required URL parameter, and any of the following optional parameters.
| Parameter | Required? | Default Value | Description |
| ------------------ | --------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `autoload` | No | `true` | Determines if the widget loads automatically. See [Loading Widgets at Different Times](#loading-widgets-at-different-times). |
| `config` | No | | This contains an object in which you can set configurations. Some of these configurations are for specific widgets. While setting configurations this way is supported, the most current way of settings these configurations is through the widget URL request. See [Configuration Options](#configuration-options) for more info. |
| `deep_link_params` | No | | This allows you to request a widget URL and provide a desired `launch_integration` destination. This requested widget URL will immediately mount the Atomic direct-deposit UX. |
| `height` | No | `600` | The widget's height, in pixels or a percentage. |
| `id` | No | `'md-widget'` | Tells the widget loader what element to place the widget in. See [Loading Multiple Widgets](#loading-multiple-widgets). |
| `width` | No | `'100%'` | The widget's width, in pixels or a percentage. |
| `url` | Yes | | The widget's URL, received through an SSO API or Platform API request. |
#### Config Parameter
The `config` object, as shown in the following example, contains configurations options.
```html Example theme={null}
var myWidget = new MoneyDesktopWidgetLoader({
url: getUrl(url),
width: 850,
height: 550,
config: {
pulse: {
ui_message_version: 4
}
},
postMessageOrigin: "*"
});
```
You can set the following configuration options.
| Configuration Option | Data Type | Description |
| -------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `is_mobile_webview` | Boolean | Defaults to `false`. Renders the widget in a mobile WebView. Executes URL updates in place of the JavaScript event postMessages. |
| `language` | String | **Deprecated**. See [Localize Insights Widgets](/products/experience/insights/integration-guides#localize-the-insights-widgets). |
| `ui_message_version` | Integer | Use this to specify which version of postMessage UI events are triggered. All new implementations must include this option when getting any widget URL and must set it to version `4`. Prior versions are deprecated and supported only for existing integrations. |
#### Deep Linking Parameter
You can set the following deep-linking options.
| Deep Link Option | Data Type | Description |
| -------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `launch_integration` | String | **Must be `direct-deposit`.** This lets the widget know to “deep link” to a specific integration. If the `account_guids` are provided under the `deep_link_params`, the direct-deposit session will be initiated with those accounts as potential deposit destinations. |
### Create a Loading Message
Any HTML placed inside of the widget placeholder element will be replaced once the widget iframe has loaded. This means you can use the placeholder element's inner HTML to display a loading message. Since this is just HTML, it can be text, images, or anything you want.
The following example adds some loading text that will appear until the widget has loaded.
```html Example theme={null}
My Web Page
Loading...
```
### Keeping a Session Alive and Logging Out
MX provides two important functions for the widget loader: ping and logout.
The `ping` function resets the session timer, allowing you to keep the session open as long as needed. The default timeout period is 900 seconds, and ping can be used anywhere in that period to restart the timer. A custom timeout period can be set by contacting MX, but MX recommends using the ping method rather than setting a longer timeout.
```html theme={null}
```
The `logout` function ends the session and redirects to the session timeout URL defined in your client profile. If no URL is defined, there is no redirect.
Contact MX if you wish to set a specific session timeout URL.
### Loading Multiple Widgets
To load multiple widgets on a single page:
1. Define multiple placeholder elements, each with a unique CSS `id`.
2. In your JavaScript, create an instance of `MoneyDesktopWidgetLoader` for each widget.
3. Connect each loader instance to a placeholder element by setting the `id` property value as the CSS `id`.
After the page has loaded, all widgets will load in their respective elements.
Here’s an example of loading 3 separate widgets onto a single page.
```html Example theme={null}
My Web Page
```
### Loading Widgets at Different Times
By default, widgets load automatically once the web page has loaded. If you'd like to load your widgets manually you can use the autoload option by setting autoload to false when instantiating `MoneyDesktopWidgetLoader`.
When you're ready to load a widget, call the load method on the instance of `MoneyDesktopWidgetLoader` with the URL.
Here’s an example of loading the Accounts Widget on page load, then loading the Transactions Widget when a button is selected.
```html Example theme={null}
My Web Page
```