Configurer un bundle PlayFab pouvant être acheté sur le Google Play Store

Ce tutoriel vous montre comment créer un bundle PlayFab, l’ajouter à votre jeu sur la place de marché Google pour que les joueurs puissent l’acheter, et comment échanger les éléments qu’il contient.

Prérequis

Un titre dans Game Manager de PlayFab.
Une intégration existante entre le titre sélectionné et la place de marché souhaitée.
Une application déjà créée et disponible sur Google Play.
1. Assurez-vous que l’API Google Play Android Developer est activée pour votre application.

Étape 1 : Créer un bundle

Dans ce tutoriel, nous commençons par créer le Bundle dans la Google Play Console.

Créer un Bundle à l’aide de la Google Play Console

Ouvrez l’application souhaitée dans la Google Play Console.
Dans la barre de navigation de gauche, faites défiler jusqu’à la section Monetize et sélectionnez In-app products.
Sélectionnez Create product en haut à droite.
Saisissez le Product ID et le Name souhaités pour le bundle. Dans ce tutoriel, utilisez warrior_bundle comme Product ID. Retenez le Product ID, car il servira à établir le lien avec Game Manager.
Faites défiler jusqu’à la section Price et sélectionnez Set price.
Ajoutez le prix souhaité pour votre bundle, par exemple 1,00 $, puis sélectionnez Apply prices en bas à droite.
Sélectionnez Save pour enregistrer toutes les modifications apportées au bundle. Notez que l’enregistrement ne l’active pas en tant que produit. Une fois l’enregistrement effectué, l’option d’activation apparaît. Pour activer le bundle dans votre application dans la Google Play Console, sélectionnez le bouton Activate en bas à droite.

Créer un Bundle à l’aide de Game Manager

Pour créer un Bundle dans Game Manager, procédez comme suit :

Accédez à Game Manager et à votre titre.
Dans le menu de navigation de gauche, choisissez Engage > Economy.
Sélectionnez l’onglet Bundles.
Sélectionnez New bundle.
Ajoutez les informations souhaitées au Bundle, comme des éléments et des prix. Dans ce tutoriel, utilisez Warrior Bundle comme nom.
Faites défiler jusqu’en bas de la page et sélectionnez Save and publish si vous souhaitez le publier immédiatement, ou Save as draft si vous souhaitez l’enregistrer sans le rendre disponible pour le moment.

Ajouter des éléments à votre bundle

Un bundle n’accorde à lui seul aucun élément à un joueur : nous devons d’abord y lier des éléments, puis, une fois échangé, il accorde ces éléments à ce joueur. Avant d’ajouter des éléments à un bundle, assurez-vous que ces éléments sont déjà créés et publiés dans votre catalogue. Nous disposons déjà d’une épée appelée Fire Sword et d’un bouclier appelé Ice Shield. Si vous ne savez pas comment créer un élément, consultez cette étape. Ajoutons-les maintenant à votre bundle ! Pour cela, vous pouvez soit les ajouter lors de la création initiale de votre bundle, à condition que les éléments soient déjà créés, soit les ajouter ultérieurement en modifiant le bundle. En mode édition, faites défiler jusqu’à la section Items de votre bundle et sélectionnez le bouton Add. Une fenêtre s’affiche avec tous les éléments disponibles dans votre catalogue ; vous pouvez y filtrer par type (Items ou éléments de contenu généré par l’utilisateur (UGC)) ou rechercher un élément spécifique. Nous sélectionnons le bouton Add à côté de chacun des éléments à ajouter, puis le bouton bleu Add en bas de la fenêtre.

Activer le mappage de place de marché

Pour garantir que, lorsqu’un joueur achète un bundle depuis votre application, celui-ci soit correctement acheté et attribué dans Game Manager, vous devez configurer votre Marketplace Mapping. Vous pouvez le faire lors de la création de votre bundle dans Game Manager ou après sa création en revenant au bundle en mode édition.

Accédez à votre bundle en mode édition.
Faites défiler jusqu’à la section Marketplace Mapping.
Dans la liste déroulante Marketplace, sélectionnez la place de marché souhaitée. (Pour ce tutoriel, il s’agit de GooglePlay.)
Pour votre Marketplace ID, veillez à utiliser la même valeur que votre Product ID dans la Google Play Console. Dans ce tutoriel, nous avons utilisé Warrior_bundle.
Pour terminer, sélectionnez le + à droite de cette ligne.

Étape 2 : Générer un Purchase Token

Assurez-vous d’avoir rempli le prérequis n° 3 avant de continuer ; sinon, il n’existe aucun moyen pratique de générer un Purchase Token.

Un Purchase Token est un jeton généré par les API de Google Play à chaque achat, semblable à un ID de reçu. Selon la documentation de Google, « un Purchase Token est une chaîne qui représente le droit d’un acheteur sur un produit sur Google Play. Il indique qu’un utilisateur Google a payé pour un produit spécifique. » Dans votre implémentation, vous devez enregistrer ce jeton, car il doit être envoyé à l’API de PlayFab afin de valider l’achat auprès de la place de marché Google. Il permet à PlayFab d’échanger les éléments achetés par le joueur et de les accorder dans son inventaire. Pour générer le jeton, vous devez déjà disposer d’une application en cours d’exécution avec une intégration active à Google Play. L’inscription de votre application sur Google Play doit également proposer des éléments (ou, dans ce cas, un bundle) à l’achat. Votre implémentation doit utiliser le système de facturation de Google Play pour qu’un jeton vous soit renvoyé lorsque vous effectuez un achat. En résumé, le système de facturation doit être utilisé lors du développement de votre application ; grâce à ce système, vous pouvez acheter le bundle côté Google, qui renvoie alors le Purchase Token. Le jeton doit ensuite être utilisé avec l’API Economy de PlayFab pour échanger l’achat et ajouter les éléments du bundle à l’inventaire du joueur.

Pour des exemples d’implémentation d’un projet similaire utilisant les systèmes de Google, consultez ce CodeLab. Pour plus d’informations sur la facturation, consultez la documentation du système de facturation de Google.

Étape 3 : Échanger un bundle

Maintenant que votre bundle est créé à la fois dans Game Manager et dans la Google Play Console, vous pouvez échanger votre bundle pour l’un de vos joueurs. Dans cet exemple, nous nous concentrons sur l’utilisation de l’API de PlayFab, plus précisément l’appel RedeemGooglePlayInventoryItems, qui fait partie de l’API Economy de PlayFab.

Vérifier les AlternateID

Avant d’effectuer l’appel d’échange, assurez-vous que l’AlternateId dans Game Manager est correct : il doit être identique à celui de la Google Play Console. La capture d’écran suivante provient de votre bundle dans Game Manager ; le Marketplace ID est ce que nous appelons l’AlternateId, c’est-à-dire un autre moyen d’identifier votre bundle.

Dans la Google Play Console, accédez à l’écran In-app products de la section Monetize ; vous y voyez tous les produits que vous avez créés, y compris le Warrior Bundle. Le Product ID figure dans la deuxième colonne ; assurez-vous qu’il est identique à votre AlternateId dans Game Manager. Si ce n’est pas le cas, mettez à jour Game Manager.

Authentifier le joueur

Pour échanger un élément, utilisez RedeemGooglePlayInventoryItems. Mais auparavant, nous devons nous assurer que le joueur qui souhaite échanger le ou les éléments est correctement authentifié dans votre application, ce pour quoi vous utiliserez probablement LoginWithGoogleAccount.

Pour un exemple plus détaillé, consultez Configuration de l’authentification PlayFab à l’aide de la connexion Google Play Jeux dans Unity.

Après un appel LoginWithGoogleAccount réussi, l’API de PlayFab renvoie un EntityToken que vous devez inclure dans les en-têtes de RedeemGooglePlayInventoryItems avec la clé X-EntityToken. Voici à quoi cela ressemble si vous utilisez une plateforme d’API pour les tests.

Effectuer l’appel d’échange

Votre joueur est authentifié, les deux instances du bundle sont créées et leurs Alternate IDs vérifiés, et vous disposez de votre Purchase Token. Vous êtes prêt à effectuer l’appel d’échange. Pour cela, nous utilisons l’appel d’API RedeemGooglePlayInventoryItems.

{
    "Purchases": [
        {
            "ProductId": "warrior_bundle",
            "Token": "{Your Google Purchase Token}"
        }
    ]
}

L’appel est simple : vous disposez d’un tableau Purchases contenant le Product ID (qui doit correspondre à celui de la Google Play Console) et d’un champ Token correspondant au Purchase Token renvoyé lors de l’appel au Google Play Billing System. Une réponse réussie inclut un 200 status code ainsi que des données telles qu’un timestamp et un MarketplaceTransactionId. Après un échange réussi, si vous consultez l’inventaire de votre joueur, vous devriez voir les deux éléments liés au bundle.

Chaque action d’échange déclenche également un journal d’événement correspondant dans l’historique des transactions du joueur, que vous pouvez consulter dans l’onglet Transaction History (V2) de la page de présentation d’un joueur donné, et qui ressemble à ceci :

En plus de l’enregistrement dans l’historique des transactions du joueur, un événement PlayStream est également déclenché et journalisé. Vous pouvez accéder à ces journaux pour votre titre via la page Data de la section Analyze de la barre de navigation de gauche dans Game Manager. Vous pouvez y modifier des requêtes pour rechercher des enregistrements spécifiques ou les exécuter avec les paramètres par défaut pour tout obtenir. Un enregistrement doit apparaître avec l’Event name items_redeemed, comme suit :

Vous remarquerez que deux événements PlayStream items_redeemed distincts sont journalisés : en effet, même si nous n’avons échangé qu’un seul bundle, celui-ci contenait deux éléments différents.

Étape 4 : Consommation

Après avoir échangé votre achat, vous devez vous assurer qu’il est correctement consommé sur la place de marché. Voici comment procéder :

En utilisant la méthode purchases.products.consume de l’API Google Play Developer.
En utilisant la méthode BillingClient.consumeAsync du Billing Client de Google.
Ou en utilisant l’un des plug-ins intégrés, comme ceux disponibles pour Unity et Unreal.

Toutefois, avant d’effectuer l’appel de consommation (ou, dans les plug-ins Unity ou Unreal, avant que le client n’indique qu’il a terminé le traitement de l’achat), vous devez recevoir une réponse 200 après le processus d’échange avec au moins une réussite et 0 échec. Si vous recevez une réponse 202 ou un échec d’échange, nous vous recommandons de réessayer l’appel de consommation une fois de plus après un certain temps.

XBOX Services

PlayFab

Échange avec la place de marché Google

Configurer un bundle PlayFab pouvant être acheté sur le Google Play Store

Prérequis

Étape 1 : Créer un bundle