Metaframe-Methoden und Ereignisse

window.metaframe-Objekt

Sobald das Skript geladen wurde, ist das metaframe-Objekt im globalen window-Objekt Ihrer Anwendung verfügbar. Das Metaframe-Objekt enthält eine Liste von Methoden, die für die Verwaltung von Metaframe in Ihrer Web-Anwendung erforderlich sind.

Methode window.metaframe.create

Signatur der Methode:

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;

Initialisiert Metaframe in Ihrer Webanwendung.

ParameterTypBeschreibung
parameters
objectObjekt mit den Parametern für den Metaframe-Start.
parameters.loginProjectId
stringLogin-ID. Diese finden Sie im Kundenportal unter Spieler > Login > Dashboard > Ihr Login-Projekt. Erforderlich.
parameters.merchantId
stringHändler-ID. Diesen Parameter finden Sie im Kundenportal:
  • unter Firmeneinstellungen > Firma,
  • in der Adresszeile des Browsers auf einer beliebigen Seite im Kundenportal. Die URL weist das folgende Format auf: https:​//publisher.xsolla.com/<merchantId>/.
Erforderlich, wenn die Funktion virtuelle Währungen oder Rucksack in den Projekteinstellungen im Kundenportal aktiviert ist.
parameters.projectID
stringProjekt-ID. Dieser Parameter wird im Kundenportal neben dem Projektnamen angezeigt.
Erforderlich, wenn die Funktion Rucksack in den Projekteinstellungen im Kundenportal aktiviert ist.
parameters.orbsApiHostId
stringHost-ID. Wenden Sie sich dafür an das Integrationsteam integration@xsolla.com oder an Ihren Customer Success Manager csm@xsolla.com, und teilen Sie ihm die Projekt-ID und die Händler-ID mit.
Erforderlich, wenn die Funktion virtuelle Währungen in den Projekteinstellungen im Kundenportal aktiviert ist.
parameters.isMobile
booleanOb Metaframe standardmäßig das mobile Layout verwendet.
parameters.isCollapsed
booleanOb das Widget standardmäßig eingeklappt (minimiert) angezeigt wird. Der Standardwert ist true.
parameters.layoutSettings
objectObjekt mit den Parametern zur Anpassung des Widget-Layouts.
parameters.layoutSettings.desktop
objectObjekt mit den Parametern zur Anpassung des Layouts der Desktop-Version des Widgets. Erforderlich.
parameters.layoutSettings.desktop.widgetMarginTop
numberOberer Rand für das Metaframe-Widget relativ zum Viewport (in px). Der Standardwert ist 16.
parameters.parameters.layoutSettings.mobile
objectObjekt mit den Parametern zur Anpassung des Layouts der mobilgeräteoptimierten Widget-Version. Erforderlich.
parameters.layoutSettings.mobile.widgetMarginTop
numberOberer Rand für das Metaframe-Widget relativ zum Viewport (in px). Der Standardwert ist 72.
Hinweis
Die Position des Widgets in der mobilen Version kann im Kundenportal konfiguriert werden. Einzelheiten dazu findet man im Abschnitt Mobile Version einrichten.

Methode window.metaframe.setIsMobile

Signatur der Methode:

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

Wechselt Metaframe von der Desktop- zur mobilen Version und umgekehrt.

ParameterTypBeschreibung
isMobile
booleanOb Metaframe auf die mobile Version umgestellt werden soll. Bei true schaltet Metaframe auf die mobile Version um. Bei false schaltet Metaframe auf die Desktop-Version um.
Hinweis
Die Position des Widgets in der mobilen Version kann im Kundenportal konfiguriert werden. Einzelheiten dazu findet man im Abschnitt Mobile Version einrichten.

window.metaframe.partnerActions-Objekt

Das Objekt enthält Methoden, die Aktionen im Metaframe auslösen.

Bevor Sie Methoden an diesem Objekt anwenden, müssen Sie sicherstellen, dass Metaframe vollständig geladen wurde. Abonnieren Sie dafür das Metaframe Ladeereignis. Wenn das Ereignis verarbeitet wurde, sind die Methoden des Objekts verfügbar.

Beispiel für das Einrichten eines Listeners für das Metaframe-Ladeereignis:

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

Methode window.metaframe.partnerActions.openBackpackItemPage

Signatur der Methode:

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

Öffnet die Seite für den angegebenen Artikel im Abschnitt Backpack

Damit die Methode korrekt funktioniert, müssen folgende Bedingungen erfüllt sein:

  • Die Funktion Rucksack ist im Kundenportal aktiviert.
  • Der Benutzer ist bei Metaframe authentifiziert.

ParameterTypBeschreibung
itemId
stringInterne ID des Elements, das während des Aufrufs der API Methode Element erstellen übertragen wird.

Methode window.metaframe.partnerActions.openLogin

Signatur der Methode:

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

Öffnet die Maske für die Nutzerautorisierung. Wenn der Nutzer bereits autorisiert ist, wird in der Browserkonsole ein Fehler angezeigt.

Methode window.metaframe.partnerActions.openProfile

Signatur der Methode:

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

Öffnet den Abschnitt Profile für den aktuellen Nutzer. Wenn der Nutzer nicht autorisiert ist, wird in der Browserkonsole ein Fehler angezeigt.

Methoden window.metaframe.partnerActions.openWallet

Signatur der Methode:

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

Öffnet den Abschnitt Wallet für den aktuellen Nutzer. Wenn der Nutzer nicht autorisiert ist, wird in der Browserkonsole ein Fehler angezeigt.

Hinweis
Damit die Methode ordnungsgemäß funktioniert, muss in dem Widget der Abschnitt Wallet konfiguriert sein.

Methode window.metaframe.partnerActions.openBackpack

Signatur der Methode:

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

Öffnet den Abschnitt Backpack für den aktuellen Nutzer. Wenn der Nutzer nicht autorisiert ist, wird in der Browserkonsole ein Fehler angezeigt.

Hinweis
Damit die Methode korrekt funktioniert, müssen folgende Bedingungen erfüllt sein:
  • Die Funktion Rucksack ist im Kundenportal aktiviert.
  • Der Benutzer ist bei Metaframe authentifiziert.

Methode window.metaframe.partnerActions.openCustomMiniApp

Signatur der Methode:

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

Öffnet den angegebenen benutzerdefinierten Abschnitt vom Typ Iframe, wenn eine der folgenden Bedingungen erfüllt ist:

  • Wenn die Option Diese App vor der Nutzeranmeldung anzeigen in den Einstellungen des angegebenen benutzerdefinierten Abschnitts aktiviert ist und der aktuelle Nutzer nicht autorisiert ist.
  • Wenn die Option Diese App nach der Nutzeranmeldung anzeigen in den Einstellungen des angegebenen benutzerdefinierten Abschnitts aktiviert ist und der aktuelle Nutzer autorisiert ist.

Wenn keine der Bedingungen erfüllt ist, wird in der Browserkonsole ein Fehler angezeigt.

Hinweis
Damit die Methode ordnungsgemäß funktioniert, muss in dem Widget ein benutzerdefinierter Abschnitt vom Typ “Iframe” konfiguriert sein. Bevor Sie die Methode aufrufen, müssen Sie prüfen, ob das Metaframe-Widget den angegebenen benutzerdefinierten Abschnitt erfolgreich geladen hat. Tracken Sie dazu die Ladeereignisse der benutzerdefinierten Abschnitte.
ParameterTypBeschreibung
params
objectObjekt mit Parametern.
params.miniAppName
stringDer App-Name, der in den Einstellungen des benutzerdefinierten Abschnitts vom Typ Iframe angegeben ist. Erforderlich.

Methoden window.metaframe.partnerActions.pushNotification

Signatur der Methode:

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;

Pusht eine neue Benachrichtigung in den Benachrichtigungsstapel.

ParameterTypBeschreibung
params
objectObjekt mit Parametern.
paramps.type
stringBenachrichtigungstyp. Mögliche Werte sind: “success”, “warning”, “error”, “info”. Erforderlich.
paramps.text
stringBenachrichtigungstext. Erforderlich.
params.button.text
stringSchaltflächentext. Erforderlich.
params.button.onClick
() => voidFunktion, die beim Klick auf die Schaltfläche aufgerufen wird. Erforderlich.
params.durationInMs
numberWie lange die Benachrichtigung auf dem Bildschirm angezeigt wird (in Millisekunden).

Methode window.metaframe.partnerActions.setIsCustomMiniAppVisible

Signatur der Methode:

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

Blendet den angegebenen benutzerdefinierten Abschnitt ein oder aus.

Hinweis
Damit die Methode ordnungsgemäß funktioniert, muss in dem Widget ein benutzerdefinierter Abschnitt konfiguriert sein. Bevor Sie die Methode aufrufen, müssen Sie prüfen, ob das Metaframe-Widget den angegebenen benutzerdefinierten Abschnitt erfolgreich geladen hat. Tracken Sie dazu die Ladeereignisse der benutzerdefinierten Abschnitte.
ParameterTypBeschreibung
params
objectObjekt mit Parametern.
params.miniAppName
stringDer App-Name, der in den Einstellungen des benutzerdefinierten Abschnitts angegeben ist. Erforderlich.
params.isVisible
booleanOb der angegebene benutzerdefinierte Abschnitt im Widget angezeigt wird. Erfoderlich.

Widget-Ereignisse

Sie können folgende Metaframe-Ereignisse abonnieren:

ParameterTyp
@metaframe-partner-events:app-loadedDas Ereignis wird ausgelöst, wenn Metaframe erfolgreich, nachdem die Methode window.metaframe.create aufgerufen wurde, geladen wird.
@metaframe-partner-events:not-authorized-mini-apps-loadedDas Ereignis wird getriggert, wenn Metaframe benutzerdefinierte Abschnitte erfolgreich geladen hat, in deren Einstellungen die Option Diese App nach der Nutzeranmeldung anzeigen aktiviert ist.
@metaframe-partner-events:authorized-mini-apps-loadedDas Ereignis wird getriggert, wenn Metaframe alle konfigurierten Widget-Abschnitte erfolgreich geladen hat, einschließlich benutzerdefinierter Abschnitte, in deren Einstellungen die Option Diese App nach der Nutzeranmeldung anzeigen aktiviert ist.
@metaframe-partner-events:login-successfulDas Ereignis wird ausgelöst, wenn der Benutzer sich erfolgreich beim Metaframe anmeldet. Es enthält ein detail-Objekt mit dem Authorisierungstoken.
@metaframe-partner-events:logout-successfulDas Ereignis wird ausgelöst, wenn sich ein Benutzer erfolgreich vom System abmeldet.
@metaframe-partner-events:mini-app-menu-button-clicked:<YOUR_MINI_APP_NAME>Das Ereignis wird getriggert, wenn ein Nutzer auf einen benutzerdefinierten Metaframe-Abschnitt klickt.
@metaframe:custom-action:<ACTION_ID>Das Ereignis wird ausgelöst, wenn ein Benutzer einen beliebigen Abschnitt des Typs Action im Metaframe wählt. Weitere Informationen finden Sie unter Ereignisse beliebiger Abschnitte nachverfolgen.

Ereignisse in benutzerdefinierten Abschnitten nachverfolgen

Sie können dem Metaframe einen benutzerdefinierten Abschnitt vom Typ “Action” hinzufügen. Dieser Abschnitt erscheint als Schaltfläche, die beim Anklicken eine Aktion ausführt, z. B. eine Website öffnet.

Um das Ereignis nachzuverfolgen, bei dem ein benutzerdefinierter Abschnitt angeklickt wird, müssen Sie das Ereignis @metaframe:custom-action:<ACTION_ID> abonnieren, wobei die Aktions-ID <ACTION_ID> im Kundenportal bei der Einrichtung des benutzerdefinierten Abschnitts generiert wird.

Beispiel für das Einrichten eines Listeners für ein Klickereignis eines benutzerdefinierten Abschnitts:

Copy
Full screen
Small screen
1document.addEventListener("@metaframe:custom-action:00000000-0000-0000-0000-000000000000", () => {
2
3 // Your code here...
4
5})
War dieser Artikel hilfreich?
Vielen Dank!
Gibt es etwas, das wir verbessern können? Nachricht
Das tut uns leid
Bitte erläutern Sie, weshalb dieser Artikel nicht hilfreich ist. Nachricht
Vielen Dank für Ihr Feedback!
Wir werden Ihr Feedback aufgreifen und dazu nutzen, Ihr Erlebnis verbessern.
Letztmalig aktualisiert: 19. September 2025

Haben Sie einen Tippfehler oder einen anderen Textfehler gefunden? Wählen Sie den Text aus und drücken Sie Strg+Eingabe.

Problem melden
Wir überprüfen unsere Inhalte ständig. Ihr Feedback hilft uns, sie zu verbessern.
Geben Sie eine E-Mail-Adresse an, damit wir Sie erreichen können
Vielen Dank für Ihr Feedback!
Ihr Feedback konnte nicht gesendet werden
Versuchen Sie es später erneut oder kontaktieren Sie uns unter doc_feedback@xsolla.com.