L'API Transactions sera abandonnée le 3 mai 2023, avant l'abandon des actions de conversation le 13 juin 2023. Pour en savoir plus, consultez Abandon de la fonctionnalité Conversation.

Cette page a été traduite par l'API Cloud Translation.

Créer des transactions numériques non consommables (Dialogflow)

Ce guide explique comment ajouter des transactions numériques à votre action de conversation afin que les utilisateurs puissent acheter vos produits numériques non consommables.

Termes clés: Un produit numérique non consommable est une unité de gestion des stocks (SKU) qui ne peut être achetée qu'une seule fois, par exemple un accès payant à du contenu supplémentaire dans une application d'action ou Android. Ce type de produit est différent d'un produit numérique consommable qui peut être acheté, utilisé et racheté.

Pour en savoir plus sur les produits ponctuels non consommables, consultez la documentation Android sur les fonctionnalités spécifiques aux produits ponctuels.

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

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:

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.
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.
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.
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.
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'elle nécessite des étapes supplémentaires).

Conditions préalables

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

Un compte de développeur et un compte marchand sur Google Play pour gérer vos produits numériques dans la Google Play Console.
Un domaine Web validé dans la Google Search Console Ce domaine n'a pas besoin d'être associé à un site Web public. Il suffit de faire référence à votre domaine Web.
Une application Android avec l'autorisation com.android.vending.BILLING dans la Google Play Console. Ils seront considérés comme des "achats via une application" associés à cette application dans la Google Play Console.

Vous devez également créer une version dans la Play Console avec cette application. Toutefois, si vous ne souhaitez pas qu'elle soit publique, vous pouvez créer une version alpha fermée.

Si vous n'avez pas encore d'application Android, suivez les instructions pour associer une application Android.
Un ou plusieurs produits gérés dans la Google Play Console, qui sont les produits numériques que vous vendez avec votre action. Notez que vous ne pouvez pas créer de produits gérés dans la Play Console tant que vous n'avez pas configuré l'application Android requise.

Si vous n'avez pas encore de produits gérés, suivez les instructions pour créer vos produits numériques.

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:

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.
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.
Ouvrez le fichier AndroidManifest.xml de votre application.

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>

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.
Dans la Google Play Console, créez une application.
Accédez à Versions de l'application.
Sous Versions fermées, accédez à Gérer, puis à Alpha.
Cliquez sur le bouton Create Release (Créer une version).
Sous Autoriser Google à gérer et à protéger votre clé de signature, saisissez les informations de votre clé de signature.
Importez votre fichier APK.
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:

Dans la Google Play Console, accédez à Produits intégrés, puis à Produits gérés. 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.
Cliquez sur Créer un produit géré.
Remplissez les champs concernant votre produit numérique. Notez l'ID produit, qui vous permettra de le référencer dans votre action.
Cliquez sur Enregistrer.
Répétez les étapes 2 à 4 pour chaque produit que vous souhaitez vendre.

Exemples de produits non consommables 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.

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

Dans la console Actions, ouvrez votre projet ou créez-en un.
Sélectionnez Déployer, puis Informations sur le répertoire.
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.
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:

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

Remarque:Le processus d'association peut prendre jusqu'à une semaine, le temps que nous validions vos propriétés. Si votre site Web ou votre application ne sont pas associés passé ce délai, contactez l'assistance.

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

Dans la console Actions, accédez à Déployer, puis à Validation de la marque.
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.
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.
  
  Remarque :Votre domaine Web apparaîtra dans la Play Console avant d'apparaître dans la console Actions. La mise à jour de la console Actions peut prendre plusieurs jours.
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 laisser la possibilité d'effectuer un achat. Cette étape consiste à vérifier que l'utilisateur a configuré un mode de paiement et qu'il se trouve dans un pays où les transactions numériques sont acceptées. Au début du flux de transaction, utilisez l'outil d'aide DIGITAL_PURCHASE_CHECK pour valider la configuration de la transaction de l'utilisateur avec l'Assistant.

Le code Node.js suivant utilise DIGITAL_PURCHASE_CHECK au début de la conversation:

app.intent('Default Welcome Intent', async (conv, { SKU }) => {
  // Immediately invoke digital purchase check intent to confirm
  // purchase eligibility.
  conv.ask(new DigitalPurchaseCheck());
});

Recherchez le résultat de cette vérification dans les arguments de la conversation sous la forme DIGITAL_PURCHASE_CHECK_RESULT. En fonction de ce résultat, poursuivez le flux de transactions ou quittez la page et invitez vos clients à vérifier leur configuration Google Pay.

Le code Node.js suivant gère le résultat de la vérification des exigences :

app.intent('Digital Purchase Check', async (conv) => {
  const arg = conv.arguments.get('DIGITAL_PURCHASE_CHECK_RESULT');
  if (!arg || !arg.resultType) {
    conv.close('Digital Purchase check failed. Please check logs.');
    return;
  }
  // User does not meet necessary conditions for completing a digital purchase
  if (arg.resultType === 'CANNOT_PURCHASE' || arg.resultType === 'RESULT_TYPE_UNSPECIFIED') {
    conv.close(`It looks like you aren't able to make digital purchases. Please check your Google Pay configuration and try again.`);
    return;
  }
  conv.ask('Welcome to the Digital Goods Sample. Would you like to see what I have for sale?');
});

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 "APP" or "UNSPECIFIED"
      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': conversationId,
        'skuType': 'APP',
        // This request is filtered to only retrieve SKUs for the following product IDs
        'ids': ['nonconsumable.1']
      },
    }, (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:

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

4. Finaliser l'achat

Pour finaliser l'achat, utilisez l'intent d'assistance COMPLETE_PURCHASE avec l'article sélectionné par l'utilisateur.

Le code Node.js suivant gère la sélection de SKU de l'utilisateur à partir d'une réponse à la liste et demande l'intent COMPLETE_PURCHASE avec ces informations:

app.intent('Send Purchase', (conv, params, option) => {
  let [skuType, id] = option.split(',');

  conv.ask(new CompletePurchase({
    skuId: {
      skuType: skuType,
      id: id,
      packageName: <PACKAGE_NAME>,
    },
  }));
});

5. Gérer le résultat

Une fois l'achat terminé, il déclenche l'événement Dialogflow actions_intent_COMPLETE_PURCHASE (ou l'intent du SDK Actions actions.intent.COMPLETE_PURCHASE) avec un argument COMPLETE_PURCHASE_VALUE décrivant le résultat. Créez un intent, déclenché par cet événement, qui communique le résultat à l'utilisateur.

Gérez les résultats d'achat possibles 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 possède déjà 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 SKU disponibles peu avant la date d'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. Étant donné que 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. Gérez cet état d'erreur en informant l'utilisateur que la transaction a échoué et en lui demandant s'il souhaite réessayer.

Le code Node.js suivant lit l'argument COMPLETE_PURCHASE_VALUE et traite chaque résultat:

app.intent('Purchase Result', (conv) => {
  const arg = conv.arguments.get('COMPLETE_PURCHASE_VALUE');
  console.log('User Decision: ' + JSON.stringify(arg));
  if (!arg || !arg.purchaseStatus) {
    conv.close('Purchase failed. Please check logs.');
    return;
  }
  if (arg.purchaseStatus === 'PURCHASE_STATUS_OK') {
    conv.close(`Purchase completed! You're all set!`);
  } else if (arg.purchaseStatus === 'PURCHASE_STATUS_ALREADY_OWNED') {
    conv.close('Purchase failed. You already own this item.');
  } else if (arg.purchaseStatus === 'PURCHASE_STATUS_ITEM_UNAVAILABLE') {
    conv.close('Purchase failed. Item is not available.');
  } else if (arg.purchaseStatus === 'PURCHASE_STATUS_ITEM_CHANGE_REQUESTED') {
    // Reprompt with your item selection dialog
  }  else {
    conv.close('Purchase Failed:' + arg.purchaseStatus);
  }
});

Refléter les achats de l'utilisateur

Lorsqu'un utilisateur interroge votre action, l'objet user de la requête JSON inclut une 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:

  "user": {
    "userId": "xxxx",
    "locale": "en-US",
    "lastSeen": "2018-02-09T01:49:23Z",
    "packageEntitlements": [
      {
        "packageName": "com.digitalgoods.application",
        "entitlements": [
          {
            "sku": "non-consumable.1",
            "skuType": "APP"
          }
          {
            "sku": "consumable.2",
            "skuType": "APP"
          }
        ]
      },
      {
        "packageName": "com.digitalgoods.application",
        "entitlements": [
          {
            "sku": "annual.subscription",
            "skuType": "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=="
            }
          }
        ]
      }
    ]
  },
  "conversation": {
    "conversationId": "1518141160297",
    "type": "NEW"
  },
  "inputs": [
    {
      "intent": "actions.intent.MAIN",
      "rawInputs": [
        {
          "inputType": "VOICE",
          "query": "Talk to My Test App"
        }
      ]
    }
  ],
  ...
}