Questa guida spiega come aggiungere transazioni di abbonamenti digitali ai tuoi colloqui Azione, per consentire agli utenti di acquistare i tuoi abbonamenti.
Termini chiave: un prodotto digitale associato a un abbonamento è un codice SKU (codice identificativo dell'articolo) che richiede un addebito ricorrente per l'utente, ad esempio una rivista online. Questo è diverso da un bene digitale consumabile che l'utente deve manualmente riacquistare o un bene digitale non consumabile che viene automaticamente acquistato una sola volta.
Per ulteriori informazioni sugli abbonamenti digitali, fai riferimento all' documentazione su funzionalità specifiche dell'abbonamento.
Limitazioni e linee guida per la revisione
Alle Azioni con transazioni si applicano norme aggiuntive. Possono essere necessari settimane per esaminare le Azioni che includono transazioni, quindi tieni conto di questo pianificare le pubblicazioni. Per semplificare la procedura di revisione, assicurati di rispettare le con norme e linee guida per le transazioni prima di inviare l'Azione per la revisione.
Le azioni che vendono prodotti digitali possono essere implementate solo nei seguenti paesi:
- Australia
- Brasile
- Canada
- Indonesia
- Giappone
- Messico
- Russia
- Singapore
- Thailandia
- Turchia
- Regno Unito
- Stati Uniti
Flusso delle transazioni
Questa guida illustra ogni fase dello sviluppo man mano che si verificano in un prodotto digitale delle transazioni online. Quando l'Azione gestisce le transazioni per prodotti digitali, usa la seguente procedura:
- Configura un client API per gli acquisti digitali: l'azione utilizza le tecnologie digitali API per gli acquisti per comunicare con il tuo inventario di Google Play ed effettuare transazioni. Prima di eseguire qualsiasi altra azione, l'azione crea un client JWT con un chiave di servizio per comunicare con l'API degli acquisti digitali.
- Raccogliere informazioni: l'azione raccoglie informazioni di base sul
e il tuo inventario di Google Play per prepararti a una transazione.
- Convalida i requisiti delle transazioni: l'Azione utilizza le dei requisiti per le transazioni all'inizio del flusso di acquisto per assicurarti che l'utente possa effettuare transazioni.
- Raccogli l'inventario disponibile: l'azione controlla il tuo Google Play inventario e identifica quali articoli sono attualmente disponibili per l'acquisto.
- Crea l'ordine: l'azione presenta i prodotti digitali disponibili a l'utente, in modo che possa selezionarne uno da acquistare.
- Completare l'acquisto: l'azione utilizza l'API per gli acquisti digitali per avvii un acquisto con la selezione dell'utente sul Google Play Store.
- Gestire il risultato: l'azione riceve un codice di stato per il transazione e avvisa l'utente che l'acquisto è andato a buon fine (o passaggi aggiuntivi).
Prerequisiti
Prima di incorporare le transazioni digitali nell'azione, devi disporre dei seguenti prerequisiti:
R account sviluppatore e un account commerciante su Google Play, per gestire i tuoi prodotti digitali nel Google Play Console
Un dominio web verificate in Google Search Console. Questo dominio non deve essere associato a un sito web lanciato pubblicamente. dobbiamo solo fare riferimento al tuo dominio web.
Un'app per Android con
com.android.vending.BILLINGautorizzazione nella Google Play Console. I tuoi prodotti digitali saranno "acquisti in-app" associate a questa app in Google Play Console.Con questa app dovrai anche creare una release in Play Console, ma se Se preferisci che la release non sia pubblica, puoi creare una versione alpha chiusa di IA generativa.
Se non hai ancora un'app per Android, segui le Istruzioni per l'associazione di un'app per Android.
Uno o più abbonamenti nel Google Play Console ovvero i prodotti digitali che vendi con l'Azione. Tieni presente che non può creare abbonamenti in Play Console finché non configuri il Prerequisito dell'app Android.
Se non hai ancora abbonamenti, segui le Crea le istruzioni per i prodotti digitali.
Associa un'app per Android
Se al momento non disponi di un'app per Android con l'autorizzazione per la fatturazione in Google Play Console:
- In Android Studio oppure l'IDE Android di tua scelta, crea un nuovo progetto. Scegli le opzioni in i prompt di configurazione del progetto per creare un'app di base.
- Assegna al progetto un nome pacchetto, ad esempio
com.mycompany.myapp. Non lasciare questo nome predefinito, in quanto non puoi caricare pacchetti che includicom.examplein Play Console. - Apri il file
AndroidManifest.xmldell'app. Aggiungi la seguente riga di codice all'interno dell'elemento
manifest:<uses-permission android:name="com.android.vending.BILLING" />Il file
AndroidManifest.xmldovrebbe avere l'aspetto del seguente blocco di codice:<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>Crea la tua app come APK firmato. In Android Studio, procedi nel seguente modo:
- Vai a Crea, Genera bundle / APK firmato.
- Fai clic su Avanti.
- In Percorso archivio chiavi, fai clic su Crea nuovo.
- Compila ogni campo e poi fai clic su OK. Prendi nota del tuo negozio chiave e Chiave password e conservale in un luogo sicuro, poiché le utilizzerai in seguito.
- Fai clic su Avanti.
- Seleziona Rilascia.
- Seleziona V1 (firma JAR).
- Fai clic su Fine.
- Dopo alcuni secondi, Android Studio genera un file
app-release.apk. Individua questo file per utilizzarlo in seguito.
Nella Google Play Console per creare una nuova applicazione.
Vai a Release dell'app.
In Canali chiusi, vai a Gestisci e poi ad Alpha.
Fai clic sul pulsante Crea release.
In Consenti a Google di gestire e proteggere la tua chiave di firma, inserisci la tua firma le informazioni più importanti.
Carica il file APK.
Fai clic su Salva.
Crea i tuoi prodotti digitali
Se al momento non disponi di prodotti digitali in Play Console, segui questi passaggi: passaggi:
- Nella Google Play Console vai a Prodotti in-app, quindi su Abbonamenti. Se vedi un avviso, segui le istruzioni precedenti per creare un'app per Android o fai clic sul link per creare un profilo commerciante.
- Fai clic su Crea sottoscrizione.
- Compila i campi per il tuo prodotto digitale. Prendi nota dell'ID prodotto, che è il modo in cui farai riferimento a questo prodotto dall'azione.
- Fai clic su Salva.
- Ripeti i passaggi 2-4 per ciascun prodotto che vuoi vendere.
Prepara il progetto Actions
Dopo aver configurato i prodotti digitali in Google Play Console, devi attivare transazioni digitali e associare il tuo progetto Actions alla tua app Google Play.
Per attivare le transazioni per i prodotti digitali nel progetto Actions, segui questi passaggi passaggi:
- Nella console Actions, apri il tuo progetto o creane uno nuovo.
- Vai a Esegui il deployment, quindi Informazioni sulla directory.
- In Informazioni aggiuntive e Transazioni, seleziona la casella Sì. in Le tue azioni utilizzano l'API Digital Purchase per eseguire transazioni? dei prodotti digitali.
- Fai clic su Salva.
Creare una chiave API per prodotti digitali
Per inviare richieste all'API dei prodotti digitali, devi scaricare un servizio JSON chiave dell'account associata al progetto della console Actions.
Per recuperare la chiave dell'account di servizio, segui questi passaggi:
- Nella console di Actions, fai clic sull'icona con tre puntini nell'angolo in alto a destra. quindi Impostazioni progetto.
- Trova l'ID progetto dell'Azione.
- Fai clic su questo link, sostituendo "
<project_id>" con l'ID del tuo progetto:https://console.developers.google.com/apis/credentials?project=project_id - Nella barra di navigazione principale, vai a Credenziali.
- Nella pagina visualizzata, fai clic su Crea credenziali, quindi su Servizio chiave dell'account di servizio.
- Vai a Account di servizio e fai clic su Nuovo account di servizio.
- Assegna all'account di servizio un nome simile a quello delle transazioni digitali.
- Fai clic su Crea.
- Imposta il Ruolo su Progetto > Proprietario.
- Fai clic su Continua.
- Fai clic su Crea chiave.
- Seleziona il tipo di chiave JSON.
- Fai clic su Crea chiave e scarica la chiave JSON dell'account di servizio.
Salva questa chiave dell'account di servizio in un luogo sicuro. Utilizzerai questa chiave per creare un cliente per l'API degli acquisti digitali.
Connettersi all'inventario di Google Play
Per accedere ai tuoi prodotti digitali da un progetto Actions, associa il tuo dominio web e app con il tuo progetto proprietà collegate.
Nota: il completamento della procedura di collegamento può richiedere fino a una settimana durante la verifica. le tue proprietà. Se al termine di questo periodo il tuo sito web o la tua app non sono collegati, contatta l'assistenza.
Per collegare l'app e il dominio web Play Console al progetto Actions, segui questi passaggi:
- Nella console Actions, vai a Esegui il deployment e poi su Verifica del brand.
Se non hai collegato nessuna proprietà, collega prima un sito web:
- Fai clic sul pulsante proprietà web (</>).
- Inserisci l'URL del tuo dominio web e fai clic su Connetti.
Google invia un'email con ulteriori istruzioni al privato verificato per quel dominio web in Google Search Console. Una volta che il destinatario dell'email avrà eseguito questi passaggi, il sito web vengono visualizzati in Verifica del brand.
Quando hai almeno un sito web collegato, procedi nel seguente modo per collega la tua app Android:
- Nella console Actions, vai a Esegui il deployment e poi su Verifica del brand.
- Fai clic su Collega app.
Nella pagina visualizzata, segui le istruzioni per verificare il tuo sito web dominio su Play Console. Seleziona l'app Google Play che contiene i tuoi prodotti digitali e inserisci l'URL del dominio web esattamente come appare nella Pagina Verifica del brand.
Ancora una volta, Google invia un'email di verifica al proprietario verificato di il dominio. Dopo l'approvazione della verifica, la tua app di Google Play dovrebbe vengono visualizzati in Verifica del brand.
Attiva l'opzione Accedi agli acquisti su Google Play.
Crea il tuo flusso di acquisto
Dopo aver preparato il progetto Actions e l'inventario di prodotti digitali, crea un modello flusso di acquisto dei prodotti nel webhook di evasione delle conversazioni.
1. Configurare un client API per gli acquisti digitali
Nel webhook di completamento delle conversazioni, crea un client JWT con il tuo servizio.
chiave JSON dell'account e
https://www.googleapis.com/auth/actions.purchases.digital ambito.
Il seguente codice Node.js crea un client JWT per l'API degli acquisti digitali:
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. Raccogliere informazioni
Prima che l'utente possa effettuare un acquisto, l'azione raccoglie informazioni sul la capacità dell'utente di effettuare acquisti e quali beni sono disponibili sul tuo inventario.
2. a. Convalida i requisiti delle transazioni
È buona norma assicurarsi che l'account dell'utente sia configurato per funzionare
transazioni, prima di offrire la possibilità di effettuare un acquisto. Questo passaggio
include la verifica che l'utente abbia configurato un metodo di pagamento e che abbia
paese in cui sono supportate le transazioni digitali. All'inizio della transazione
usa l'helper DIGITAL_PURCHASE_CHECK per convalidare la transazione dell'utente
configurazione con l'assistente.
Il seguente codice Node.js utilizza il DIGITAL_PURCHASE_CHECK all'inizio del
conversazione:
app.intent('Default Welcome Intent', async (conv, { SKU }) => {
// Immediately invoke digital purchase check intent to confirm
// purchase eligibility.
conv.ask(new DigitalPurchaseCheck());
});
Trova il risultato di questa verifica negli argomenti della conversazione come
DIGITAL_PURCHASE_CHECK_RESULT. In base a questo risultato, continua
flusso di transazioni o effettuare un passaggio e chiedere di controllare Google Pay
configurazione.
Il seguente codice Node.js gestisce il risultato del controllo dei requisiti :
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. Raccogli l'inventario disponibile
Usa l'API DigitalPurchases per richiedere il tuo Play Store attualmente disponibile e poi integrarlo in un array di oggetti JSON per ogni prodotto. Potrai fare riferimento a questo array in un secondo momento per mostrare all'utente le opzioni disponibili per l'acquisto.
Ciascuno dei tuoi prodotti digitali è rappresentato come uno SKU in formato JSON. La il seguente codice Node.js descrive la formattazione prevista di ogni SKU:
body = {
skus: [
skuId: {
skuType: one of "APP" or "UNSPECIFIED"
id: string,
packageName: string
}
formattedPrice: string,
title: string,
description: string
]
}
Invia una richiesta POST al
https://actions.googleapis.com/v3/packages/{packageName}/skus:batchGet
endpoint, dove {packageName} è il nome del pacchetto dell'app in Google Play
console (ad esempio, com.myapp.digitalgoods) e formatta il risultato in un
di oggetti SKU.
Per recuperare solo prodotti digitali specifici nell'array risultante, indica il prodotto
ID per prodotti digitali (mostrati sotto ogni prodotto in-app in Google Play
Console) che vuoi rendere disponibili per l'acquisto in body.ids.
Il seguente codice Node.js richiede un elenco dei prodotti disponibili dal acquista l'API e formatta il risultato sotto forma di array di 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': ['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. Crea l'ordine
Per avviare l'acquisto digitale dell'utente, presenta un elenco dei tuoi prodotti digitali disponibili per l'acquisto. Puoi utilizzare vari tipi di risposte avanzate per rappresentare i tuoi stock e chiedere all'utente di effettuare una selezione.
Il codice Node.js riportato di seguito legge un array di inventario di oggetti SKU e crea un list response con una voce elenco per ognuno:
skus.forEach((sku) => {
const key = `${sku.skuId.skuType},${sku.skuId.id}`
list.items[key] = {
title: sku.title,
description: `${sku.description} | ${sku.formattedPrice}`,
};
});
4. Completa l'acquisto
Per completare l'acquisto, utilizza l'intent helper COMPLETE_PURCHASE con la
selezionato dall'utente.
Il seguente codice Node.js gestisce la selezione dello SKU dell'utente da una risposta all'elenco
e richiede l'intent COMPLETE_PURCHASE con queste informazioni:
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. Gestire il risultato
Una volta completato l'acquisto, attiva l'actions_intent_COMPLETE_PURCHASE
Evento Dialogflow (o intento dell'SDK actions.intent.COMPLETE_PURCHASE Actions) con
un argomento COMPLETE_PURCHASE_VALUE che descrive il risultato. Sviluppa un intent,
attivati da questo evento, che comunica il risultato all'utente.
Gestisci i seguenti possibili risultati di acquisto:
PURCHASE_STATUS_OK: l'acquisto è andato a buon fine. La transazione è completa a questo punto, quindi esci dal flusso transazionale e torna a la conversazione.PURCHASE_STATUS_ALREADY_OWNED: la transazione non è andata a buon fine perché l'utente possiede già l'elemento. Per evitare questo errore, controlla le informazioni precedenti acquista e personalizza gli articoli mostrati in modo che non abbiano la possibilità di acquistare di nuovo gli articoli che già possiedono.PURCHASE_STATUS_ITEM_UNAVAILABLE: la transazione non è andata a buon fine perché l'elemento richiesto non è disponibile. Per evitare questo errore, controlla le risorse disponibili SKU più vicini al momento dell'acquisto.PURCHASE_STATUS_ITEM_CHANGE_REQUESTED: la transazione non è andata a buon fine perché l'utente ha deciso di acquistare qualcos'altro. Ripeti con la creazione dell'ordine in modo che l'utente possa prendere subito un'altra decisione.PURCHASE_STATUS_USER_CANCELLED: la transazione non è andata a buon fine perché l'utente ha annullato il flusso di acquisto. Dato che l'utente ha abbandonato prematuramente il flusso, chiedi l'utente vuole ritentare la transazione o chiuderla del tutto.PURCHASE_STATUS_ERROR: la transazione non è andata a buon fine per un motivo sconosciuto. Lascia che l'utente sa che la transazione non è andata a buon fine e chiedi se vuole riprovare.PURCHASE_STATUS_UNSPECIFIED: la transazione non è andata a buon fine per un motivo sconosciuto. con conseguente stato sconosciuto. Gestisci questo stato di errore consentendo all'utente sapere che la transazione non è andata a buon fine e chiedere all'utente se vuole riprovare.
Il seguente codice Node.js legge l'argomento COMPLETE_PURCHASE_VALUE e
gestisce ogni risultato:
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);
}
});
Rispecchiare gli acquisti dell'utente.
Quando un utente esegue una query sull'azione, l'oggetto user del file JSON della richiesta include un elenco
dei loro acquisti. Controlla queste informazioni e modifica la risposta dell'Azione
in base ai contenuti pagati dall'utente.
Il seguente codice di esempio mostra l'oggetto user di una richiesta che include
packageEntitlements di acquisti in-app precedenti effettuati per la
Pacchetto 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"
}
]
}
],
...
}