Créer des transactions d'abonnement numériques

Ce guide explique comment ajouter des transactions d'abonnement numérique à votre action de conversation afin que les utilisateurs puissent souscrire vos abonnements.

Termes clés: Un produit numérique d'abonnement est une unité de gestion des stocks (SKU) nécessitant un paiement récurrent pour l'utilisateur, comme un magazine en ligne. Cela diffère d'un produit numérique consommable qu'un utilisateur doit racheter manuellement ou d'un produit numérique non consommable qui n'est automatiquement acheté qu'une seule fois.

Pour en savoir plus sur les abonnements numériques, consultez la documentation Android sur les fonctionnalités spécifiques aux abonnements.

Flux de transactions

Ce guide décrit chaque étape de développement au cours d'un flux de transactions de biens numériques. Lorsque votre action traite des transactions pour des produits numériques, elle suit le flux suivant:

  1. Configurer un client d'API d'achats numériques: votre action utilise l'API d'achats numériques pour communiquer avec votre inventaire Google Play et effectuer des transactions. Avant que votre action ne fasse quoi que ce soit, elle crée un client JWT avec une clé de service pour communiquer avec l'API Digital Purchases.
  2. Recueillir des informations: votre action collecte des informations de base sur l'utilisateur et votre inventaire Google Play pour préparer une transaction.
    1. Valider les exigences de transaction: votre action utilise l'assistant des exigences de transactions numériques au début du parcours d'achat pour s'assurer que l'utilisateur peut effectuer une transaction.
    2. Rassembler l'inventaire disponible: votre action vérifie votre inventaire Google Play et identifie les articles actuellement disponibles à l'achat.
  3. Créer la commande: votre action présente les produits numériques disponibles à l'utilisateur afin qu'il puisse en sélectionner un et l'acheter.
  4. Finaliser l'achat: votre action utilise l'API d'achats numériques pour effectuer un achat à partir de la sélection de l'utilisateur sur le Google Play Store.
  5. Gérer le résultat: votre action reçoit un code d'état pour la transaction et informe l'utilisateur que l'achat a abouti (ou qu'il prend des mesures supplémentaires).

Restrictions et consignes relatives aux avis

Des règles supplémentaires s'appliquent aux actions avec transactions. L'examen des actions qui incluent des transactions peut prendre quelques semaines. Tenez-en compte lorsque vous planifiez votre calendrier de lancement. Pour faciliter le processus d'examen, assurez-vous de respecter les Règles et consignes concernant les transactions avant d'envoyer votre action pour examen.

Les actions de vente de produits numériques ne peuvent être déployées que dans les pays suivants:

  • Australie
  • Brésil
  • Canada
  • Indonésie
  • Japon
  • Mexique
  • Russie
  • Singapour
  • Thaïlande
  • Turquie
  • Royaume-Uni
  • États-Unis

Conditions préalables

Avant d'intégrer des transactions numériques dans votre action, vous devez remplir les conditions préalables suivantes:

Associer une application Android

Si vous ne possédez pas encore d'application Android disposant de l'autorisation de facturation dans la Google Play Console, procédez comme suit:

  1. Dans Android Studio ou l'IDE Android de votre choix, créez un projet. Choisissez des options dans les invites de configuration du projet pour créer une application très basique.
  2. Attribuez un nom de package au projet, tel que com.mycompany.myapp. Ne conservez pas ce nom par défaut, car vous ne pouvez pas importer de packages contenant com.example dans la Play Console.
  3. Ouvrez le fichier AndroidManifest.xml de votre application.
  4. Ajoutez la ligne de code suivante dans l'élément manifest:

    <uses-permission android:name="com.android.vending.BILLING" />

    Votre fichier AndroidManifest.xml devrait ressembler au bloc de code suivant:

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools"
        package="com.mycompany.myapp">
        <uses-permission android:name="com.android.vending.BILLING" />
    
        <application
            android:allowBackup="true"
            android:icon="@mipmap/ic_launcher"
            android:label="@string/app_name"
            android:roundIcon="@mipmap/ic_launcher_round"
            android:supportsRtl="true"
            android:theme="@style/AppTheme" />
    </manifest>
    
  5. Créez votre application en tant qu'APK signé. Dans Android Studio, procédez comme suit:

    1. Accédez à Build (Compiler), puis à Generate Signed Bundle / APK (Générer un app bundle/APK signé).
    2. Cliquez sur Suivant.
    3. Sous Key Store Path (Chemin d'accès au keystore), cliquez sur Create new (Créer).
    4. Remplissez chaque champ, puis cliquez sur OK. Notez le mot de passe du keystore et le mot de passe de la clé, et stockez-les en lieu sûr, car vous les utiliserez plus tard.
    5. Cliquez sur Suivant.
    6. Sélectionnez Libérer.
    7. Sélectionnez V1 (JAR Signature) (V1 (signature JAR)).
    8. Cliquez sur Terminer.
    9. Après quelques secondes, Android Studio génère un fichier app-release.apk. Localisez ce fichier pour une utilisation ultérieure.
  6. Dans la Google Play Console, créez une application.

  7. Accédez à Versions de l'application.

  8. Sous Versions fermées, accédez à Gérer, puis à Alpha.

  9. Cliquez sur le bouton Create Release (Créer une version).

  10. Sous Autoriser Google à gérer et à protéger votre clé de signature, saisissez les informations de votre clé de signature.

  11. Importez votre fichier APK.

  12. Cliquez sur Enregistrer.

Créez vos produits numériques

Si vous n'avez aucun produit numérique dans la Play Console actuellement, procédez comme suit:

  1. Dans la Google Play Console, accédez à Produits intégrés, puis à Abonnements. Si un avertissement s'affiche, suivez les instructions précédentes pour créer une application Android ou cliquez sur le lien pour créer un profil de marchand.
  2. Cliquez sur Créer un abonnement.
  3. Remplissez les champs concernant votre produit numérique. Notez l'ID produit, qui vous permettra de le référencer dans votre action.
  4. Cliquez sur Enregistrer.
  5. Répétez les étapes 2 à 4 pour chaque produit que vous souhaitez vendre.

Exemples d&#39;abonnements dans la Google Play Console.

Préparer votre projet Actions

Une fois vos produits numériques configurés dans la Google Play Console, vous devez activer les transactions numériques et associer votre projet Actions à votre application Play.

Prérequis

Pour activer les transactions de produits numériques dans votre projet Actions, procédez comme suit:

  1. Dans la console Actions, ouvrez votre projet ou créez-en un.
  2. Sélectionnez Déployer, puis Informations sur le répertoire.
  3. Sous Informations supplémentaires et Transactions, cochez la case Oui sous Vos actions utilisent-elles l'API Digital Purchase pour effectuer des transactions de produits numériques.
  4. Cliquez sur Enregistrer.

Créer une clé API pour les produits numériques

Pour envoyer des requêtes à l'API Digital Goods, vous devez télécharger une clé de compte de service JSON associée à votre projet dans la console Actions.

Pour récupérer la clé de votre compte de service, procédez comme suit:

  1. Dans la console Actions, cliquez sur l'icône à trois points en haut à droite, puis sur Paramètres du projet.
  2. Recherchez l'ID de projet de votre action.
  3. Suivez ce lien, en remplaçant "<project_id>" par l'ID de votre projet : https://console.developers.google.com/apis/credentials?project=project_id
  4. Dans le menu de navigation principal, accédez à Identifiants.
  5. Sur la page qui s'affiche, cliquez sur Créer des identifiants, puis sur Clé de compte de service.
  6. Accédez à Compte de service, puis cliquez sur Nouveau compte de service.
  7. Attribuez un nom au compte de service, par exemple "digitaltransactions".
  8. Cliquez sur Créer.
  9. Définissez le rôle sur Projet > Propriétaire.
  10. Cliquez sur Continuer.
  11. Cliquez sur Create Key (Créer une clé).
  12. Sélectionnez le type de clé JSON.
  13. Cliquez sur Créer une clé et téléchargez la clé du compte de service JSON.

Enregistrez cette clé de compte de service en lieu sûr. Vous utiliserez cette clé dans votre traitement afin de créer un client pour l'API Digital Purchases.

Associer à votre inventaire Play

Pour accéder à vos produits numériques à partir d'un projet Actions, associez votre domaine Web et votre application à votre projet en tant que propriétés connectées.

Pour associer votre application et votre domaine Web Play Console à votre projet Actions, procédez comme suit:

  1. Dans la console Actions, accédez à Déployer, puis à Validation de la marque.
  2. Si vous n'avez associé aucune propriété, commencez par associer un site Web:

    1. Cliquez sur le bouton du site Web (</>).
    2. Saisissez l'URL de votre domaine Web, puis cliquez sur Connecter.

    Google envoie un e-mail contenant des instructions supplémentaires à la personne qui a été validée pour ce domaine Web dans la Google Search Console. Une fois que le destinataire de cet e-mail aura suivi ces étapes, le site Web devrait apparaître sous Validation de la marque.

  3. Une fois que vous avez au moins un site Web connecté, procédez comme suit pour connecter votre application Android:

    1. Dans la console Actions, accédez à Déployer, puis à Validation de la marque.
    2. Cliquez sur Associer une application.
    3. Sur la page qui s'affiche, suivez les instructions pour valider votre domaine Web dans la Play Console. Sélectionnez l'application Play contenant vos articles numériques, puis saisissez l'URL du domaine Web exactement telle qu'elle apparaît sur la page Validation de la marque.

      Une fois encore, Google envoie un e-mail de validation au propriétaire validé du domaine. Une fois la validation approuvée, votre application Play devrait apparaître sous Validation de la marque.

    4. Activez l'option Accéder aux achats sur Play.

Image montrant le site Web et les applications associés au projet Actions.

Créez votre parcours d'achat

Une fois votre projet Actions et votre inventaire de produits numériques prêts, créez un parcours d'achat de produits numériques dans votre webhook de traitement des conversations.

1. Configurer un client API pour les achats numériques

Dans le webhook de traitement de la conversation, créez un client JWT avec la clé JSON de votre compte de service et le champ d'application https://www.googleapis.com/auth/actions.purchases.digital.

Le code Node.js suivant crée un client JWT pour l'API Digital Purchases:

  const serviceAccount = {'my-file.json'};
  const request = require('request');
  const {google} = require('googleapis');

  const jwtClient = new google.auth.JWT(
    serviceAccount.client_email, null, serviceAccount.private_key,
    ['https://www.googleapis.com/auth/actions.purchases.digital'],
    null
  );

2. Recueillir des informations

Avant que l'utilisateur puisse effectuer un achat, votre action collecte des informations sur sa capacité à effectuer des achats et sur les produits disponibles dans votre inventaire.

2. a. Valider les exigences de transaction

Nous vous recommandons de vous assurer que le compte de l'utilisateur est configuré pour effectuer des transactions avant de lui donner la possibilité d'effectuer un achat. Vous devez passer à une scène DigitalPurchaseCheck, qui vérifie que l'utilisateur est validé, qu'il effectue la transaction sur une surface autorisée (écran connecté, enceinte intelligente ou Android) et qu'il se trouve dans une région où les transactions numériques sont acceptées.

Pour créer une scène de vérification des achats numériques, procédez comme suit:

  1. Dans l'onglet Scenes (Scènes), ajoutez une scène nommée DigitalPurchaseCheck.
  2. Sous Remplissage de cases, cliquez sur + pour ajouter un emplacement.
  3. Sous Select type (Sélectionner un type), sélectionnez actions.type.DigitalPurchaseCheckResult comme type d'emplacement.
  4. Dans le champ du nom de l'emplacement, nommez l'emplacement DigitalPurchaseCheck.
  5. Cochez la case Customizeslot value writeback (Personnaliser l'écriture des valeurs d'emplacement) (activée par défaut).
  6. Cliquez sur Enregistrer.

Une vérification des achats numériques peut entraîner l'un des résultats suivants:

  • Si les conditions sont remplies, le paramètre de session est défini avec une condition de réussite, et vous pouvez autoriser l'utilisateur à acheter des produits numériques.
  • Si une ou plusieurs des conditions ne peuvent pas être remplies, le paramètre de session est défini avec une condition d'échec. Dans ce cas, vous devez détourner la conversation de l'expérience transactionnelle ou mettre fin à la conversation.

Pour gérer le résultat du contrôle des achats numériques, procédez comme suit:

  1. Dans l'onglet Scenes (Scènes), sélectionnez la scène DigitalPurchaseCheck que vous venez de créer.
  2. Sous Condition, cliquez sur + pour ajouter une condition.
  3. Dans le champ de texte, saisissez la syntaxe de condition suivante pour vérifier la condition de réussite:

    scene.slots.status == "FINAL" && session.params.DigitalPurchaseCheck.resultType == "CAN_PURCHASE"
    
  4. Pointez sur la condition que vous venez d'ajouter, puis cliquez sur la flèche vers le haut pour la placer avant if scene.slots.status == "FINAL".

  5. Activez Envoyer des invites et fournissez une invite simple informant l'utilisateur qu'il est prêt à effectuer une transaction:

    candidates:
      - first_simple:
          variants:
            - speech: >-
                You are ready to purchase digital goods.
    
  6. Sous Transition, sélectionnez une autre scène, ce qui permet à l'utilisateur de poursuivre la conversation et d'effectuer une transaction.

  7. Sélectionnez la condition else if scene.slots.status == "FINAL".

  8. Activez Envoyer des invites et fournissez une invite simple informant l'utilisateur qu'il ne peut pas effectuer de transaction:

    candidates:
      - first_simple:
          variants:
            - speech: Sorry you cannot perform a digital purchase.
    
  9. Sous Transition, sélectionnez End conversation (Terminer la conversation) pour mettre fin à la conversation.

2. b. Rassembler l'inventaire disponible

Utilisez l'API d'achats numériques pour demander votre inventaire Play Store actuellement disponible, puis créez un tableau d'objets JSON pour chaque produit. Vous référencez ce tableau ultérieurement pour indiquer à l'utilisateur quelles options sont disponibles à l'achat.

Chacun de vos produits numériques est représenté sous la forme d'un SKU au format JSON. Le code Node.js suivant décrit la mise en forme attendue pour chaque code SKU:

body = {
  skus: [
    skuId: {
      skuType: one of "SKU_TYPE_IN_APP" or "SKU_TYPE_SUBSCRIPTION"
      id: string,
      packageName: string
    }
    formattedPrice: string,
    title: string,
    description: string
  ]
}

Envoyez une requête POST au point de terminaison https://actions.googleapis.com/v3/packages/{packageName}/skus:batchGet, où {packageName} est le nom de package de votre application dans la Google Play Console (par exemple, com.myapp.digitalgoods), puis mettez en forme le résultat dans un tableau d'objets SKU.

Pour ne récupérer que des produits numériques spécifiques dans le tableau obtenu, répertoriez les ID des produits numériques (tels qu'ils apparaissent sous chaque produit intégré dans la Google Play Console) que vous souhaitez rendre disponibles à l'achat dans body.ids.

Le code Node.js suivant demande la liste des produits disponibles à partir de l'API Digital purchases et met en forme le résultat sous la forme d'un tableau de SKU:

return jwtClient.authorize((err, tokens) => {
    if (err) {
      throw new Error(`Auth error: ${err}`);
    }

    const packageName = 'com.example.projectname';

    request.post(`https://actions.googleapis.com/v3/packages/${packageName}/skus:batchGet`, {
      'auth': {
        'bearer': tokens.access_token,
      },
      'json': true,
      'body': {
        'conversationId': conv.session.id,
        'skuType': 'SKU_TYPE_IN_APP',
        // This request is filtered to only retrieve SKUs for the following product IDs
        'ids': ['annual.subscription']
      },
    }, (err, httpResponse, body) => {
      if (err) {
        throw new Error(`API request error: ${err}`);
      }
      console.log(`${httpResponse.statusCode}: ${httpResponse.statusMessage}`);
      console.log(JSON.stringify(body));
    });
  });
});

3. Créer la commande

Pour commencer l'achat numérique de l'utilisateur, présentez la liste des produits numériques disponibles à l'achat. Vous pouvez utiliser divers types de réponses enrichies pour représenter votre stock et inviter l'utilisateur à faire un choix.

Le code Node.js suivant lit un tableau d'inventaire d'objets SKU et crée une réponse de liste contenant chacun un élément de liste:

const items = [];
const entries = [];
skus.forEach((sku) => {
   const key = `${sku.skuId.skuType},${sku.skuId.id}`
   items.push({
       key: key
   });
   entries.push({
       name: key,
       synonyms: [],
       display: {
           title: sku.title,
           description: `${sku.description} | ${sku.formattedPrice}`,
       }
   });
});

conv.session.typeOverrides = [{
   name: 'type_name',
   mode: 'TYPE_REPLACE',
   synonym: {
       entries: entries
   }
}];

conv.add(new List({
   title: 'List title',
   subtitle: 'List subtitle',
   items: items,
}));

Créer un achat à partir de la sélection de l'utilisateur

Une fois que l'utilisateur a sélectionné un article, vous pouvez créer la commande. Pour ce faire, au niveau de l'emplacement associé à l'élément sélectionné, vous pouvez appeler votre webhook afin de créer la commande. À partir du traitement, enregistrez les données de la commande dans un paramètre de session. L'objet d'ordre est utilisé dans toutes les scènes d'une même session.

conv.session.params.purchase = {
  "@type": "type.googleapis.com/google.actions.transactions.v3.CompletePurchaseValueSpec",
  "skuId": {
    "skuType": "<SKU_TYPE_IN_APP>",
    "id": "<SKU_ID>",
    "packageName": "<PACKAGE_NAME>"
  },
  "developerPayload": ""
};

Dans Actions Builder, vous pouvez utiliser l'éditeur JSON pour configurer l'emplacement avec l'objet de commande ci-dessus. Les deux implémentations utilisent le même format pour CompletePurchaseValueSpec, que vous trouverez dans la documentation de référence sur la charge utile de webhook JSON.

4. Finaliser l'achat

Une fois que l'utilisateur a sélectionné un article, vous pouvez finaliser son achat. Une fois que vous avez rempli l'emplacement associé à l'élément sélectionné, vous devez passer à une scène qui effectue un achat complet.

Créer une scène d'achat complète

  1. Dans l'onglet Scenes (Scènes), ajoutez une scène nommée CompletePurchase.
  2. Sous Remplissage de cases, cliquez sur + pour ajouter un emplacement.
  3. Sous Select type (Sélectionner un type), sélectionnez actions.type.CompletePurchaseValue comme type d'emplacement.
  4. Dans le champ du nom de l'emplacement, nommez l'emplacement CompletePurchase.
  5. Cochez la case Personnaliser l'écriture des valeurs d'emplacement (option activée par défaut).
  6. Sous Configurer l'emplacement, sélectionnez Use session parameter dans le menu déroulant.
  7. Sous Configurer l'emplacement, saisissez le nom du paramètre de session utilisé pour stocker la commande dans le champ de texte (par exemple, $session.params.purchase).
  8. Cliquez sur Enregistrer.

5. Gérer le résultat

Un emplacement de type actions.type.CompletePurchaseValue peut avoir les résultats suivants:

  • PURCHASE_STATUS_OK: l'achat a bien été effectué. La transaction est terminée à ce stade. Vous devez donc quitter le flux transactionnel et revenir à votre conversation.
  • PURCHASE_STATUS_ALREADY_OWNED: la transaction a échoué, car l'utilisateur est déjà propriétaire de cet article. Pour éviter cette erreur, vérifiez les achats précédents de l'utilisateur et adaptez les articles affichés afin qu'il n'ait pas la possibilité de racheter les articles qu'il possède déjà.
  • PURCHASE_STATUS_ITEM_UNAVAILABLE: la transaction a échoué, car l'article demandé n'est pas disponible. Pour éviter cette erreur, vérifiez les codes SKU disponibles à une date proche du moment de l'achat.
  • PURCHASE_STATUS_ITEM_CHANGE_REQUESTED: la transaction a échoué, car l'utilisateur a décidé d'acheter autre chose. Envoyez une nouvelle demande lors de la création de la commande afin que l'utilisateur puisse prendre une autre décision immédiatement.
  • PURCHASE_STATUS_USER_CANCELLED: la transaction a échoué, car l'utilisateur a annulé le parcours d'achat. Comme l'utilisateur a quitté le flux prématurément, demandez-lui s'il souhaite réessayer ou quitter la transaction.
  • PURCHASE_STATUS_ERROR: la transaction a échoué pour une raison inconnue. Informez l'utilisateur que la transaction a échoué et demandez-lui s'il souhaite réessayer.
  • PURCHASE_STATUS_UNSPECIFIED: la transaction a échoué pour une raison inconnue, entraînant un état inconnu. Pour gérer cet état d'erreur, informez l'utilisateur que la transaction a échoué et demandez-lui s'il souhaite réessayer.

Vous devez gérer chacun de ces résultats de votre scène CompletePurchase.

  1. Dans l'onglet Scenes (Scènes), sélectionnez la scène CompletePurchase que vous venez de créer.
  2. Sous Condition, cliquez sur + pour ajouter une condition.
  3. Dans le champ de texte, saisissez la syntaxe de condition suivante pour vérifier la condition de réussite:

    scene.slots.status == "FINAL" && session.params.CompletePurchase.purchaseStatus == "PURCHASE_STATUS_OK"
    
  4. Pointez sur la condition que vous venez d'ajouter, puis cliquez sur la flèche vers le haut pour la placer avant if scene.slots.status == "FINAL".

  5. Activez Envoyer des invites et fournissez une invite simple informant l'utilisateur qu'il est prêt à effectuer une transaction:

    candidates:
      - first_simple:
          variants:
            - speech: >-
                Your purchase was successful.
    
  6. Sous Transition, sélectionnez End conversation (Terminer la conversation) pour mettre fin à la conversation.

Répétez les étapes ci-dessus pour chaque type de résultat d'achat que vous souhaitez traiter.

Refléter les achats de l'utilisateur

Lorsqu'un utilisateur interroge votre action, l'objet user de la requête JSON inclut la liste de ses achats. Vérifiez ces informations et modifiez la réponse de votre action en fonction du contenu payé par l'utilisateur.

L'exemple de code suivant montre l'objet user d'une requête qui inclut packageEntitlements des achats précédemment effectués via une application pour le package com.digitalgoods.application:

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "example_session_id",
    "params": {},
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
      "packageEntitlements": [
        {
          "packageName": "com.digitalgoods.application",
          "entitlements": [
            {
              "sku": "non-consumable.1",
              "skuType": "SKU_TYPE_IN_APP"
            }
            {
              "sku": "consumable.2",
              "skuType": "SKU_TYPE_IN_APP"
            }
          ]
        },
        {
          "packageName": "com.digitalgoods.application",
          "entitlements": [
            {
              "sku": "annual.subscription",
              "skuType": "SKU_TYPE_SUBSCRIPTION",
              "inAppDetails": {
                "inAppPurchaseData": {
                  "autoRenewing": true,
                  "purchaseState": 0,
                  "productId": "annual.subscription",
                  "purchaseToken": "12345",
                  "developerPayload": "HSUSER_IW82",
                  "packageName": "com.digitalgoods.application",
                  "orderId": "GPA.233.2.32.3300783",
                  "purchaseTime": 1517385876421
                },
                "inAppDataSignature": "V+Q=="
              }
            }
          ]
        }
      ]
     }
   },
  "homeStructure": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

Tester votre projet

Lorsque vous testez votre projet, vous pouvez activer le mode bac à sable dans la console Actions pour tester votre action sans facturer de mode de paiement. Pour activer le mode bac à sable, procédez comme suit:

  1. Dans la console Actions, cliquez sur Tester dans le menu de navigation.
  2. Cliquez sur Paramètres.
  3. Activez l'option Bac à sable de développement.