Présentation

Digital Distribution Hub est une solution qui met en relation les développeurs de jeux avec de multiples partenaires de distribution qui disposent de leurs propres plateformes ou écosystèmes pour la distribution des jeux, des objets virtuels, de la monnaie virtuelle et des lots.

Partenaires de distribution — plateformes numériques ou écosystèmes qui peuvent distribuer des jeux et des objets en jeu et disposer de leur propre vitrine et de leur propre facturation. Exemples de partenaires de distribution de Xsolla :

• super applications qui regroupent plusieurs services ;
• applications bancaires ;
• fournisseurs de services de télécommunication et d’Internet ;
• kiosques de paiement ;
• fournisseurs de programmes de cashback et de récompenses ;
• marketplace de commerce électronique.

Avantages pour le développeur de jeux :

• Élargissement de l’audience des jeux grâce à une connexion directe avec des partenaires de distribution à croissance rapide.
• Augmentation des revenus en ajoutant des jeux à de nouveaux canaux de distribution avec une base d’utilisateurs unique.
• Augmentation de la découverte organique sur des plateformes tierces grâce à des publicités et des bannières.

Avantages pour le partenaire de distribution :

• Accroître la fidélité des utilisateurs en élargissant l’accès au contenu du jeu. Les utilisateurs achètent des clés de jeu, des objets virtuels, de la monnaie virtuelle et des lots directement à partir de l’application ou du service.
• Fidéliser les utilisateurs actuels et en attirer de nouveaux, grâce à la popularité croissante de l’industrie du jeu.
• Augmenter les revenus en percevant une commission sur la vente de clés de jeu, d’objets virtuels et de la monnaie virtuelle de la part des principaux éditeurs de l’industrie du jeu.

Comment ça marche

Flux d'utilisation lors de l'achat de clés de jeu

Flux d'utilisation lors de l'achat d'objets virtuels et de la monnaie virtuelle

Flux d'interaction

1. Le développeur de jeux crée un projet dans le Compte éditeur et télécharge les clés de jeu, les objets virtuels, la monnaie virtuelle et les lots.
2. Un partenaire de distribution demande des données utilisateur :
   • lors de la vente de jeux — l’adresse e-mail utilisateur à laquelle les clés et le reçu seront envoyés ;
   • lors de la vente des objets en jeu — l’ID utilisateur dans le jeu auquel les objets seront ajoutés, et l’adresse e-mail utilisateur à laquelle le reçu sera envoyé.
3. L’utilisateur saisit les données suivantes dans l’interface du partenaire de distribution :
   • pour les achats de jeux — l’adresse e-mail pour recevoir les clés et le reçu ;
   • pour les achats d’objets en jeu — l’ID dans le jeu pour ajouter les objets à l’inventaire et une adresse e-mail pour recevoir le reçu.
4. Le partenaire de distribution appelle la méthode Create user token et passe l’adresse e-mail (obligatoire) et l’ID utilisateur (obligatoire lors de la vente d’objets virtuels, de la monnaie virtuelle et de lots) en tant que paramètres.
5. Xsolla vérifie si l’utilisateur existe dans le jeu si le développeur du jeu a configuré les webhooks. La configuration des webhooks est obligatoire pour la vente d’objets virtuels et de la monnaie virtuelle, mais facultative pour les clés de jeu.
6. Xsolla crée un jeton avec les données de l’utilisateur et l’envoie au partenaire de distribution.
7. Le partenaire de distribution demande un catalogue des jeux ou un catalogue des objets en jeu.
8. Xsolla renvoie le catalogue demandé dans la réponse.
9. Le partenaire de distribution reçoit le catalogue et l’affiche à l’utilisateur.
10. L’utilisateur effectue un achat. Le partenaire de distribution crée un panier.
11. Le partenaire de distribution envoie le panier de l’utilisateur pour créer une commande.
12. Xsolla renvoie l’ID de la commande et le prix du panier, y compris les remises et les taxes.
13. Le partenaire de distribution affiche le coût total du panier à l’utilisateur.
14. Si l’utilisateur poursuit le paiement, le partenaire de distribution débite les fonds de l’utilisateur et affiche la page d’état du paiement.
15. Le partenaire de distribution notifie à Xsolla que la commande a été payée et envoie les informations relatives au paiement.
16. Xsolla informe le développeur du jeu de l’achat.
17. L’utilisateur qui a acheté le jeu reçoit un e-mail contenant les détails de l’achat et peut activer les clés du jeu. Si l’utilisateur a acheté des objets virtuels ou de la monnaie virtuelle, ceux-ci sont ajoutés à son inventaire.

Intégration du côté du développeur de jeu

Comment connecter Digital Distribution Hub

1. Connectez Store au Compte éditeur et téléchargez :
   • les clés de jeu ou des lots de clés de jeu, si vous vendez des clés de jeu ;
   • les objets virtuels, la monnaie virtuelle ou des lots de ceux-ci, si vous vendez des objets en jeu.
2. Configurez les webhooks.
3. Contactez votre responsable de la réussite client ou envoyez un e-mail à csm@xsolla.com pour activer Digital Distribution Hub pour votre projet.

Comment configurer les webhooks

La configuration des webhooks est nécessaire :

• pour valider l’utilisateur et personnaliser le catalogue par ID utilisateur dans le jeu ;
• pour valider l’utilisateur et ajouter les objets en jeu achetés à son inventaire ;
• pour lier l’ID de transaction côté Xsolla avec l’ID de transaction dans le système du développeur du jeu ;
• pour passer des paramètres utilisateur supplémentaires dans la commande ;
• pour recevoir des notifications d’achat.

Pour configurer des webhooks dans votre Compte éditeur :

1. Ouvrez votre projet dans le Compte éditeur.
2. Cliquez sur Project settings dans le menu latéral et accédez à Webhooks.
3. Réglez la bascule Webhooks sur On.
4. Spécifiez l’URL du webhook.
5. Une clé secrète permettant de signer les webhooks du projet est générée par défaut. Si vous souhaitez en générer une nouvelle, cliquez sur l’icône d’actualisation.
6. Cliquez sur Save settings.

Validation utilisateur

Xsolla envoie le webhook Validation utilisateur pour vérifier que l’utilisateur existe dans le jeu. La validation de l’utilisateur vous permet :

• d’afficher un catalogue personnalisé pour l’utilisateur si vous passez des attributs utilisateur dans la réponse ;
• d’ajouter des objets à l’inventaire de l’utilisateur après l’achat.

Pour confirmer la réception du webhook, votre serveur doit renvoyer :

• code HTTP 204 sans corps de message, si l’utilisateur existe dans le jeu ;
• code HTTP 400 décrivant le problème, si l’utilisateur spécifié n’a pas été trouvé ou si une signature non valide a été passée.

La liste complète et le mécanisme des webhooks, y compris des exemples, sont décrits en détail dans le document Référence API.

En réponse, vous pouvez passer des paramètres de transaction supplémentaires dans l’objet custom_parameters.

{
"$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
  }
}
}

Exemple de réponse :

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

Liaison de l'ID de transaction

{
  "$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"
          }
        }
      }
    }
  }
}

Exemple de requête :

{
  "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"
    }
  ]
}

En réponse, vous pouvez passer des paramètres de transaction supplémentaires dans l’objet custom_parameters.

Réponse attendue :

{
  "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
   }
 }
}

Exemple de réponse :

{
    "id":"123"
}

Liste des paramètres du webhook pour lier les ID de transaction :

Notification d'achat

• Le webhook de paiement qui contient les informations relatives au paiement.
• Le webhook de contenu du panier qui contient des informations sur les objets à ajouter à l’inventaire.

Intégration du côté du partenaire de distribution

Si vous souhaitez intégrer Digital Distribution Hub, envoyez un e-mail au responsable de l’intégration à psbusiness@xsolla.com et obtenez les paramètres requis pour utiliser avec Digital Distribution Hub API :

• geotype ;
• project_id ;
• distribution_hub_id et api_key.

Pendant l’intégration, vous envoyez des notifications sur les paiements réussis ou les annulations de paiement (étape 9). Pour le traitement adéquat des notifications côté Xsolla, communiquez l’adresse IP de votre serveur, à partir duquel vous envoyez les notifications, à votre responsable de compte. Si cette adresse IP venait à changer, informez-en rapidement votre responsable de compte.

1. Affichez un formulaire pour saisir :
   • l’adresse e-mail utilisateur — lors de la vente de jeux ;
   • l’adresse e-mail utilisateur et l’ID utilisateur dans le jeu — lors de la vente d’objets en jeu.

1. L'ID utilisateur est utilisé pour les projets qui vendent des objets virtuels, de la monnaie virtuelle et des lots d'objets et de monnaie. Dans ce cas, il est également nécessaire d'afficher une indication à l'utilisateur lui signifiant d'entrer l'ID qu'il a reçu lors de son inscription au jeu.

1. Exemple :

2. Passez les données utilisateur reçues :
   • Adresse e-mail utilisateur. Toujours obligatoire ;
   • ID utilisateur dans le jeu. Obligatoire lors de la vente d'objets en jeu.

1. Les données sont utilisées pour vérifier l'existence de l'utilisateur dans le jeu et recevoir un jeton d'autorisation.

1. Utilisez la méthode Create user token. Passez des paramètres dans la requête :

1. Un jeton d'autorisation contenant les données utilisateur est renvoyé dans la réponse.

3. Importez :
   • le catalogue des jeux, en utilisant la méthode Lire une liste de jeux ;
   • le catalogue des objets virtuels, en utilisant la méthode Lire un objet virtuel ;
   • le catalogue des monnaies virtuelles, en utilisant la méthode Lire une liste de monnaies virtuelles ;
   • le catalogue des lots contenant des jeux ou des objets en jeu, en utilisant la méthode Lire la liste des lots pour administration.

1. Dans la demande, passez le jeton que vous avez reçu à l'étape 2 et le paramètre suivant :

4. Affichez le catalogue des jeux et des objets en jeu sur votre vitrine. Dans l'interface, implémentez la possibilité de sélectionner :
   • le nombre de clés de jeu et de plateformes de publication de jeux ;
   • le nombre d'objets virtuels ;
   • la quantité de la monnaie virtuelle ou les packages de monnaie virtuelle avec une quantité fixe ;
   • le nombre de lots.

1. Si vous utilisez un panier, le nombre d'objets est spécifié dans le panier de l'utilisateur. Si vous n'utilisez pas de panier, le choix du nombre d'objets est effectué dans le catalogue.

1. Exemple de spécification du nombre d'objets dans le panier :

1. Exemple de spécification du nombre d'objets dans le catalogue :

1. Si vous n'utilisez pas de panier, passez à l'étape 6 et utilisez la méthode Créer une commande à partir d'un objet spécifique.

5. Pour remplir le panier, utilisez la méthode Fill the cart with items.

1. L'utilisateur peut ajouter et supprimer des objets, ou modifier leur quantité en une seule commande. Pour mettre à jour le panier, utilisez les méthodes suivantes :
   • méthode Fill the cart with items pour remplir le panier avec des objets chaque fois que l'utilisateur modifie le contenu du panier.
   • méthodes pour mettre à jour le panier et supprimer un objet :
     • Mettre à jour un objet du panier actuel ;
     • Delete all cart items from current cart ;
     • Delete cart item from current cart.

1. Dans ce cas, utilisez Lire le panier de l'utilisateur actuel après la mise à jour du panier.

1. Passez les paramètres suivants dans les requêtes pour les méthodes de remplissage et de mise à jour du panier :

1. Après l'appel Fill the cart with items ou Lire le panier de l'utilisateur actuel, la réponse renvoie des informations actualisées sur les biens sélectionnés : prix avant et après les remises, produits bonus.

6. Pour créer une commande et payer les objets d'un panier, utilisez la méthode Créer une commande à partir de tous les objets du panier actuel. Passez les paramètres suivants dans la requête :

1. La réponse renvoie l'ID de la commande et le prix du panier, taxes incluses.

7. Affichez le prix total du panier à l'utilisateur.
8. Débitez les fonds de l'utilisateur depuis votre plateforme. Affichez le statut du paiement à l'utilisateur.
9. Envoyez une notification de paiement. Si le paiement a été remboursé ou n'a pas été complété, envoyer une notification d'annulation de paiement.

1. Pour le traitement adéquat des notifications côté Xsolla, communiquez l'adresse IP de votre serveur, à partir duquel vous envoyez les notifications, à votre responsable de compte. Si cette adresse IP venait à changer, informez-en rapidement votre responsable de compte.