Découvrir les méthodes et événements Metaframe

Objet window.metaframe

Une fois le script chargé, l’objet metaframe devient accessible dans l’objet global window de votre application. Cet objet metaframe contient une série de méthodes essentielles pour gérer Metaframe dans votre application Web.

Méthode window.metaframe.create

Signature de la méthode :

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;

Initialise Metaframe dans votre application Web.

ParamètreTypeDescription
parameters
objectObjet contenant les paramètres de lancement de Metaframe.
parameters.loginProjectId
stringID de Login. Pour l’obtenir, ouvrez le Compte éditeur et accédez à la section Players > Login > Dashboard > votre projet de Login. Obligatoire.
parameters.merchantId
stringID de commerçant. Ce paramètre se trouve dans le Compte éditeur :
  • dans la section Company settings > Company ;
  • dans l’URL dans la barre d’adresse du navigateur sur n’importe quelle page de Compte éditeur. L’URL est au format suivant : https:​//publisher.xsolla.com/<merchantId>/.
Obligatoire, si la fonction Virtual currencies ou Backpack est activée dans les paramètres du projet dans le Compte éditeur.
parameters.projectID
stringID de projet. Ce paramètre se trouve dans le Compte éditeur à côté du nom du projet.
Obligatoire, si la fonction Backpack est activée dans les paramètres du projet dans le Compte éditeur.
parameters.orbsApiHostId
stringID d’hôte. Pour l’obtenir, contactez l’équipe d’intégration à integration@xsolla.com ou votre responsable de la réussite client à csm@xsolla.com, et communiquez l’ID du projet ou l’ID du commerçant.
Obligatoire, si la fonction Virtual currencies est activée dans les paramètres du projet dans le Compte éditeur.
parameters.isMobile
booleanDétermine l’utilisation par Metaframe de la disposition mobile par défaut.
parameters.isCollapsed
booleanDétermine si le widget s’affiche en mode réduit (minimisé) par défaut. La valeur par défaut est true.
parameters.layoutSettings
objectObjet contenant des paramètres permettant de personnaliser la disposition du widget.
parameters.layoutSettings.desktop
objectObjet contenant les paramètres permettant de personnaliser la disposition de la version bureau du widget. Obligatoire.
parameters.layoutSettings.desktop.widgetMarginTop
numberMarge supérieure du widget Metaframe par rapport à la fenêtre (en px). La valeur par défaut est 16.
parameters.parameters.layoutSettings.mobile
objectObjet contenant les paramètres permettant de personnaliser la disposition de la version mobile du widget. Obligatoire.
parameters.layoutSettings.mobile.widgetMarginTop
numberMarge supérieure du widget Metaframe par rapport à la fenêtre (en px). La valeur par défaut est 72.
Note
L’emplacement du widget dans la version mobile peut être configuré dans le Compte éditeur. Pour des informations détaillées, consultez la section Configuration de la version mobile.

Méthode window.metaframe.setIsMobile

Signature de la méthode :

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

Bascule Metaframe de la version bureau à la version mobile ou vice versa.

ParamètreTypeDescription
isMobile
booleanDétermine si Metaframe doit utiliser la version mobile ou bureau. Si la valeur est true, Metaframe bascule vers la version mobile. Si la valeur est false, il passe à la version bureau.
Note
L’emplacement du widget dans la version mobile peut être configuré dans le Compte éditeur. Pour des informations détaillées, consultez la section Configuration de la version mobile.

Objet window.metaframe.partnerActions

L’objet contient des méthodes permettant de déclencher des actions dans Metaframe.

Avant d’utiliser les méthodes de cet objet, vérifiez que Metaframe est entièrement chargé. Pour cela, souscrivez à l’événement de chargement de Metaframe. Une fois l’événement traité, les méthodes de l’objet deviennent disponibles.

Exemple d’implémentation d’un écouteur pour l’événement de chargement de Metaframe :

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

Méthode window.metaframe.partnerActions.openBackpackItemPage

Signature de la méthode :

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

Ouvre la page de l’objet spécifié dans la section Backpack.

Pour que la méthode fonctionne correctement, les conditions suivantes doivent être remplies :

  • La fonction Backpack est activée dans le Compte éditeur.
  • L’utilisateur est authentifié dans Metaframe.

ParamètreTypeDescription
itemId
stringID interne de l’objet passé lors de l’appel à la méthode API pour créer l’objet.

Méthode window.metaframe.partnerActions.openLogin

Signature de la méthode :

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

Ouvre le formulaire d’autorisation de l’utilisateur. Si l’utilisateur est déjà autorisé, une erreur s’affiche dans la console du navigateur.

Méthode window.metaframe.partnerActions.openProfile

Signature de la méthode :

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

Ouvre la section Profile pour l’utilisateur actuel. Si l’utilisateur n’est pas autorisé, une erreur s’affiche dans la console du navigateur.

Méthodes window.metaframe.partnerActions.openWallet

Signature de la méthode :

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

Ouvre la section Wallet pour l’utilisateur actuel. Si l’utilisateur n’est pas autorisé, une erreur s’affiche dans la console du navigateur.

Note
Pour que la méthode fonctionne correctement, la section Wallet doit être configurée dans le widget.

Méthode window.metaframe.partnerActions.openBackpack

Signature de la méthode :

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

Ouvre la section Backpack pour l’utilisateur actuel. Si l’utilisateur n’est pas autorisé, une erreur s’affiche dans la console du navigateur.

Note
Pour que la méthode fonctionne correctement, les conditions suivantes doivent être remplies :
  • La fonction Backpack est activée dans le Compte éditeur.
  • L’utilisateur est authentifié dans Metaframe.

Méthode window.metaframe.partnerActions.openCustomMiniApp

Signature de la méthode :

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

Ouvre la section personnalisée spécifiée avec le type Iframe si l’une des conditions suivantes est remplie :

  • Si la bascule Show this app before user login est activée dans les paramètres de la section personnalisée, et l’utilisateur actuel n’est pas connecté ;
  • Si la basculeShow this app after user login est activée dans les paramètres de la section personnalisée, et l’utilisateur actuel est connecté.

Si les conditions ne sont pas remplies, une erreur s’affiche dans la console du navigateur.

Note
Pour que la méthode fonctionne correctement, une section personnalisée avec le type Iframe doit être configurée dans le widget. Avant d’appeler la méthode, vérifiez que le widget Metaframe a bien chargé la section personnalisée spécifiée. Pour ce faire, suivez les événements de chargement des sections personnalisées.
ParamètreTypeDescription
params
objectObjet contenant des paramètres.
params.miniAppName
stringNom de l’application spécifié dans les paramètres de la section personnalisée avec le type Iframe. Obligatoire.

Méthodes window.metaframe.partnerActions.pushNotification

Signature de la méthode :

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;

Envoie une nouvelle notification dans la pile des notifications.

ParamètreTypeDescription
params
objectObjet contenant des paramètres.
paramps.type
stringType de notification. Valeurs possibles : “success”, “warning”, “error”, “info”. Obligatoire.
paramps.text
stringTexte de la notification. Obligatoire.
params.button.text
stringTexte du bouton. Obligatoire.
params.button.onClick
() => voidFonction appelée après un clic sur le bouton. Obligatoire.
params.durationInMs
numberDurée de l’affichage de la notification à l’écran en millisecondes.

Méthode window.metaframe.partnerActions.setIsCustomMiniAppVisible

Signature de la méthode :

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

Affiche ou masque la section personnalisée spécifiée.

Note
Pour que la méthode fonctionne correctement, une section personnalisée doit être configurée dans le widget. Avant d’appeler la méthode, vérifiez que le widget Metaframe a bien chargé la section personnalisée spécifiée. Pour ce faire, suivez les événements de chargement des sections personnalisées.
ParamètreTypeDescription
params
objectObjet contenant des paramètres.
params.miniAppName
stringNom de l’application spécifié dans les paramètres de la section personnalisée. Obligatoire.
params.isVisible
booleanDétermine l’affichage de la section personnalisée spécifiée dans le widget. Obligatoire.

Événements du widget

Vous pouvez vous abonner aux événements Metaframe suivants :

ParamètreType
@metaframe-partner-events:app-loadedL’événement se déclenche lorsque Metaframe se charge avec succès, après l’appel à la méthode window.metaframe.create.
@metaframe-partner-events:not-authorized-mini-apps-loadedL’événement se déclenche lorsque Metaframe charge avec succès les sections personnalisées dans les paramètres où la bascule Show this app before user login est activée.
@metaframe-partner-events:authorized-mini-apps-loadedL’événement se déclenche lorsque Metaframe charge avec succès toutes les sections configurées du widget, y compris celles personnalisées dans les paramètres où la bascule Show this app after user login est activée.
@metaframe-partner-events:login-successfulCet événement se déclenche lorsque l’utilisateur se connecte avec succès à Metaframe. Il inclut un objet detail contenant le jeton d’autorisation de l’utilisateur.
@metaframe-partner-events:logout-successfulL’événement se déclenche lorsque l’utilisateur se déconnecte avec succès du système.
@metaframe-partner-events:mini-app-menu-button-clicked:<YOUR_MINI_APP_NAME>L’événement se déclenche lorsque l’utilisateur clique sur la section personnalisée de Metaframe.
@metaframe:custom-action:<ACTION_ID>L’événement se déclenche lorsque l’utilisateur sélectionne une section personnalisée de type Action dans Metaframe. Pour plus d’informations, voir Suivi des événements des sections personnalisées.

Suivi des événements des sections personnalisées

Vous pouvez ajouter une section personnalisée de type Action au Metaframe. Cette section apparaît sous forme de bouton et exécute une action, comme ouvrir un site Web, lorsque l’utilisateur clique dessus.

Pour suivre l’événement du clic sur une section personnalisée, vous devez vous abonner à l’événement @metaframe:custom-action:<ACTION_ID>, où <ACTION_ID> est l’ID de l’action généré dans le Compte éditeur lors de la configuration de la section personnalisée.

Exemple configuration d’un écouteur pour un événement de clic de section personnalisé :

Copy
Full screen
Small screen
1document.addEventListener("@metaframe:custom-action:00000000-0000-0000-0000-000000000000", () => {
2
3 // Your code here...
4
5})
Cet article vous a été utile ?
Merci !
Que pouvons-nous améliorer ? Message
Nous sommes désolés de l'apprendre
Dites-nous pourquoi vous n'avez pas trouvé cet article utile. Message
Merci pour votre commentaire !
Nous examinerons votre message et l'utiliserons pour améliorer votre expérience.
Dernière mise à jour: 19 Septembre 2025

Faute de frappe ou autre erreur dans le texte ? Sélectionnez le texte concerné et appuyez sur Ctrl+Entrée.

Signaler un problème
Nous améliorons continuellement notre contenu grâce à vos commentaires.
Indiquez votre adresse e-mail pour un suivi
Merci pour votre commentaire !
Impossible d'envoyer votre commentaire
Réessayez plus tard ou contactez-nous à doc_feedback@xsolla.com.