Digital Distribution Hub

Überblick

Digital Distribution Hub ist eine Lösung, die Spieleentwickler mit Vertriebspartnern vernetzt, die ihre eigenen Plattformen oder Ökosysteme für die Distribution von Spielen, virtuellen Gegenständen, virtueller Währung und Bundles nutzen.

Vertriebspartner sind digitale Plattformen oder Ökosysteme, die Spiele und Ingame-Items vertreiben und eigene Shops haben sowie eigene Rechnungen ausstellen. Beispiele für Xsolla-Vertriebspartner:

• Super-Apps, die mehrere Dienste bündeln
• Banking-Apps
• Telekommunikations- und Internetdienstanbieter
• Automaten
• Anbieter von Cashback- und Prämienprogrammen
• digitale Marktplätze

Vorteile für Spieleentwickler:

• Vergrößert die Zielgruppe der Spiele durch die direkte Vernetzung mit schnell wachsenden Vertriebspartnern.
• Steigende Umsätze dank neuer Vertriebskanäle mit einzigartigem Nutzerkreis.
• Bessere organische Auffindbarkeit auf Plattformen Dritter durch Werbeanzeigen und Banner.

Vorteile für Vertriebspartner:

• Gesteigerte Nutzertreue durch Zugang zu noch mehr Spielinhalten. Nutzer können Spielschlüssel, virtuelle Gegenstände, virtuelle Währung und Bundles direkt über die App oder den Dienst erwerben.
• Bindung bestehender und Gewinnung neuer Nutzer durch die wachsende Beliebtheit der Gaming-Branche.
• Steigende Umsätze durch die Provision aus dem Verkauf von Spielschlüsseln, virtuellen Gegenständen und virtueller Währung der größten Publisher.

So funktioniert's

Spielschlüsselkauf: Ablauf für Benutzer

Kauf von virtuellen Gegenständen und virtueller Währung: Ablauf für Benutzer

Interaktionsablauf

1. Der Spieleentwickler erstellt ein Projekt im Kundenportal und lädt die Spielschlüssel, die virtuellen Gegenstände, die virtuelle Währung und die Bundles hoch.
2. In folgenden Fällen fordert ein Vertriebspartner Nutzerdaten an:
   • beim Verkauf von Spielen – E-Mail-Adresse des Nutzers, an die die Schlüssel und die Quittung geschickt werden sollen
   • beim Verakuf von Ingame-Items – Ingame-ID des Nutzers, der die virtuellen Gegenstände erhalten soll, und die E-Mail-Adresse des Nutzers, an die die Quittung gesendet werden soll
3. Der Nutzer gibt die folgenden Daten auf der Benutzeroberfläche des Vertriebspartners ein:
   • beim Kauf eines Spiels – E-Mail-Adresse für den Erhalt des Schlüssels und der Quittung
   • beim Kauf von Ingame-Items – Ingame-ID, um die virtuellen Gegenstände dem Inventar hinzuzufügen, und eine E-Mail-Adresse für den Erhalt der Quittung
4. Der Vertriebspartner ruft die Methode Benutzertoken erstellen auf und übermittelt die E-Mail-Adresse (erforderlich) und die Benutzer-ID (erforderlich beim Verkauf von virtuellen Gegenständen, virtueller Währung und Bundles) als Parameter.
5. Xsolla prüft, ob der Nutzer im Spiel existiert, sofern der Spieleentwickler Webhooks eingerichtet hat. Die Einrichtung von Webhooks ist für den Verkauf von virtuellen Gegenständen und virtueller Währung zwingend erforderlich, beim Verkauf von Spielschlüsseln jedoch optional.
6. Xsolla erstellt einen Token mitsamt Nutzerdaten und sendet den Token an den Vertriebspartner.
7. Der Vertriebspartner fordert einen Spielekatalog oder Ingame-Items-Katalog an.
8. Xsolla antwortet mit dem angefragten Katalog.
9. Der Vertriebspartner erhält den Katalog und zeigt ihn dem Nutzer an.
10. Der Nutzer tätigt einen Kauf. Der Vertriebspartner stellt den Warenkorb zusammen.
11. Der Vertriebspartner sendet den Warenkorb, um eine Bestellung anzulegen.
12. Xsolla antwortet mit der Bestell-ID und dem Warenkorbpreis inklusive Rabatten und Steuern.
13. Der Vertriebspartner zeigt dem Nutzer die Warenkorbsumme an.
14. Fährt der Nutzer mit der Zahlung fort, belastet der Vertriebspartner das Guthaben des Nutzers und leitet ihn zur Zahlungsstatusseite weiter.
15. Der Vertriebspartner benachrichtigt Xsolla, dass die Bestellung bezahlt wurde und sendet die Zahlungsdaten.
16. Xsolla benachrichtigt den Spieleentwickler über den Kauf.
17. Der Käufer des Spiels erhält eine E-Mail mit den Kaufdetails und kann die Spielschlüssel aktivieren. Hat der Nutzer virtuelle Gegenstände oder virtuelle Währung gekauft, werden diese seinem Inventar hinzugefügt.

Integration aufseiten des Spieleentwicklers

So verknüpfen Sie den Digital Distribution Hub

1. Verknüpfen Sie Online-Shop im Kundenportal, und laden Sie Folgendes herunter:
   • Spielschlüssel oder Spielschlüssel-Bundles, sofern Sie Spielschlüssel verkaufen;
   • virtuelle Gegenstände, virtuelle Währung oder Bundles, sofern Sie Ingame-Items verkaufen.
2. Richten Sie Webhooks ein.
3. Wenden Sie sich an Ihren Customer Success Manager oder senden Sie eine E-Mail an csm@xsolla.com, um Digital Distribution Hub für Ihr Projekt zu aktivieren.

So richten Sie Webhooks ein

Webhooks müssen eingerichtet sein:

• um den Nutzer zu überprüfen und den Katalog anhand der Benutzer-ID im Spiel zu personalisieren;
• um den Nutzer zu überprüfen und die gekauften Ingame-Items seinem Inventar hinzuzufügen;
• um die Transaktions-ID aufseiten von Xsolla mit der Transaktions-ID im System des Spieleentwicklers zu verknüpfen;
• um zusätzliche Benutzerparameter in der Bestellung zu übermitteln;
• um Kaufbenachrichtigungen zu erhalten.

So richten Sie Webhooks ein:

1. Öffnen Sie Ihr Projekt im Kundenportal.
2. Klicken Sie in der Seitenleiste auf Projekteinstellungen, und wechseln Sie zur Registerkarte Webhooks.
3. Stellen Sie den Schalter Webhooks auf Ein.
4. Geben Sie die Webhook-URL an.
5. Daraufhin wird standardmäßig ein geheimer Schlüssel zum Signieren der Projekt-Webhooks generiert. Wenn Sie einen neuen geheimen Schlüssel generieren möchten, klicken Sie auf das Aktualisieren-Symbol.
6. Klicken Sie auf Einstellungen speichern.

Benutzervalidierung

Xsolla sendet einen Webhook für die Benutzervalidierung, um zu prüfen, ob ein Benutzer im Spiel existiert. Die Benutzervalidierung ermöglicht es Ihnen:

• dem Benutzer einen personalisierten Katalog anzuzeigen, sofern Sie Benutzerattribute in der Antwort übermitteln;
• gekaufte Gegenstände dem Inventar des Benutzers hinzuzufügen.

Um den Empfang eines Webhooks zu bestätigen, muss Ihr Server wie folgt antworten:

• HTTP-Statuscode 204 ohne Nachrichtenrumpf, wenn der Benutzer im Spiel existiert;
• HTTP-Statuscode 400 samt Problembeschreibung, sofern der angegebene Benutzer nicht gefunden oder eine ungültige Signatur übermittelt wurde.

Die vollständige Liste und der Mechanismus der Webhooks, einschließlich Beispielen, sind in der API-Referenz ausführlich beschrieben.

In der Antwort können Sie weitere Transaktionsparameter im custom_parameters-Objekt übermitteln.

{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"additionalProperties": false,
"properties": {
  "user_attributes": {
    "type": "object",
    "required": false,
    "minProperties": 1,
    "maxProperties": 100,
    "patternProperties": {
      "^[\\w-_.]{1,255}$": {
        "oneOf": [
          {
            "type": "integer"
          },
          {
            "type": "string",
            "minLength": 1,
            "maxLength": 255
          },
          {
            "type": "array",
            "items": {
              "type": "string",
              "maxLength": 255
            },
            "minItems": 1,
            "maxItems": 1000
          }
        ]
      }
    },
    "additionalProperties": false
  }
}
}

Antwortbeispiel:

{
  "user_attributes": {
    "age": 18,
    "level": 1,
    "game": "WoW",
    "is_baned": false,
    "registration_date": "2022-01-01"
  }
}

Verknüpfung der Transaktions-ID

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "notification_type": {
      "type": "string"
    },
    "order_id": {
      "type": "integer"
    },
    "project_id": {
      "type": "integer"
    },
    "user": {
      "type": "object",
      "properties": {
        "external_id": {
          "type": "string"
        },
        "email": {
          "type": "string"
        }
      }
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "item_id": {
            "type": "integer"
          },
          "sku":  {
            "type": "string"
          },
          "quantity": {
            "type": "integer"
          },
          "type": {
            "type": "string"
          }
        }
      }
    }
  }
}

Anfragebeispiel:

{
  "notification_type": "create_external_transaction",
  "order_id": 1,
  "project_id": 51336,
  "user": {
    "external_id": "user_id",
    "email": "public_email@test.com"
  },
  "items": [
    {
      "item_id": 101,
      "sku": "mithril_dagger",
      "quantity": 2,
      "type": "virtual_good"
    }
  ]
}

In der Antwort können Sie weitere Transaktionsparameter im custom_parameters-Objekt übermitteln.

Erwartete Antwort:

{
  "id": "validation_transaction_info_response.json",
 "$schema": "http://json-schema.org/draft-07/schema#",
 "description": "DDH Project Transaction Info Response",
 "type": "object",
 "additionalProperties": true,
 "properties": {
   "id": {
     "type": "string",
     "minLength": 1
   },
  "custom_parameters": {
     "type": "object",
     "additionalProperties": true,
     "minProperties": 1,
     "maxProperties": 200
   }
 }
}

Antwortbeispiel:

{
    "id":"123"
}

Liste der Webhook-Parameter für die Verknüpfung von Transaktions-IDs:

Kaufbestätigung

• den Zahlungs-Webhook mit den Zahlungsdaten;
• den Warenkorbinhalt-Webhook mit den Informationen über die Artikel, die dem Inventar hinzugefügt werden sollen.

Integration aufseiten des Vertriebspartners

Wenn Sie an einer Integration von Digital Distribution Hub interessiert sind, senden Sie dem Integrationsmanager eine E-Mail (psbusiness@xsolla.com), und bitten Sie um die für die Nutzung der Digital Distribution Hub API erforderlichen Parameter:

• geotype;
• project_id;
• distribution_hub_id und api_key.

Während der Integration müssen Sie Benachrichtigungen über erfolgreiche Zahlungen oder Zahlungsstornierungen versenden (Schritt 9). Damit die Benachrichtigungen aufseiten von Xsolla korrekt verarbeitet werden können, müssen Sie Ihrem Kundenbetreuer die IP-Adresse des Servers mitteillen, von dem aus Sie die Benachrichtigungen senden. Wenn sich die IP-Adresse ändert, sollten Sie den Kundenbetreuer so schnell wie möglich informieren.

1. Zeigen Sie eine Maske mit folgenden Eingabefeldern an:
   • E-Mail-Adresse des Nutzers – beim Verkauf von Spielen
   • E-Mail-Adresse und Ingame-ID des Nutzers – beim Verkauf von Ingame-Items

1. Die Benutzer-ID kommt bei Projekten zum Einsatz, bei denen virtuelle Gegenstände, virtuelle Währung und Bundles mit virtuellen Gegenständen und virtueller Währung zum Verkauf angeboten werden. In diesem Fall ist es auch notwendig, den Nutzer darauf hinzuweisen, seine ID einzugeben, die er bei der Registrierung im Spiel erhalten hat.

1. Beispiel:

2. Übermitteln Sie die erhaltenen Nutzerdaten:
   • E-Mail-Adresse des Nutzers. Stets erforderlich.
   • Ingame-ID des Nutzers. Erforderlich beim Verkauf von Ingame-Items.

1. Anhand der Daten wird geprüft, ob der Nutzer im Spiel existiert, außerdem dienen sie dazu, einen Autorisierungstoken abzurufen.

1. Nutzen Sie die Methode Benutzertoken erstellen. Übermitteln Sie die folgenden Parameter in der Anfrage:

1. Ein Autorisierungstoken mit Nutzerdaten wird in der Antwort zurückgegeben.

3. Import:
   • Spielekatalog; Methode Spieleliste abrufen nutzen
   • Katalog mit virtuellen Gegenständen; Methode Liste der virtuellen Gegenstände abrufen nutzen
   • Katalog mit virtueller Währung; Methode Liste der virtuellen Währungen abrufen nutzen
   • Bundles mit Spielen oder Katalog mit Ingame-Items; Methode Liste der Bundles abrufen nutzen

1. Übermitteln Sie in der Anfrage den in Schritt 2 erhaltenen Token und den folgenden Parameter:

4. Zeigen Sie den Spiele- und Ingame-Items-Katalog auf Ihrer Shopstartseite an. Implementieren Sie auf der Benutzeroberfläche folgende Auswahlmöglichkeiten:
   • Anzahl der Spielschlüssel und Publishing-Plattformen;
   • Anzahl der virtuellen Gegenstände;
   • Anzahl der virtuellen Währung bzw. virtuellen Währungspakete für einen festen Währungsbetrag;
   • Anzahl der Bundles.

1. Wenn Sie einen Warenkorb verwenden, kann die Artikelmenge darin festgelegt werden. Wenn Sie keinen Warenkorb verwenden, können Sie implementieren, dass die Auswahl der Artikelmenge im Katalog erfolgt.

1. Beispiel für die Auswahl der Artikelmenge im Warenkorb:

1. Beispiel für die Auswahl der Artikelmenge im Katalog:

1. Wenn Sie keinen Einkaufswagen verwenden, wechseln Sie zu Schritt 6, und verwenden Sie die Methode Bestellung mit dem angegebenen Artikel erstellen.

5. Nutzen Sie die Methode Artikel in den Warenkorb legen, um den Warenkorb zusammenzustellen.

1. Der Benutzer kann in einer Bestellung Artikel hinzufügen, entfernen oder deren Menge ändern. So lässt sich der Warenkorb aktualisieren:
   • Über die Methode Artikel in den Warenkorb legen, jedes Mal, wenn der Benutzer den Inhalt des Warenkorbs ändert.
   • Methoden zum Aktualisieren des Warenkorbs und zum Löschen eines Artikels:
     • Warenkorbartikel aus aktuellem Warenkorb aktualisieren.
     • Alle Warenkorbartikel aus dem aktuellen Warenkorb löschen.
     • Warenkorbartikel aus aktuellem Warenkorb löschen.

1. Nutzen Sie in diesem Fall nach dem Aktualisieren des Warenkorbs die Methode Warenkorb des aktuellen Benutzers abrufen.

1. Übermitteln Sie die folgenden Parameter in den Anfragen für das Zusammenstellen und Aktualisieren des Warenkorbs:

1. Nach dem Aufruf der Methode Artikel in den Warenkorb legen oder Warenkorb des aktuellen Benutzers abrufen liefert die Antwort aktualisierte Informationen über die ausgewählten Artikel: Preise mit und ohne Rabatt, Bonusartikel.

6. Verwenden Sie die Methode Bestellung mit allen Artikeln aus dem aktuellen Warenkorb erstellen, um eine Bestellung anzulegen und die im Warenkorb befindlichen Artikel zu bezahlen. Übermitteln Sie die folgenden Parameter in der Anfrage:

1. In der Antwort werden die Bestell-ID und der Warenkorbpreis inklusive Steuern zurückgegeben.

7. Zeigen Sie dem Nutzer den Gesamtpreis des Warenkorbs an.
8. Belasten Sie das Guthaben des Nutzers auf Ihrer Plattform. Zeigen Sie dem Nutzer den Zahlungsstatus an.
9. Senden Sie eine Zahlungsbenachrichtigung. Wenn die Zahlung erstattet oder nicht abgeschlossen wurde, senden Sie eine Benachrichtigung über die Zahlungsstornierung.

1. Damit die Benachrichtigungen aufseiten von Xsolla korrekt verarbeitet werden können, müssen Sie dem Xsolla-Kundenbetreuer die IP-Adresse des Servers mitteillen, von dem aus Sie die Benachrichtigungen senden. Wenn sich die IP-Adresse ändert, sollten Sie den Kundenbetreuer so schnell wie möglich informieren.