Creare transazioni digitali utilizzabili (Dialogflow)

Questa guida spiega come aggiungere transazioni digitali a un dialogo Azione, in modo che gli utenti possano acquistare i tuoi beni digitali di consumo.

Termini chiave: un bene digitale consumabile è un codice SKU (codice identificativo dell'articolo) che un utente può utilizzare e acquistare più di una volta, ad esempio una quantità di valuta in-game per un gioco Android. Questo bene digitale è diverso da un non consumabile prodotto digitale che un utente può acquistare una sola volta.

Per ulteriori informazioni sui prodotti di consumo a pagamento singolo, fai riferimento al documentazione su funzionalità uniche per prodotti specifici.

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.

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 dal 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 (o passaggi aggiuntivi).
  6. Rendi l'acquisto ripetibile: l'azione utilizza gli acquisti digitali. API da "consumare" l'articolo acquistato, rendendolo disponibile per l'acquisto di nuovo da quell'utente.

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 conservarle 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 beni di consumo 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.

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.

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:

  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 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': ['consumable.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:

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

6. Rendi l'acquisto ripetibile

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': ['consumable.1']
      },
    }, (err, httpResponse, body) => {
      if (err) {
        throw new Error(`API request error: ${err}`);
      }
      console.log(`${httpResponse.statusCode}: ${httpResponse.statusMessage}`);
      console.log(JSON.stringify(body));
    });
  });
});

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"
        }
      ]
    }
  ],
  ...
}