Crea transazioni digitali non consumabili

Questa guida spiega come aggiungere transazioni digitali al tuo account Azione, in modo che gli utenti possano acquistare i tuoi prodotti digitali non consumabili.

Termini chiave: un prodotto digitale non consumabile è un codice SKU (codice identificativo dell'articolo) che possono essere acquistati solo una volta, ad esempio l'accesso a pagamento a contenuti aggiuntivi in un'azione o l'app per Android. Questo tipo di prodotto è diverso da un prodotto digitale di consumo valido che può essere acquistato, utilizzato e riacquistato.

Per ulteriori informazioni sui prodotti a pagamento singolo non consumabili, consulta l' documentazione su funzionalità uniche per prodotti specifici.

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:

  1. 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.
  2. Raccogliere informazioni: l'azione raccoglie informazioni di base sul e il tuo inventario di Google Play per prepararti a una transazione.
    1. 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.
    2. Raccogli l'inventario disponibile: l'azione controlla il tuo Google Play inventario e identifica quali articoli sono attualmente disponibili per l'acquisto.
  3. Crea l'ordine: l'azione presenta i prodotti digitali disponibili a l'utente, in modo che possa selezionarne uno da acquistare.
  4. 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.
  5. Gestire il risultato: l'azione riceve un codice di stato per il transazione e avvisa l'utente che l'acquisto è andato a buon fine (oppure richiede passaggi aggiuntivi).

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
di Gemini Advanced.

Prerequisiti

Prima di incorporare le transazioni digitali nell'Azione, devi disporre dei seguenti prerequisiti:

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:

  1. 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.
  2. Assegna al progetto un nome pacchetto, ad esempio com.mycompany.myapp. Non lasciare questo nome predefinito, in quanto non puoi caricare pacchetti che includi com.example in Play Console.
  3. Apri il file AndroidManifest.xml dell'app.

  4. Aggiungi la seguente riga di codice all'interno dell'elemento manifest:

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

    Il file AndroidManifest.xml dovrebbe 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>

  5. Crea la tua app come APK firmato. In Android Studio, procedi nel seguente modo:

    1. Vai a Crea, Genera bundle / APK firmato.
    2. Fai clic su Avanti.
    3. In Percorso archivio chiavi, fai clic su Crea nuovo.
    4. 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.
    5. Fai clic su Avanti.
    6. Seleziona Rilascia.
    7. Seleziona V1 (firma JAR).
    8. Fai clic su Fine.
    9. Dopo alcuni secondi, Android Studio genera un file app-release.apk. Individua questo file per utilizzarlo in seguito.

  6. Nella Google Play Console per creare una nuova applicazione.

  7. Vai a Release dell'app.

  8. In Canali chiusi, vai a Gestisci e poi ad Alpha.

  9. Fai clic sul pulsante Crea release.

  10. In Consenti a Google di gestire e proteggere la tua chiave di firma, inserisci la tua firma le informazioni più importanti.

  11. Carica il file APK.

  12. Fai clic su Salva.

Crea i tuoi prodotti digitali

Se al momento non disponi di prodotti digitali in Play Console, segui questi passaggi: passaggi:

  1. Nella Google Play Console Vai a Prodotti in-app e poi a Prodotti gestiti. Se vedi un avviso, segui le istruzioni precedenti per creare un'app per Android o fai clic sul link per creare un profilo commerciante.
  2. Fai clic su Crea prodotto gestito.
  3. 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.
  4. Fai clic su Salva.
  5. Ripeti i passaggi 2-4 per ciascun prodotto che vuoi vendere.

Esempi di prodotti non consumabili in Google Play Console.

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.

Configurazione

Per attivare le transazioni per i prodotti digitali nel progetto Actions, segui questi passaggi passaggi:

  1. Nella console Actions, apri il tuo progetto o creane uno nuovo.
  2. Vai a Esegui il deployment, quindi Informazioni sulla directory.
  3. In Informazioni aggiuntive e Transazioni, seleziona la casella Sì. in Le tue azioni utilizzano l'API Digital Purchase per eseguire transazioni? dei prodotti digitali.
  4. 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:

  1. Nella console di Actions, fai clic sull'icona con tre puntini nell'angolo in alto a destra. quindi Impostazioni progetto.
  2. Trova l'ID progetto dell'Azione.
  3. Fai clic su questo link, sostituendo "<project_id>" con l'ID del tuo progetto: https://console.developers.google.com/apis/credentials?project=project_id
  4. Nella barra di navigazione principale, vai a Credenziali.
  5. Nella pagina visualizzata, fai clic su Crea credenziali, quindi su Servizio chiave dell'account di servizio.
  6. Vai a Account di servizio e fai clic su Nuovo account di servizio.
  7. Assegna all'account di servizio un nome simile a quello delle transazioni digitali.
  8. Fai clic su Crea.
  9. Imposta il Ruolo su Progetto > Proprietario.
  10. Fai clic su Continua.
  11. Fai clic su Crea chiave.
  12. Seleziona il tipo di chiave JSON.
  13. 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.

Per collegare l'app e il dominio web Play Console al progetto Actions, segui questi passaggi:

  1. Nella console Actions, vai a Esegui il deployment e poi su Verifica del brand.

  2. Se non hai collegato nessuna proprietà, collega prima un sito web:

    1. Fai clic sul pulsante proprietà web (&lt;/&gt;).
    2. 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.

  3. Quando hai almeno un sito web collegato, procedi nel seguente modo per collega la tua app Android:

    1. Nella console Actions, vai a Esegui il deployment e poi su Verifica del brand.
    2. Fai clic su Collega app.

    3. 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.

    4. Attiva l'opzione Accedi agli acquisti su Google Play.

Immagine che mostra il sito web e le app collegate al progetto Actions.

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 per gli acquisti digitali

È buona norma assicurarsi che l'account dell'utente sia configurato per funzionare transazioni prima di offrire la possibilità di effettuare un acquisto. Dovresti transizione a una scena DigitalPurchaseCheck, che controlla che l'utente sia verificato che stia eseguendo la transazione su una piattaforma consentita (smart display, smart speaker o Android) e che si trovi in un luogo in cui le transazioni sono supportate.

Per creare una scena di controllo di acquisto digitale:

  1. Dalla scheda Scene, aggiungi una nuova scena con il nome DigitalPurchaseCheck.
  2. In Riempimento slot, fai clic su + per aggiungere un nuovo spazio.
  3. In Seleziona tipo, seleziona actions.type.DigitalPurchaseCheckResult come il tipo di slot.
  4. Nel campo del nome dell'area, assegna all'area il nome DigitalPurchaseCheck.
  5. Attiva la casella di controllo Personalizza il writeback del valore dell'area (attiva per impostazione predefinita).
  6. Fai clic su Salva.

Una verifica dell'acquisto digitale avrà come risultato uno dei seguenti risultati:

  • Se i requisiti sono soddisfatti, il parametro di sessione viene impostato con esito positivo e potrai consentire all'utente di acquistare prodotti digitali.
  • Se non è possibile soddisfare uno o più requisiti, il parametro sessione viene impostato con una condizione di errore. In questo caso, devi modificare la conversazione dall'esperienza transazionale o terminare la conversazione.

Per gestire il risultato di un controllo di acquisto digitale:

  1. Dalla scheda Scene, seleziona la scena DigitalPurchaseCheck appena creata.
  2. In Condizione, fai clic su + per aggiungere una nuova condizione.

  3. Nel campo di testo, inserisci la seguente sintassi della condizione per verificare condizione di operazione riuscita:

    scene.slots.status == "FINAL" && session.params.DigitalPurchaseCheck.resultType == "CAN_PURCHASE"

  4. Passa il mouse sopra la condizione appena aggiunta e fai clic sulla Freccia su per posizionarlo prima di if scene.slots.status == "FINAL".

  5. Attiva l'opzione Invia prompt e fornisci un messaggio semplice per informare l'utente sono pronti a effettuare una transazione:

    candidates:
  - first_simple:
      variants:
        - speech: >-
            You are ready to purchase digital goods.

  6. In Transizione, seleziona un'altra scena per consentire all'utente di continuare. la conversazione e procedere con la transazione.

  7. Seleziona la condizione else if scene.slots.status == "FINAL".

  8. Attiva l'opzione Invia prompt e fornisci un messaggio semplice per informare l'utente non sono in grado di effettuare una transazione:

    candidates:
  - first_simple:
      variants:
        - speech: Sorry you cannot perform a digital purchase.

  9. In Transizione, seleziona Termina conversazione per terminarla.

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 "SKU_TYPE_IN_APP" or "SKU_TYPE_SUBSCRIPTION"
      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': 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. 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:

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,
}));

Crea acquisto dalla selezione dell'utente

Dopo che l'utente seleziona un articolo, puoi creare l'ordine. Per farlo, area associata all'elemento selezionato, puoi richiamare il webhook per per creare l'ordine. Dopo l'evasione dell'ordine, salva i dati dell'ordine in una sessione . L'oggetto Order viene utilizzato in più scene per la stessa sessione.

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": ""
};

In Actions Builder, puoi invece utilizzare l'editor JSON per configurare l'area con l'oggetto ordine sopra indicato. Entrambe le implementazioni utilizzano lo stesso formato CompletePurchaseValueSpec, che puoi trovare nella Riferimento al payload per il webhook JSON.

4. Completa l'acquisto

Una volta che l'utente seleziona un articolo, puoi completare l'acquisto. Una volta compilata la allo spazio associato all'elemento selezionato, devi passare a una scena che esegue un acquisto completo.

Crea scena di acquisto completo

  1. Dalla scheda Scene, aggiungi una nuova scena con il nome CompletePurchase.
  2. In Riempimento slot, fai clic su + per aggiungere un nuovo spazio.
  3. In Seleziona tipo, seleziona actions.type.CompletePurchaseValue come tipo di slot.
  4. Nel campo del nome dell'area, assegna all'area il nome CompletePurchase.
  5. Attiva la casella di controllo Personalizza il writeback del valore dell'area (attiva per impostazione predefinita).
  6. In Configura slot, seleziona Use session parameter dal menu a discesa.
  7. In Configura slot,inserisci il nome del parametro di sessione utilizzato archiviare l'ordine nel campo di testo (ad es. $session.params.purchase).
  8. Fai clic su Salva.

5. Gestire il risultato

Un'area di tipo actions.type.CompletePurchaseValue può avere quanto segue risultati:

  • PURCHASE_STATUS_OK: l'acquisto è andato a buon fine. La transazione è completato 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 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. Poiché l'utente ha abbandonato prematuramente il flusso, chiedi all'utente se vuole ritentare la transazione o chiuderla del tutto.
  • PURCHASE_STATUS_ERROR: la transazione non è andata a buon fine per un motivo sconosciuto. Fai sapere all'utente che la transazione non è andata a buon fine e chiedi all'utente se vuole riprovare.
  • PURCHASE_STATUS_UNSPECIFIED: la transazione non è andata a buon fine per un motivo sconosciuto. con conseguente stato sconosciuto. Puoi gestire questo stato di errore consentendo al l'utente sa che la transazione non è andata a buon fine e chiedi se vuole riprovare.

Devi gestire ciascuno di questi risultati dalla scena CompletePurchase.

  1. Dalla scheda Scene, seleziona la scena CompletePurchase appena creata.
  2. In Condizione, fai clic su + per aggiungere una nuova condizione.

  3. Nel campo di testo, inserisci la seguente sintassi della condizione per verificare condizione di operazione riuscita:

    scene.slots.status == "FINAL" && session.params.CompletePurchase.purchaseStatus == "PURCHASE_STATUS_OK"

  4. Passa il mouse sopra la condizione appena aggiunta e fai clic sulla Freccia su per posizionarlo prima di if scene.slots.status == "FINAL".

  5. Attiva l'opzione Invia prompt e fornisci un messaggio semplice per informare l'utente sono pronti a effettuare una transazione:

    candidates:
  - first_simple:
      variants:
        - speech: >-
            Your purchase was successful.

  6. In Transizione seleziona Termina conversazione per terminarla.

Ripeti i passaggi precedenti per ogni tipo di risultato di acquisto che vuoi supportare.

Rispecchiare gli acquisti dell'utente.

Quando un utente esegue una query sull'azione, l'oggetto user della richiesta JSON include un oggetto elenco dei suoi acquisti. Controlla queste informazioni e modifica il valore risposta 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:

{
  "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"
    ]
  }
}

Testa il progetto

Durante il test del progetto, puoi abilitare la modalità sandbox nella console di Actions per testare l'Azione senza addebitare l'importo su un metodo di pagamento. Per attivare la modalità sandbox:

  1. Nella console di Actions, fai clic su Test nel menu di navigazione.
  2. Fai clic su Impostazioni.
  3. Attiva l'opzione Sandbox per lo sviluppo.