Creare transazioni per abbonamenti digitali

Questa guida spiega come aggiungere transazioni di abbonamento digitale all'azione conversazionale, in modo che gli utenti possano acquistare i tuoi abbonamenti.

Termini chiave: un bene digitale di abbonamento è uno SKU (stock-keeping unit) che richiede un addebito ricorrente all'utente, ad esempio una rivista online. Si tratta di un bene digitale di consumo che l'utente deve riacquistare manualmente o di un bene digitale non consumabile che viene acquistato automaticamente una sola volta.

Per ulteriori informazioni sugli abbonamenti digitali, consulta la documentazione di Android sulle funzionalità specifiche per gli abbonamenti.

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:

  1. 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.
  2. Raccogliere informazioni. L'Azione raccoglie informazioni di base sull'utente e sul tuo inventario di Google Play per preparare una transazione.
    1. 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.
    2. Raccogliere l'inventario disponibile. L'Azione controlla il tuo inventario Google Play e identifica quali articoli sono attualmente disponibili per l'acquisto.
  3. Crea l'ordine: l'azione presenta i beni digitali disponibili all'utente in modo che possa selezionarne uno da acquistare.
  4. Completare l'acquisto: l'Azione utilizza l'API DigitalPurchases per avviare un acquisto sul Google Play Store con la selezione dell'utente.
  5. Gestire il risultato: l'Azione riceve un codice di stato per la transazione e avvisa l'utente che l'acquisto è riuscito (o esegue passaggi aggiuntivi).

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

Prerequisiti

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

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:

  1. 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.
  2. 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 includono com.example.
  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 tuo 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 Build, Genera bundle / APK firmato.
    2. Fai clic su Avanti.
    3. In Percorso archivio chiavi, fai clic su Crea nuovo.
    4. 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.
    5. Fai clic su Avanti.
    6. Seleziona Rilascia.
    7. Seleziona V1 (firma JAR).
    8. Fai clic su Fine.
    9. Dopo qualche secondo, Android Studio genera un file app-release.apk. Individua questo file per utilizzarlo in seguito.
  6. In Google Play Console, crea una nuova applicazione.

  7. Vai a Release dell'app.

  8. In Gruppi 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 le informazioni relative alla chiave di firma.

  11. Carica il file APK.

  12. Fai clic su Salva.

Crea i tuoi prodotti digitali

Se al momento non disponi di beni digitali in Play Console, procedi nel seguente modo:

  1. In Google Play Console, vai a Prodotti in-app e poi ad Abbonamenti. Se viene visualizzato un avviso, segui le istruzioni precedenti per creare un'app Android o fai clic sul link per creare un profilo commerciante.
  2. Fai clic su Crea sottoscrizione.
  3. Compila i campi del prodotto digitale. Prendi nota dell'ID prodotto, che serve a fare riferimento a questo prodotto nell'Azione.
  4. Fai clic su Salva.
  5. Ripeti i passaggi 2-4 per ogni prodotto che vuoi vendere.

Abbonamenti di esempio in Google Play Console.

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.

Configurazione

Per attivare le transazioni su beni digitali nel tuo progetto Actions, segui questi passaggi:

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

  1. Nella Console di Actions, fai clic sull'icona con tre puntini nell'angolo in alto a destra, quindi su Impostazioni progetto.
  2. Individua l'ID progetto dell'Azione.
  3. Segui questo link, sostituendo "<project_id>" con l'ID del tuo progetto: https://console.developers.google.com/apis/credentials?project=project_id
  4. Nella navigazione principale, vai a Credenziali.
  5. Nella pagina visualizzata, fai clic su Crea credenziali, quindi su Chiave account di servizio.
  6. Vai ad Account di servizio e fai clic su Nuovo account di servizio.
  7. Assegna all'account di servizio un nome, ad esempio 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 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.

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

  1. Nella Console di Actions, vai a Deployment e poi a Verifica del brand.
  2. Se non hai collegato alcuna proprietà, collega prima un sito web:

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

  3. Dopo aver collegato almeno un sito web, procedi nel seguente modo per connettere la tua app Android:

    1. Nella Console di Actions, vai a Deployment e poi a Verifica del brand.
    2. Fai clic su Collega app.
    3. 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.

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

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

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 transazioni prima di dare la possibilità di effettuare un acquisto. Devi passare a una scena DigitalPurchaseCheck per verificare 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'area geografica in cui sono supportate le transazioni digitali.

Per creare una scena di un controllo di acquisto digitale, segui questi passaggi:

  1. Dalla scheda Scene, aggiungi una nuova scena con il nome DigitalPurchaseCheck.
  2. In Riempimento slot, fai clic su + per aggiungere una nuova area.
  3. In Seleziona tipo, scegli actions.type.DigitalPurchaseCheckResult come tipo di area.
  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 (attivata per impostazione predefinita).
  6. Fai clic su Salva.

Un controllo degli acquisti digitali comporterà uno dei seguenti risultati:

  • Se i requisiti sono soddisfatti, il parametro sessione viene impostato con una condizione di successo e puoi continuare a consentire all'utente di acquistare beni digitali.
  • Se uno o più requisiti non possono essere soddisfatti, il parametro sessione viene impostato con una condizione di errore. In questo caso, devi allontanare la conversazione dall'esperienza transazionale o terminare la conversazione.

Per gestire il risultato di un controllo di acquisto digitale, segui questi passaggi:

  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 la presenza della condizione di esito positivo:

    scene.slots.status == "FINAL" && session.params.DigitalPurchaseCheck.resultType == "CAN_PURCHASE"
    
  4. Passa il cursore sulla condizione appena aggiunta e fai clic sulla Freccia su per posizionarla prima di if scene.slots.status == "FINAL".

  5. Attiva Invia richieste e fornisci una semplice richiesta per far sapere all'utente che è pronto a effettuare una transazione:

    candidates:
      - first_simple:
          variants:
            - speech: >-
                You are ready to purchase digital goods.
    
  6. In Transizione, seleziona un'altra scena, consentendo all'utente di continuare la conversazione e di procedere con la transazione.

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

  8. Attiva Invia richieste e fornisci una semplice richiesta per far sapere all'utente che non è possibile effettuare una transazione:

    candidates:
      - first_simple:
          variants:
            - speech: Sorry you cannot perform a digital purchase.
    
  9. In Transizione, seleziona Termina conversazione per terminare la conversazione.

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 "SKU_TYPE_IN_APP" or "SKU_TYPE_SUBSCRIPTION"
      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': conv.session.id,
        'skuType': 'SKU_TYPE_IN_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 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:

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 degli utenti

Dopo che l'utente ha selezionato un articolo, puoi creare l'ordine. Per farlo, nell'area annuncio associata all'elemento selezionato, puoi chiamare il tuo webhook per creare l'ordine. Dal fulfillment, salva i dati dell'ordine in un parametro di sessione. L'oggetto Order viene utilizzato nelle varie 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 utilizzare l'editor JSON per configurare lo slot con l'oggetto ordine sopra. Entrambe le implementazioni utilizzano lo stesso formato per CompletePurchaseValueSpec, che puoi trovare nel riferimento al payload dei webhook JSON.

4. Completa l'acquisto

Una volta selezionato un articolo, puoi completare l'acquisto. Dopo aver riempito lo slot associato all'elemento selezionato, dovresti passare a una scena che esegue un acquisto completo.

Crea scena di acquisto completa

  1. Dalla scheda Scene, aggiungi una nuova scena con il nome CompletePurchase.
  2. In Riempimento slot, fai clic su + per aggiungere una nuova area.
  3. In Seleziona tipo, scegli actions.type.CompletePurchaseValue come tipo di area annuncio.
  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 annuncio (attivata 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 per archiviare l'ordine nel campo di testo (ad es. $session.params.purchase).
  8. Fai clic su Salva.

5. Gestire il risultato

Un'area con il tipo actions.type.CompletePurchaseValue può avere i seguenti risultati:

  • 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'elemento. Per evitare questo errore, controlla gli acquisti precedenti dell'utente e personalizza gli articoli mostrati in modo che non possa riacquistare gli articoli di cui è già proprietario.
  • 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 è andata a buon fine perché l'utente ha deciso di acquistare qualcos'altro. Rispondi alla richiesta 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 completamente dalla transazione.
  • 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, con conseguente 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.

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 la presenza della condizione di esito positivo:

    scene.slots.status == "FINAL" && session.params.CompletePurchase.purchaseStatus == "PURCHASE_STATUS_OK"
    
  4. Passa il cursore sulla condizione appena aggiunta e fai clic sulla Freccia su per posizionarla prima di if scene.slots.status == "FINAL".

  5. Attiva Invia richieste e fornisci una semplice richiesta per far sapere all'utente che è pronto a effettuare una transazione:

    candidates:
      - first_simple:
          variants:
            - speech: >-
                Your purchase was successful.
    
  6. In Transizione, seleziona Termina conversazione per terminare la conversazione.

Ripeti i passaggi precedenti per ogni tipo di risultato relativo agli acquisti che vuoi supportare.

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:

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

Testare il progetto

Durante il test del progetto, puoi attivare la modalità sandbox nella console Actions per testare l'Azione senza addebitare alcun metodo di pagamento. Per attivare la modalità sandbox, segui questi passaggi:

  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.