Ce guide explique comment ajouter des transactions numériques à votre conversation Action pour que les utilisateurs puissent acheter vos produits numériques non consommables.
Termes clés: un produit numérique non consommable est un SKU qui gère les stocks ne peut être acheté qu'une seule fois, comme l'accès payant à des contenus supplémentaires dans une action. ou Android. Ce type de produit est différent d'un consommable bien que vous puissiez l'acheter, l'utiliser et le racheter.
Pour en savoir plus sur les produits ponctuels non consommables, consultez le documentation sur fonctionnalités ponctuelles spécifiques au produit.
Flux de transactions
Ce guide décrit chaque étape de développement au fur et à mesure qu'elles se produisent dans le cas d'un produit numérique. le flux des transactions. Lorsque votre action gère des transactions pour des produits numériques, elle utilise le flux suivant:
- Configurez un client API d'achats numériques: votre action utilise le code Achats pour communiquer avec votre inventaire Google Play et effectuer des transactions. Avant d'effectuer toute autre action, votre action crée un client JWT avec une clé pour communiquer avec l'API des achats numériques.
- Recueillir des informations: votre action collecte des informations de base sur le
et votre inventaire Google Play pour préparer une transaction.
- Valider les exigences concernant les transactions: votre action utilise l'ID les exigences relatives aux transactions au début du parcours d'achat pour pour s'assurer que l'utilisateur peut effectuer une transaction.
- Rassembler l'inventaire disponible: votre action vérifie votre inventaire et identifie les articles actuellement disponibles à l’achat.
- Créez l'ordre: votre action présente les produits numériques disponibles aux l'utilisateur afin qu'il puisse en choisir un à acheter.
- Finaliser l'achat : votre action utilise l'API des achats numériques pour : effectuer un achat sur le Google Play Store à partir du choix de l'utilisateur ;
- Gérez le résultat: votre action reçoit un code d'état pour le paramètre transaction et notifie l'utilisateur que l'achat a abouti (ou nécessite des étapes supplémentaires).
Restrictions et consignes relatives aux avis
Des règles supplémentaires s'appliquent aux actions comportant des transactions. Cela peut nous prendre quelques afin d'examiner les actions incluant des transactions. planifier votre calendrier de publication. Pour faciliter le processus d'examen, assurez-vous de respecter avec le Règles et consignes concernant les transactions avant de soumettre votre action pour examen.
Les actions qui vendent des 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
Prérequis
Avant d'intégrer des transactions numériques dans votre action, vous devez conditions préalables suivantes:
A compte de développeur et un compte marchand sur Google Play, pour gérer vos produits numériques Google Play Console :
Un domaine Web validées dans la Google Search Console. Il n'a pas besoin d'être associé à un site Web public. il suffit de référencer votre domaine Web.
Une application Android avec l'
com.android.vending.BILLINGautorisation dans la Google Play Console. Vos produits numériques seront des "achats via une application" associées à cette application dans la Google Play Console.Vous devez également créer une version dans la Play Console avec cette application, mais si si vous ne voulez pas que la version soit publique, créez une version alpha fermée version.
Si vous n'avez pas encore d'application Android, suivez les Associer des instructions pour une application Android
Un ou plusieurs produits gérés dans le Google Play Console Il s'agit des produits numériques vendus avec votre action. Notez que vous devez ne peuvent pas créer de produits gérés dans la Play Console tant que vous n'avez pas configuré Conditions préalables à l'utilisation de l'application Android
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 d'application Android disposant de l'autorisation de facturation dans le dans la Google Play Console, procédez comme suit:
- Dans Android Studio ou l'IDE Android de votre choix, créez un projet. Choisir des options dans les invites de configuration du projet pour créer une application très basique.
- Attribuez au projet un nom de package, tel que
com.mycompany.myapp. Ne laissez pas ce nom par défaut, car vous ne pouvez pas importer de packages qui inclurecom.exampleà la Play Console. - Ouvrez le fichier
AndroidManifest.xmlde votre application. Ajoutez la ligne de code suivante dans l'élément
manifest:<uses-permission android:name="com.android.vending.BILLING" />Votre fichier
AndroidManifest.xmldoit se présenter comme suit:<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:
- Accédez à Build (Compilation), puis à Generate Signed Bundle / APK (Générer un app bundle/APK signé).
- Cliquez sur Suivant.
- Sous Key Store Path (Chemin du keystore), cliquez sur Create new (Créer).
- Renseignez chaque champ, puis cliquez sur OK. Notez votre Key Store mot de passe et Mot de passe de la clé, et conservez-les en lieu sûr, vous les utiliserez plus tard.
- Cliquez sur Suivant.
- Sélectionnez Release (Version).
- Sélectionnez V1 (Signature JAR).
- Cliquez sur Terminer.
- Après quelques secondes, Android Studio génère un fichier
app-release.apk. Localisez ce fichier pour une utilisation ultérieure.
Dans Google Play Console créer une application.
Accédez à Versions de l'application.
Sous Versions fermées, sélectionnez Gérer, puis Alpha.
Cliquez sur le bouton Créer une version.
Sous Laisser Google gérer et protéger votre clé de signature, saisissez votre identifiant les informations clés.
Importez votre fichier APK.
Cliquez sur Enregistrer.
Créer vos produits numériques
Si vous n'avez actuellement aucun produit numérique dans la Play Console, suivez ces étapes:
- Dans 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 pour votre produit numérique. Notez l'identifiant produit, C'est ainsi que vous utiliserez ce produit à partir de votre action.
- Cliquez sur Enregistrer.
- Répétez les étapes 2 à 4 pour chaque produit que vous souhaitez vendre.
Préparer votre projet Actions
Une fois votre contenu numérique configuré dans la Google Play Console, vous devez activer transactions numériques et associer votre projet Actions à votre application Play.
Configuration
Pour activer les transactions de produits numériques dans votre projet Actions, procédez comme suit : étapes:
- Dans la console Actions, ouvrez votre projet ou créez-en un.
- Accédez à Déployer, puis à Informations sur l'annuaire.
- Sous Informations supplémentaires et Transactions, cochez la case Oui.
sous Vos actions utilisent-elles l'API d'achat numérique pour effectuer des transactions ?
de produits numériques.
- Cliquez sur Enregistrer.
Créer une clé API pour le contenu numérique
Pour envoyer des requêtes à l'API Digital Goods, vous devez télécharger un service JSON associée à votre projet dans la console Actions.
Pour récupérer votre clé de 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, qui remplace "
<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 Service clé de compte Google Ads.
- Accédez à Compte de service, puis cliquez sur Nouveau compte de service.
- Nommez le 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é de compte de service JSON.
Enregistrez cette clé de compte de service en lieu sûr. Vous utiliserez cette clé dans votre fulfillment pour créer un client pour l'API des achats numériques.
Se connecter à votre inventaire Play
Pour accéder à vos produits numériques à partir d'un projet Actions, associez votre domaine Web et application avec votre projet en tant que propriétés connectées.
Pour associer le domaine Web et l'application Play Console à votre projet Actions, procédez comme suit : 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:
- Cliquez sur le bouton du site Web (</>).
- Saisissez l'URL de votre domaine Web, puis cliquez sur Se connecter.
Google envoie un e-mail contenant des instructions supplémentaires à la personne validé pour ce domaine Web Google Search Console : Une fois que le destinataire de cet e-mail a suivi ces étapes, le site Web doit s'affichent sous Validation de la marque.
Une fois que vous avez au moins un site Web connecté, procédez comme suit pour connectez votre application Android:
- Dans la console Actions, accédez à Déployer, puis à Validation de la marque.
- Cliquez sur Associer une application.
Sur la page qui s'affiche, suivez les instructions pour valider votre site Web. domaine dans la Play Console. Sélectionnez l'application Play contenant votre produits numériques, puis saisissez l'URL du domaine Web exactement telle qu'elle apparaît sur le Page Validation de la marque.
Une fois encore, Google envoie un e-mail de validation au propriétaire confirmé de le domaine. Une fois la validation approuvée, votre application Play s'affichent sous Validation de la marque.
Activez l'option Accéder aux achats sur Play.
Créer votre parcours d'achat
Une fois votre projet Actions et votre inventaire de produits numériques préparés, élaborez une stratégie dans le flux d'achat de produits dans votre webhook de traitement des conversations.
1. Configurer un client API d'achats numériques
Dans votre webhook de fulfillment de conversation, créez un client JWT avec votre service
la clé JSON du compte
https://www.googleapis.com/auth/actions.purchases.digital.
Le code Node.js suivant crée un client JWT pour l'API des achats numériques:
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 l'élément la capacité de l'utilisateur à effectuer des achats et quels produits sont disponibles sur votre de l'inventaire.
2. a. Valider les exigences concernant les achats numériques
Il est recommandé de s'assurer que
le compte de l'utilisateur est configuré pour
des transactions avant de leur donner la possibilité d'effectuer un achat. Vous devez
une transition vers une scène DigitalPurchaseCheck, qui vérifie que l'utilisateur est validé,
qu'ils effectuent la transaction sur une surface autorisée (écran connecté,
ou Android) et qu'ils se trouvent dans un pays où la technologie
les transactions sont prises en charge.
Pour créer une scène de contrôle des achats numériques, procédez comme suit:
- Depuis l'onglet Scenes (Scènes), ajoutez une scène nommée
DigitalPurchaseCheck. - Sous Remplissage de cases, cliquez sur + pour ajouter un emplacement.
- Sous Sélectionner un type, choisissez
actions.type.DigitalPurchaseCheckResult. le type d'emplacement. - Dans le champ "Nom de l'emplacement", attribuez le nom
DigitalPurchaseCheckà l'emplacement. - Cochez la case Personnaliser l'écriture de la valeur de l'emplacement (activée par défaut).
- Cliquez sur Enregistrer.
La validation des achats en ligne peut entraîner l'un des résultats suivants:
- Si les conditions sont remplies, le paramètre de session est défini avec succès. 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 recentrer la conversation de l'expérience transactionnelle ou mettre fin à la conversation.
Pour gérer un résultat de chèque d'achat numérique, procédez comme suit:
- Dans l'onglet Scenes (Scènes), sélectionnez la scène
DigitalPurchaseCheckque vous venez de créer. - Sous Condition, cliquez sur + pour ajouter une condition.
Dans le champ de texte, saisissez la syntaxe de condition suivante pour vérifier la valeur condition de réussite:
scene.slots.status == "FINAL" && session.params.DigitalPurchaseCheck.resultType == "CAN_PURCHASE"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".Activez l'option Send invites (Envoyer des invites) et fournissez une invite simple pour avertir l'utilisateur. il est prêt à effectuer une transaction:
candidates: - first_simple: variants: - speech: >- You are ready to purchase digital goods.Sous Transition, sélectionnez une autre scène, ce qui permet à l'utilisateur de continuer. la conversation et de procéder à la transaction.
Sélectionnez la condition
else if scene.slots.status == "FINAL".Activez l'option Send invites (Envoyer des invites) et fournissez une invite simple pour avertir l'utilisateur. s'il n'est pas en mesure d'effectuer une transaction:
candidates: - first_simple: variants: - speech: Sorry you cannot perform a digital purchase.Sous Transition, sélectionnez End conversation (Terminer la conversation) pour mettre fin à la conversation.
2. b. Rassembler l'inventaire disponible
Utiliser l'API des achats numériques pour demander le Play Store actuellement disponible dans un inventaire, puis nous l'intégrons dans un tableau d'objets JSON pour chaque produit. Vous référencerez ce tableau plus tard pour montrer à l'utilisateur les options disponibles. à acheter.
Chacun de vos articles numériques est représenté par un SKU au format JSON. La Le code Node.js suivant décrit le formatage attendu pour chaque 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 à
https://actions.googleapis.com/v3/packages/{packageName}/skus:batchGet
point de terminaison, où {packageName} correspond au nom du package de votre application dans
console (par exemple, com.myapp.digitalgoods), puis mettez en forme le résultat dans un
d'objets SKU.
Pour ne récupérer que des produits numériques spécifiques dans le tableau obtenu, listez le produit
Les identifiants de produits numériques (tels qu'ils apparaissent sous chaque produit intégré dans
Console) que vous souhaitez rendre disponible à l'achat dans body.ids.
Le code Node.js suivant demande la liste des produits disponibles API Achats 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': ['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 une liste de vos produits numériques. disponibles à l'achat. Vous pouvez utiliser différents types de réponses enrichies pour représenter et inviter l'utilisateur à faire une sélection.
Le code Node.js suivant lit un tableau d'inventaire d'objets SKU et crée un Réponse "list" avec un élément de liste pour chacun:
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 l'ordre. Pour ce faire, l'emplacement associé à l'élément sélectionné, vous pouvez appeler votre webhook créer la commande. À partir du traitement, enregistrez les données de commande dans une session. . L'objet d'ordre est utilisé dans toutes les scènes pour la 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 plutôt utiliser l'éditeur JSON pour configurer l'emplacement
avec l'objet "order" ci-dessus. Les deux implémentations utilisent le même format pour
CompletePurchaseValueSpec, disponible dans la
Documentation de référence sur la charge utile du webhook JSON
4. Finaliser l'achat
Une fois que l'utilisateur a sélectionné un article, vous pouvez finaliser l'achat. Une fois que vous avez rempli l'emplacement associé à l'élément sélectionné, vous devez passer à une scène effectue un achat complet.
Créer une scène d'achat complet
- Dans l'onglet Scenes (Scènes), ajoutez une scène nommée
CompletePurchase. - Sous Remplissage de cases, cliquez sur + pour ajouter un emplacement.
- Sous Sélectionner un type, choisissez
actions.type.CompletePurchaseValuele type d'emplacement. - Dans le champ "Nom de l'emplacement", attribuez le nom
CompletePurchaseà l'emplacement. - Cochez la case Personnaliser l'écriture de la valeur de l'emplacement (activée par défaut).
- Sous Configurer l'emplacement, sélectionnez
Use session parameterdans le menu déroulant. - Sous Configurer l'emplacement,saisissez le nom du paramètre de session utilisé pour
enregistrer la commande dans le champ de texte (par exemple,
$session.params.purchase).
- Cliquez sur Enregistrer.
5. Gérer le résultat
Un emplacement de type actions.type.CompletePurchaseValue peut avoir les éléments suivants :
résultats:
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 l'historique et d'adapter les articles présentés afin qu'ils n'aient pas la possibilité racheter des articles qu'ils possèdent déjà.PURCHASE_STATUS_ITEM_UNAVAILABLE: la transaction a échoué, car le l'élément demandé n'est pas disponible. Pour éviter cette erreur, vérifiez les SKU plus proches du moment de l'achat.PURCHASE_STATUS_ITEM_CHANGE_REQUESTED: la transaction a échoué, car le l'utilisateur a décidé d'acheter autre chose. Relancer la création de votre 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. Puisque l'utilisateur a quitté prématurément le flux, Demander à l'utilisateur s'il souhaite réessayer ou quitter la transaction dans son ensemble.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 autorisant l'utilisateur sait que la transaction a échoué et lui demande s'il veut réessayer.
Vous devez gérer chacun de ces résultats à partir de votre scène CompletePurchase.
- Dans l'onglet Scenes (Scènes), sélectionnez la scène
CompletePurchaseque vous venez de créer. - Sous Condition, cliquez sur + pour ajouter une condition.
Dans le champ de texte, saisissez la syntaxe de condition suivante pour vérifier la valeur condition de réussite:
scene.slots.status == "FINAL" && session.params.CompletePurchase.purchaseStatus == "PURCHASE_STATUS_OK"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".Activez l'option Send invites (Envoyer des invites) et fournissez une invite simple pour avertir l'utilisateur. il est prêt à effectuer une transaction:
candidates: - first_simple: variants: - speech: >- Your purchase was successful.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 proposer.
reflètent les achats de l'utilisateur ;
Lorsqu'un utilisateur interroge votre action, l'objet user de la requête JSON inclut un
la liste de leurs achats. Vérifiez ces informations et modifiez
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 précédents achats via une application qu'ils ont effectués pour
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:
- Dans la console Actions, cliquez sur Test (Tester) dans le menu de navigation.
- Cliquez sur Paramètres.
- Activez l'option Bac à sable de développement.