Questa guida spiega come aggiungere transazioni digitali all'azione conversazionale, in modo che gli utenti possano acquistare i tuoi beni digitali non consumabili.
Termini chiave: un bene digitale non consumabile è uno SKU (stock-keeping unit) che può essere acquistato una sola volta, ad esempio l'accesso a pagamento a contenuti aggiuntivi in un'app per Android o di un'azione. Questo tipo di prodotto è diverso da un bene digitale di consumo che può essere acquistato, utilizzato e riacquistato.
Per ulteriori informazioni sui prodotti monouso non consumabili, consulta la documentazione di Android sulle funzionalità specifiche del prodotto una tantum.
Limitazioni e linee guida per le recensioni
Norme aggiuntive si applicano alle Azioni con transazioni. Possono essere necessarie alcune settimane per esaminare le azioni che includono transazioni, quindi tieni conto di questo tempo quando pianifichi la pianificazione delle pubblicazioni. Per facilitare la procedura di revisione, assicurati di rispettare le norme e le linee guida per le transazioni prima di inviare l'Azione per la revisione.
Le azioni che vendono beni 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 descrive ogni fase dello sviluppo nel flusso di transazioni di prodotti digitali. Quando l'Azione gestisce le transazioni per i beni digitali, utilizza il seguente flusso:
- Configura un client API Digital Subscriptions. L'Azione utilizza l'API Digital Purchases per comunicare con il tuo inventario di Google Play ed effettuare transazioni. Prima che l'Azione faccia altro, crea un client JWT con una chiave di servizio per comunicare con l'API DigitalPurchases.
- Raccogliere informazioni. L'Azione raccoglie informazioni di base sull'utente e sul tuo inventario di Google Play per preparare una transazione.
- Convalida dei requisiti delle transazioni: l'Azione utilizza l'helper per i requisiti delle transazioni digitali all'inizio del flusso di acquisto per garantire che l'utente possa effettuare transazioni.
- Raccogliere l'inventario disponibile. L'Azione controlla il tuo inventario Google Play e identifica quali articoli sono attualmente disponibili per l'acquisto.
- Crea l'ordine: l'azione presenta i beni digitali disponibili all'utente in modo che possa selezionarne uno da acquistare.
- Completare l'acquisto: l'Azione utilizza l'API DigitalPurchases per avviare un acquisto sul Google Play Store con la selezione dell'utente.
- Gestire il risultato: l'Azione riceve un codice di stato della transazione e avvisa l'utente che l'acquisto è riuscito (o richiede passaggi aggiuntivi).
Prerequisiti
Prima di incorporare le transazioni digitali nell'Azione, devi disporre dei seguenti prerequisiti:
Un account sviluppatore e un account commerciante su Google Play per gestire i tuoi prodotti digitali in Google Play Console.
Un dominio web verificato in Google Search Console. Non è necessario che questo dominio sia associato a un sito web disponibile pubblicamente, basta fare riferimento al tuo dominio web.
Un'app Android con l'autorizzazione
com.android.vending.BILLINGin Google Play Console. I tuoi prodotti digitali saranno "acquisti in-app" associati a questa app in Google Play Console.Devi anche creare una release in Play Console con questa app, ma se non vuoi che la release sia pubblica puoi creare una release alpha chiusa.
Se non hai ancora un'app per Android, segui le istruzioni per associare un'app Android.
Uno o più prodotti gestiti in Google Play Console, ovvero i prodotti digitali che vendi con l'Azione. Tieni presente che non puoi creare prodotti gestiti in Play Console finché non configuri il prerequisito delle app per Android.
Se non hai già prodotti gestiti, segui le istruzioni per la creazione di beni digitali.
Associa un'app Android
Se al momento non hai un'app Android con l'autorizzazione per la fatturazione in Google Play Console, segui questi passaggi:
- In Android Studio o nell'IDE per Android che preferisci, crea un nuovo progetto. Scegli le opzioni nei prompt di configurazione del progetto per creare un'app molto semplice.
- Assegna al progetto un nome pacchetto, ad esempio
com.mycompany.myapp. Non lasciare questo nome come predefinito, dato che non puoi caricare in Play Console i pacchetti che includonocom.example. - 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 tuo 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 Build, Genera bundle / APK firmato.
- Fai clic su Avanti.
- In Percorso archivio chiavi, fai clic su Crea nuovo.
- Compila ciascun campo e poi fai clic su OK. Prendi nota della password dell'archivio chiavi e della password della chiave e conservali in un luogo sicuro, poiché utilizzerai questi dati in seguito.
- Fai clic su Avanti.
- Seleziona Rilascia.
- Seleziona V1 (firma JAR).
- Fai clic su Fine.
- Dopo qualche secondo, Android Studio genera un file
app-release.apk. Individua questo file per utilizzarlo in seguito.
In Google Play Console, crea una nuova applicazione.
Vai a Release dell'app.
In Gruppi 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 le informazioni relative alla chiave di firma.
Carica il file APK.
Fai clic su Salva.
Crea i tuoi prodotti digitali
Se al momento non disponi di beni digitali in Play Console, procedi nel seguente modo:
- In Google Play Console, vai a Prodotti in-app e poi a Prodotti gestiti. Se viene visualizzato un avviso, segui le istruzioni precedenti per creare un'app Android o fai clic sul link per creare un profilo commerciante.
- Fai clic su Crea prodotto gestito.
- Compila i campi del prodotto digitale. Prendi nota dell'ID prodotto, che serve a fare riferimento a questo prodotto nell'Azione.
- Fai clic su Salva.
- Ripeti i passaggi 2-4 per ogni prodotto che vuoi vendere.
Prepara il progetto Actions
Dopo aver configurato i tuoi prodotti digitali in Google Play Console, devi abilitare le transazioni digitali e associare il tuo progetto Actions alla tua app Google Play.
Per attivare le transazioni su beni digitali nel tuo progetto Actions, segui questi passaggi:
- Nella Console di Actions, apri il tuo progetto o creane uno nuovo.
- Vai a Esegui il deployment, quindi a Informazioni sulla directory.
- In Informazioni aggiuntive e Transazioni, seleziona la casella Sì in Le tue azioni utilizzano l'API Digital Purchase per eseguire transazioni di beni digitali.
- Fai clic su Salva.
Creare una chiave API per prodotti digitali
Per inviare richieste all'API di beni digitali, devi scaricare una chiave dell'account di servizio JSON associata al tuo progetto della console di Actions.
Per recuperare la chiave dell'account di servizio:
- Nella Console di Actions, fai clic sull'icona con tre puntini nell'angolo in alto a destra, quindi su Impostazioni progetto.
- Individua l'ID progetto dell'Azione.
- Segui questo link, sostituendo "
<project_id>" con l'ID del tuo progetto:https://console.developers.google.com/apis/credentials?project=project_id - Nella navigazione principale, vai a Credenziali.
- Nella pagina visualizzata, fai clic su Crea credenziali, quindi su Chiave account di servizio.
- Vai ad Account di servizio e fai clic su Nuovo account di servizio.
- Assegna all'account di servizio un nome, ad esempio 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 nel fulfillment per creare un client per l'API Digital purchase.
Collegarsi all'inventario Google Play
Per accedere ai tuoi beni digitali da un progetto Actions, associa il tuo dominio web e la tua app al progetto come proprietà collegate.
Nota: il completamento della procedura di collegamento può richiedere fino a una settimana mentre verifichiamo le tue proprietà. Se il tuo sito web o la tua app non vengono collegati dopo questo periodo di tempo, contatta l'assistenza.
Per connettere il dominio web e l'app Play Console al progetto Actions, segui questi passaggi:
- Nella Console di Actions, vai a Deployment e poi a Verifica del brand.
Se non hai collegato alcuna proprietà, collega prima un sito web:
- Fai clic sul pulsante della proprietà web (</>).
- Inserisci l'URL del tuo dominio web e fai clic su Connetti.
Google invia un'email con ulteriori istruzioni alla persona che ha verificato per il dominio web in questione in Google Search Console. Una volta che il destinatario di questa email avrà eseguito questi passaggi, il sito web dovrebbe apparire nella sezione Verifica del brand.
Dopo aver collegato almeno un sito web, procedi nel seguente modo per connettere la tua app Android:
- Nella Console di Actions, vai a Deployment e poi a Verifica del brand.
- Fai clic su Collega app.
Nella pagina visualizzata, segui le istruzioni per verificare il tuo dominio web in Play Console. Seleziona l'app Play che contiene i tuoi prodotti digitali e inserisci l'URL del dominio web esattamente come viene visualizzato nella pagina Verifica del brand.
Ancora una volta, Google invia un'email di verifica al proprietario verificato del dominio. Una volta approvata la verifica, l'app Google Play dovrebbe essere visualizzata nella sezione Verifica del brand.
Attiva l'opzione Accedi agli acquisti di Google Play.
Crea il tuo flusso di acquisto
Una volta preparato il progetto Actions e l'inventario dei beni digitali, crea un flusso di acquisto di beni digitali nel webhook di fulfillment delle conversazioni.
1. Configura un client API Digital Subscriptions
Nel webhook di fulfillment della conversazione, crea un client JWT con la chiave JSON del tuo account di servizio e l'ambito https://www.googleapis.com/auth/actions.purchases.digital.
Il seguente codice Node.js crea un client JWT per l'API DigitalPurchases:
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 sulla capacità dell'utente di effettuare acquisti e sui prodotti disponibili nel tuo inventario.
2. a. Convalida i requisiti delle transazioni
È buona norma assicurarsi che l'account dell'utente sia configurato per eseguire le transazioni prima di offrire all'utente la possibilità di effettuare un acquisto. Questo passaggio include verificare che l'utente abbia configurato un metodo di pagamento e che si trovi in un'area geografica in cui sono supportate le transazioni digitali. All'inizio del flusso di transazioni, utilizza l'helper DIGITAL_PURCHASE_CHECK per convalidare la configurazione della transazione dell'utente con l'assistente.
Il seguente codice Node.js utilizza DIGITAL_PURCHASE_CHECK all'inizio della 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 questo controllo negli argomenti della conversazione come DIGITAL_PURCHASE_CHECK_RESULT. In base a questo risultato, continua il flusso della transazione o passa da un punto all'altro e chiedi agli utenti di verificare la configurazione di Google Pay.
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. Raccogliere l'inventario disponibile
Utilizza l'API Digital purchase per richiedere l'inventario del Play Store attualmente disponibile, quindi crealo in un array di oggetti JSON per ogni prodotto. Farai 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. 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 all'endpoint https://actions.googleapis.com/v3/packages/{packageName}/skus:batchGet, dove {packageName} è il nome del pacchetto dell'app in Google Play Console (ad esempio, com.myapp.digitalgoods), e formatta il risultato in un array di oggetti SKU.
Per recuperare soltanto prodotti digitali specifici nell'array risultante, elenca gli ID prodotto dei prodotti digitali (indicati 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 di beni disponibili dall'API Digital purchases e formatta il risultato come 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': ['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. Crea l'ordine
Per avviare l'acquisto digitale dell'utente, presenta un elenco dei tuoi prodotti digitali disponibili per l'acquisto. Puoi utilizzare una varietà di tipi di risposte avanzate per rappresentare il tuo stock e richiedere all'utente di effettuare una selezione.
Il seguente codice Node.js legge un array di inventario di oggetti SKU e crea una risposta dell'elenco con un elemento dell'elenco per ciascuno:
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 l'elemento selezionato dall'utente.
Il seguente codice Node.js gestisce la selezione di SKU dell'utente da una risposta dell'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
Al termine dell'acquisto, attiva l'actions_intent_COMPLETE_PURCHASE
evento Dialogflow (o actions.intent.COMPLETE_PURCHASE intent SDK Actions) con
un argomento COMPLETE_PURCHASE_VALUE che descrive il risultato. Crea un intent, attivato 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. A questo punto la transazione è completata, quindi esci dal flusso transazionale e passa di nuovo alla conversazione.PURCHASE_STATUS_ALREADY_OWNED: la transazione non è riuscita perché l'utente è già proprietario dell'articolo. Per evitare questo errore, controlla gli acquisti precedenti dell'utente e personalizza gli articoli mostrati in modo che non possa acquistare di nuovo gli articoli che già possiede.PURCHASE_STATUS_ITEM_UNAVAILABLE: la transazione non è andata a buon fine perché l'articolo richiesto non è disponibile. Per evitare questo errore, controlla gli SKU disponibili più vicino al momento dell'acquisto.PURCHASE_STATUS_ITEM_CHANGE_REQUESTED: la transazione non è riuscita perché l'utente ha deciso di acquistare qualcos'altro. Rispondi subito con la creazione dell'ordine in modo che l'utente possa prendere subito un'altra decisione.PURCHASE_STATUS_USER_CANCELLED: la transazione non è riuscita perché l'utente ha annullato il flusso di acquisto. Poiché l'utente è uscito prematuramente dal flusso, chiedi all'utente se vuole ritentare la transazione o uscire del tutto.PURCHASE_STATUS_ERROR: la transazione non è andata a buon fine per un motivo sconosciuto. Comunica all'utente 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, che ha causato uno stato sconosciuto. Gestisci questo stato di errore informando l'utente che la transazione non è andata a buon fine e chiedi 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);
}
});
Riflettere gli acquisti dell'utente
Quando un utente esegue una query sull'Azione, l'oggetto JSON della richiesta user include un elenco dei suoi 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 degli acquisti in-app precedenti effettuati per il 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"
}
]
}
],
...
}