Explore Metaframe methods and events

window.metaframe object

Once the script is loaded, the metaframe object is available in the global window object of your application. The metaframe object contains a list of methods needed to manage the Metaframe in your web application.

window.metaframe.create method

Method signature:

Copy
Full screen
Small screen
 1window.metaframe.create: (parameters: {
 2 loginProjectId: string,
 3 merchantId?: number,
 4 projectId?: number,
 5 orbsApiHostId?: string,
 6 isMobile?: boolean,
 7 isCollapsed?: boolean,
 8 layoutSettings?: {
 9     desktop: {
10       widgetMarginTop?: number,
11     },
12     mobile: {
13       widgetMarginTop?: number,
14     },
15   },
16}) => void;

Initializes Metaframe in your web application.

ParameterTypeDescription
parameters
objectObject with parameters for launching Metaframe.
parameters.loginProjectId
stringLogin ID. To get it, open Publisher Account, and go to the Players > Login > Dashboard > your Login project section. Required.
parameters.merchantId
stringMerchant ID. You can find this parameter in your Publisher Account:
  • in the Company settings > Company section.
  • in the URL in the browser address bar on any Publisher Account page. The URL has the following format: https:​//publisher.xsolla.com/<merchantId>/.
Required, if the Virtual currencies or Backpack function is enabled in the project settings in the Publisher Account.
parameters.projectID
stringProject ID. You can find this parameter in your Publisher Account next to the name of the project.
Required, if the Backpack function is enabled in the project settings in the Publisher Account.
parameters.orbsApiHostId
stringHost ID. To get it, contact the integration team at integration@xsolla.com or your Customer Success Manager at csm@xsolla.com and pass the project ID and merchant ID.
Required, if the Virtual currencies function is enabled in the project settings in the Publisher Account.
parameters.isMobile
booleanWhether Metaframe uses mobile layout by default.
parameters.isCollapsed
booleanWhether the widget is displayed collapsed (minimized) by default. The default value is true.
parameters.layoutSettings
objectObject with parameters for customizing the widget layout.
parameters.layoutSettings.desktop
objectObject with parameters for customizing the layout of the desktop version of the widget. Required.
parameters.layoutSettings.desktop.widgetMarginTop
numberTop margin for the Metaframe widget relative to the viewport (in px). The default value is 16.
parameters.parameters.layoutSettings.mobile
objectObject with parameters for customizing the layout of the mobile version of the widget. Required.
parameters.layoutSettings.mobile.widgetMarginTop
numberTop margin for the Metaframe widget relative to the viewport (in px). The default value is 72.
Note
The widget location in the mobile version can be configured in the Publisher Account. Detailed information is provided in the Setting up mobile version section.

window.metaframe.setIsMobile method

Method signature:

Copy
Full screen
Small screen
1window.metaframe.setIsMobile(isMobile: boolean)

Switches Metaframe from desktop to mobile version or vice versa.

ParameterTypeDescription
isMobile
booleanWhether to switch Metaframe to the mobile version. If set to true, Metaframe switches to the mobile version. If set to false, Metaframe switches to the desktop version.
Note
The widget location in the mobile version can be configured in the Publisher Account. Detailed information is provided in the Setting up mobile version section.

window.metaframe.partnerActions object

The object contains methods to trigger actions in the Metaframe.

Before using the methods of this object, you must ensure that the Metaframe is fully loaded. To do this, subscribe to the Metaframe load event. If the event has been processed, the object’s methods are available.

Example of setting a listener to the Metaframe load event:

Copy
Full screen
Small screen
1window.addEventListener("@metaframe-partner-events:app-loaded", () => {
2
3 //Here you can use partner actions
4
5});

window.metaframe.partnerActions.openBackpackItemPage method

Method signature:

Copy
Full screen
Small screen
1openBackpackItemPage: (itemId: string) => void;

Opens the page for the specified item in the Backpack section.

For the method to work correctly, the following conditions must be met:

  • The Backpack function is enabled in the Publisher Account.
  • The user is authenticated in to Metaframe.

ParameterTypeDescription
itemId
stringInternal ID of the item that is passed when calling the API method to create the item.

window.metaframe.partnerActions.openLogin method

Method signature:

Copy
Full screen
Small screen
1openLogin: () => void;

Opens the user authorization form. If the user is already authorized, an error is displayed in the browser console.

window.metaframe.partnerActions.openProfile method

Method signature:

Copy
Full screen
Small screen
1openProfile: () => void;

Opens the Profile section for the current user. If the user is not authorized, an error is displayed in the browser console.

window.metaframe.partnerActions.openWallet methods

Method signature:

Copy
Full screen
Small screen
1openWallet: () => void;

Opens the Wallet section for the current user. If the user is not authorized, an error is displayed in the browser console.

Note
For the method to work correctly, the Wallet section must be configured in the widget.

window.metaframe.partnerActions.openBackpack method

Method signature:

Copy
Full screen
Small screen
1openBackpack: () => void;

Opens the Backpack section for the current user. If the user is not authorized, an error is displayed in the browser console.

Note
For the method to work correctly, the following conditions must be met:
  • The Backpack function is enabled in the Publisher Account.
  • The user is authenticated in to Metaframe.

window.metaframe.partnerActions.openCustomMiniApp method

Method signature:

Copy
Full screen
Small screen
1openCustomMiniApp: (params: {miniAppName: string}) => void;

Opens the specified custom section with the Iframe type if one of the following conditions is met:

  • If the Show this app before user login toggle in the settings of the specified custom section is active, and the current user is not authorized.
  • If the Show this app after user login toggle in the settings of the specified user section is active, and the current user is authorized.

If the conditions are not met, an error is displayed in the browser console.

Note
For the method to work correctly, a custom section with the Iframe type must be configured in the widget. Before calling the method, verify that the Metaframe widget has successfully loaded the specified custom section. To do this, track events of custom sections loading.
ParameterTypeDescription
params
objectObject with parameters.
params.miniAppName
stringApp name specified in the settings of the custom section with the Iframe type. Required.

window.metaframe.partnerActions.pushNotification methods

Method signature:

Copy
Full screen
Small screen
1pushNotification: (params: {
2  type: string; // use “success”, “warning”, “error” or “info”
3  text: string;
4  button?: {
5    text: string;
6    onClick: () => void;
7  };
8  durationInMs?: number;
9}) => void;

Pushes a new notification to the notification stack.

ParameterTypeDescription
params
objectObject with parameters.
paramps.type
stringNotification type. Possible values: “success”, “warning”, “error”, “info”. Required.
paramps.text
stringNotification text. Required.
params.button.text
stringButton copy. Required.
params.button.onClick
() => voidFunction that is called when the button is clicked. Required.
params.durationInMs
numberDuration of the notification display on the screen in milliseconds.

window.metaframe.partnerActions.setIsCustomMiniAppVisible method

Method signature:

Copy
Full screen
Small screen
1setIsCustomMiniAppVisible: (params: {
2  miniAppName: string;
3  isVisible: boolean;
4}) => void;

Shows or hides the specified custom section.

Note
For the method to work correctly, a custom section must be configured in the widget. Before calling the method, verify that the Metaframe widget has successfully loaded the specified custom section. To do this, track events of custom sections loading.
ParameterTypeDescription
params
objectObject with parameters.
params.miniAppName
stringApp name specified in the settings of the custom section. Required.
params.isVisible
booleanWhether to display the specified custom section in the widget. Required.

Widget events

You can subscribe to the following Metaframe events:

ParameterType
@metaframe-partner-events:app-loadedThe event is triggered when the Metaframe is successfully loaded after the window.metaframe.create method is called.
@metaframe-partner-events:not-authorized-mini-apps-loadedThe event is triggered when the Metaframe successfully loads custom sections in the settings of which the Show this app before user login toggle is active.
@metaframe-partner-events:authorized-mini-apps-loadedThe event is triggered when the Metaframe successfully loads all configured widget sections, including custom sections in the settings of which the Show this app after user login toggle is active.
@metaframe-partner-events:login-successfulThis event is triggered when the user successfully logs into the Metaframe. It contains a detail object with the user’s authorization token.
@metaframe-partner-events:logout-successfulThe event is triggered when a user successfully logs out of the system.
@metaframe-partner-events:mini-app-menu-button-clicked:<YOUR_MINI_APP_NAME>The event is triggered when a user clicks on Metaframe custom section.
@metaframe:custom-action:<ACTION_ID>The event is triggered when a user selects a custom section of type Action in the Metaframe. For more information, see Tracking custom sections’ events.

Tracking custom sections’ events

You can add to Metaframe a custom section with the Action type. This section appears as a button that, performs an action when clicked, such as opening a website.

To track the event of clicking a custom section, you need to subscribe to the @metaframe:custom-action:<ACTION_ID> event, where <ACTION_ID> is the action ID generated in Publisher Account when setting up the custom section.

Example of setting a listener for a custom section click event:

Copy
Full screen
Small screen
1document.addEventListener("@metaframe:custom-action:00000000-0000-0000-0000-000000000000", () => {
2
3 // Your code here...
4
5})
Was this article helpful?
Thank you!
Is there anything we can improve? Message
We’re sorry to hear that
Please explain why this article wasn’t helpful to you. Message
Thank you for your feedback!
We’ll review your message and use it to help us improve your experience.
Last updated: September 19, 2025

Found a typo or other text error? Select the text and press Ctrl+Enter.

Report a problem
We always review our content. Your feedback helps us improve it.
Provide an email so we can follow up
Thank you for your feedback!
We couldn't send your feedback
Try again later or contact us at doc_feedback@xsolla.com.