Nahtlose Web-to-Game-Integration

So funktioniert's

Die nahtlose Web-to-Game-Integration ermöglicht es Ihnen, zu konfigurieren, welche Daten von Ihrer Website an das Spiel in den URL-Parametern gesendet werden. Sie können den Autorisierungstoken eines Nutzers, Marketingkampagnendaten oder andere Informationen übertragen.

Ablauf für den Nutzer

Bei der Implementierung einer nahtlosen Web-to-Game-Integration gibt es folgende Nutzerszenarien:

• Klick auf einen Link zum Download des Startprogramm-Installers von der Website.
• Klick auf einen Link auf der Website, um zum Startprogramm zu gelangen.
• Starten des Spiels aus dem Startprogramm heraus.

Klickt ein Nutzer auf einen Link, um das Startprogramm von der Website herunterzuladen, sieht der Ablauf wie folgt aus:

1. Der Nutzer öffnet die Website.
2. Der Nutzer klickt auf den Download-Link.
3. Der Download des Startprogramm-Installers beginnt, der Download-Link enthält zudem ein Einmalpasswort.
4. Der Nutzer installiert das Startprogramm.
5. Das Startprogramm empfängt den Wert des Parameters common_payload aus dem Einmalpasswort.
6. Der Nutzer klickt im Startprogramm auf Spielen.
7. Das Startprogramm prüft, ob der Parameter common_payload vorhanden und gültig ist:
   • Ist das Ergebnis der Prüfung positiv, startet das Startprogramm das Spiel mit den Argumenten aus dem Parameter common_payload.
   • Bei einem negativen Prüfergebnis:
     • Wenn im Kundenportal unter “Name der ausführbaren Datei” eine Website-URL angegeben ist, leitet das Startprogramm den Nutzer zu dieser Adresse weiter.
     • Ist keine URL angegeben, startet das Startprogramm das Spiel ohne das Argument common_payload.

Klickt ein Nutzer auf der Website auf einen Link, der zum Startprogramm weiterleitet, und das Startprogramm bereits installiert ist, sieht der Ablauf wie folgt aus:

1. Der Nutzer öffnet die Website.
2. Der Nutzer klickt auf den Link.
3. Das Startprogramm speichert die in der URL enthaltenen Werte der Parameter payload, common_payload und expires_jn.
4. Der Nutzer klickt im Startprogramm auf Spielen.
5. Das Startprogramm prüft, ob die Parameter payload und common_payload vorhanden und gültig sind:
   • Ist das Ergebnis der Prüfung positiv, startet das Startprogramm das Spiel mit den Argumenten aus den Parametern payload und common_payload.
   • Bei einem negativen Prüfergebnis:
     • Wenn im Kundenportal unter “Name der ausführbaren Datei” eine Website-URL angegeben ist, leitet das Startprogramm den Nutzer zu dieser Adresse weiter.
     • Ist keine URL angegeben, startet das Startprogramm das Spiel ohne die Argumente payload und common_payload.

Startet ein Nutzer das Spiel vom Startprogramm aus, sieht der Ablauf wie folgt aus:

1. Der Nutzer öffnet das Startprogramm.
2. Der Nutzer klickt im Startprogramm auf Spielen.
3. Das Startprogramm prüft, ob die Parameter payload und common_payload vorhanden und gültig sind:
   • Ist das Ergebnis der Prüfung positiv, startet das Startprogramm das Spiel mit den Argumenten aus den Parametern payload und common_payload.
   • Bei einem negativen Prüfergebnis:
     • Wenn im Kundenportal unter “Name der ausführbaren Datei” eine Website-URL angegeben ist, leitet das Startprogramm den Nutzer zu dieser Adresse weiter.
     • Ist keine URL angegeben, startet das Startprogramm das Spiel ohne die Argumente payload und common_payload.

Wie komme ich dazu

So richten Sie die nahtlose Web-to-Game-Integration ein:

1. Konfigurieren Sie die Einstellungen im Kundenportal.
2. Fügen Sie der Website einen Link hinzu.
3. Implementieren Sie die Verarbeitung der im Payload-Parameter empfangenen Daten aufseiten des Spiels.

Einstellungen im Kundenportal konfigurieren

1. Öffnen Sie Ihr Projekt im Kundenportal.
2. Klicken Sie in der Seitenleiste auf Launcher.
3. Wählen Sie im Dashboard das gewünschte Startprogramm aus, und klicken Sie auf Startprogramm bearbeiten.
4. Scrollen Sie zum Abschnitt Spiele, und klicken Sie rechts neben dem gewünschten Spiel auf Einrichten.
5. Wählen Sie die Option Builds.
6. Wechseln Sie zur Registerkarte Ausführbare Dateien.
7. Geben Sie für jedes Betriebssystem im Feld Name der ausführbaren Datei das Argument --x_payload_url an. Übermitteln Sie als Argumentwert die URL der Website, auf der sich der Link bzw. die Schaltfläche befindet. Der Wert sollte mit Base64 kodiert sein.

Lautet beispielsweise der Name der ausführbaren Datei game.exe und die URL der Spiel-Website http://example.com/start_play, dann geben Sie game.exe –x_payload_url aHR0cDovL2V4YW1wbGUuY29tL3N0YXJ0X3BsYXk= im Feld Name der ausführbaren Datei ein.

Website einen Link hinzufügen

Platzieren Sie einen Link oder eine Schaltfläche auf Ihrer Website, über den/die die URL im Format xl-<launcher-id>://game/<game-id>?payload=<payload>&common_payload=<common_payload>&expires_in=<expires_in> geöffnet wird, wobei:

• <launcher-id> und <game-id> die Kennungen des Startprogramms und des Spiels sind. Beide finden Sie in der URL im Kundenportal: https://publisher.xsolla.com/<merchant-id>/projects/<project-id>/new-launcher/<launcher-id>/game/<game-id>.
• <payload> die an das Spiel zu übermittelnden Daten sind.
• <common_payload> die an das Startprogramm zu übermittelnden Nutzerdaten sind, die für alle Spiele gleich sind.
• <expires_in> die Verfallszeit (angegeben in Millisekunden in Unixzeit) der in den Parametern payload und common_payload übermittelten Daten ist.

function getAuthToken() {
    return 'YOUR DATA HERE';
}

function getDeeplink(launcherID, gameID) {
    const encodedPayload = btoa(getAuthToken());
    const expiresIn = new Date();
    expiresIn.setHours(expiresIn.getHours() + 1); // Payload data will be fresh for 1 hour
 return `xl-${launcherID}://game/${gameID}?payload=${encodedPayload}&expires_in=${expiresIn.getTime()}`;
}

// Put that `href` to button or link address
const href = getDeeplink(123, 4567);

Integration aufseiten des Spiels

Das Startprogramm übermittelt die im Parameter payload empfangenen Daten als Wert des Befehlszeilenarguments –xsolla-payload, wie im folgenden Beispiel gezeigt. Zudem prüft es, ob die im Parameter common_payload übermittelten Daten vorhanden und gültig sind und übermittelt sie als Wert des Befehlszeilenarguments –xsolla-common-payload, wie im folgenden Beispiel gezeigt.

Beispiel für den Start eines Spiels, wenn die Daten mit Base64 verschlüsselt sind:

game.exe ---xsolla-payload <payload> --xsolla-common-payload <common_payload> WU9VUiBEQVRBIEhFUkU=