L'API Transactions verrà ritirata il 3 maggio 2023, prima della disattivazione delle azioni di conversazione il 13 giugno 2023. Per ulteriori informazioni, vedi Ritiro di Azioni di conversazione.

Questa pagina è stata tradotta dall'API Cloud Translation.

Creare transazioni fisiche con i pagamenti gestiti dal commerciante

Questa guida illustra il processo di sviluppo di un progetto Actions che incorpora transazioni per beni fisici utilizzando i metodi di pagamento gestiti dal tuo sito.

Flusso delle transazioni

Quando il tuo progetto Actions gestisce le transazioni fisiche mediante pagamenti gestiti dal commerciante, utilizza il seguente flusso:

Collega l'account dell'utente: affinché l'utente possa utilizzare un metodo di pagamento che ha salvato con il tuo servizio, usa il collegamento dell'account per associare il suo Account Google all'account nel tuo servizio.
Raccogliere informazioni (facoltativo). A seconda della natura della transazione, potresti voler raccogliere le seguenti informazioni dall'utente all'inizio della conversazione:
1. Convalida dei requisiti di transazione: all'inizio della sezione relativa alla transazione della conversazione, convalida che l'utente soddisfi i requisiti per effettuare una transazione, ad esempio se i dati di pagamento devono essere configurati e disponibili correttamente prima di creare il carrello.
2. Richiedi un indirizzo di consegna: se la transazione richiede un indirizzo di consegna, richiedine uno all'utente.
Creare l'ordine: guidare l'utente attraverso un "assemblaggio del carrello" in cui sceglie gli articoli da acquistare.
Proponi l'ordine: una volta completato il carrello, proponi l'ordine all'utente in modo che possa confermare che è corretto. Se l'ordine viene confermato, riceverai una risposta con i dettagli dell'ordine e un token di pagamento.
Finalizzare l'ordine e inviare una ricevuta: dopo la conferma dell'ordine, aggiorna il monitoraggio dell'inventario o gli altri servizi di evasione degli ordini, quindi invia una ricevuta all'utente.
Inviare aggiornamenti degli ordini: nel corso della durata dell'evasione dell'ordine, fornisci all'utente aggiornamenti dell'ordine inviando richieste PATCH all'API Orders.

Limitazioni e linee guida per le recensioni

Tieni presente che alle Azioni con transazioni si applicano norme aggiuntive. Potrebbero essere necessarie fino a sei settimane per esaminare le azioni con transazioni, quindi tieni conto di questo lasso di tempo quando pianifichi la pianificazione della release. Per facilitare la procedura di revisione, assicurati di rispettare le norme e linee guida per le transazioni prima di inviare l'Azione per la revisione.

Puoi implementare Azioni che vendono beni fisici solo nei seguenti paesi:

Australia
Brasile
Canada
Indonesia

Giappone
Messico
Qatar
Russia

Singapore
Svizzera
Thailandia
Turchia
Regno Unito
Stati Uniti

Crea il tuo progetto

Per un esempio di conversazione transazionale, visualizza l'esempio di transazioni Node.js.

Configurazione del progetto

Quando crei l'Azione, devi specificare che vuoi eseguire transazioni nella Console di Actions.

Per configurare il progetto e il fulfillment:

Crea un nuovo progetto o importa un progetto esistente.
Vai a Deployment > Informazioni sulla directory.
In Informazioni aggiuntive > Transazioni > seleziona la casella "Le tue azioni utilizzano l'API Transactions per eseguire transazioni di beni fisici?".

Collega l'account dell'utente (facoltativo)

Se utilizzi il tuo metodo di pagamento personale per effettuare addebiti, ti consigliamo di collegare il suo Account Google a un account che utilizzi con il tuo servizio per recuperare, presentare e addebitare i metodi di pagamento memorizzati al suo interno.

Progetta l'interfaccia utente vocale per il flusso di autenticazione

Controlla se l'utente è verificato e avvia la procedura di collegamento dell'account

Apri il progetto Actions Builder nella console di Actions.
Crea una nuova scena per avviare il collegamento dell'account nell'Azione:
1. Fai clic su Scene.
2. Fai clic sull'icona Aggiungi (+) per aggiungere una nuova scena.
Nella scena appena creata, fai clic sull'icona Aggiungi in Condizioni.
Aggiungi una condizione che verifichi se l'utente associato alla conversazione è un utente verificato. Se il controllo ha esito negativo, l'Azione non può eseguire il collegamento dell'account durante la conversazione e dovrebbe fornire l'accesso a funzionalità che non richiedono il collegamento dell'account.
1. Nel campo Enter new expression in Condizione, inserisci la seguente logica: user.verificationStatus != "VERIFIED"
2. In Transizione, seleziona una scena che non richieda il collegamento dell'account o che sia il punto di accesso alle funzionalità solo per gli ospiti.

Fai clic sull'icona Aggiungi in Condizioni.
Aggiungi una condizione per attivare un flusso di collegamento dell'account se all'utente non è associata un'identità.
1. Nel campo Enter new expression in Condizione, inserisci la seguente logica: user.verificationStatus == "VERIFIED"
2. In Transizione, seleziona la scena di sistema Collegamento dell'account.
3. Fai clic su Salva.

Dopo il salvataggio, al progetto viene aggiunta una nuova scena di sistema di collegamento dell'account denominata <SceneName>_AccountLinking.

Personalizzare la scena di collegamento dell'account

In Scene, seleziona la scena di sistema per il collegamento dell'account.
Fai clic su Invia richiesta e aggiungi una breve frase per descrivere all'utente il motivo per cui l'Azione deve accedere alla sua identità (ad esempio "Per salvare le tue preferenze").
Fai clic su Salva.

In Condizioni, fai clic su Se l'utente completa correttamente il collegamento dell'account.
Configura la procedura da seguire nel caso in cui l'utente accetti di collegare il suo account. Ad esempio, chiama il webhook per elaborare qualsiasi logica di business personalizzata richiesta e tornare alla scena di origine.
Fai clic su Salva.

In Condizioni, fai clic su Se l'utente annulla o ignora il collegamento dell'account.
Configura la procedura da seguire nel flusso se l'utente non accetta di collegare il proprio account. Ad esempio, invia un messaggio di conferma e reindirizza a scene che offrono funzionalità che non richiedono il collegamento dell'account.
Fai clic su Salva.

In Condizioni, fai clic su Se si verifica un errore di sistema o di rete.
Configura la procedura da seguire se non è possibile completare il flusso di collegamento dell'account a causa di errori di sistema o di rete. Ad esempio, invia un messaggio di conferma e reindirizza a scene che offrono funzionalità che non richiedono il collegamento dell'account.
Fai clic su Salva.

Raccogliere informazioni (facoltativo)

(Facoltativo) Convalida i requisiti della transazione

Non appena l'utente avrà indicato di voler effettuare un acquisto, devi verificare che sia in grado di eseguire una transazione. Ad esempio, quando viene richiamata, l'Azione potrebbe chiedere "Vuoi ordinare delle scarpe o controllare il saldo del tuo account?". Se l'utente dice "ordina scarpe", devi assicurarti che possa procedere e offrirgli l'opportunità di correggere le impostazioni che impediscono di continuare la transazione. Per farlo, devi passare a una scena che esegue un controllo dei requisiti di transazione.

Crea scena del controllo dei requisiti di transazione

Dalla scheda Scene, aggiungi una nuova scena con il nome TransactionRequirementsCheck.
In Riempimento slot, fai clic su + per aggiungere una nuova area.
In Seleziona tipo, scegli actions.type.TransactionRequirementsCheckResult come tipo di area.
Nel campo del nome dell'area, assegna all'area il nome TransactionRequirementsCheck.
Attiva la casella di controllo Personalizza il writeback del valore dell'area annuncio (attivata per impostazione predefinita).
Fai clic su Salva.

Un controllo dei requisiti di transazione comporterà uno dei seguenti risultati:

Se i requisiti sono soddisfatti, il parametro sessione viene impostato con una condizione di successo e puoi procedere con la creazione dell'ordine dell'utente.
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.
- Se gli errori che causano lo stato di errore possono essere corretti dall'utente, gli verrà chiesto di risolverli sul dispositivo. Se la conversazione si svolge su una piattaforma solo vocale, verrà avviato un trasferimento al telefono dell'utente.

Gestire il risultato del controllo dei requisiti di transazione

Dalla scheda Scene, seleziona la scena TransactionRequirementsCheck appena creata.
In Condizione, fai clic su + per aggiungere una nuova condizione.
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.TransactionRequirementsCheck.resultType == "CAN_TRANSACT"
```
Passa il cursore sulla condizione appena aggiunta e fai clic sulla Freccia su per posizionarla prima di if scene.slots.status == "FINAL".
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 physical goods.
```
In Transizione, seleziona un'altra scena, consentendo all'utente di continuare la conversazione e procedere con una transazione.
Seleziona la condizione else if scene.slots.status == "FINAL".
Attiva Invia richieste e fornisci una semplice richiesta per far sapere all'utente che non è possibile effettuare una transazione:
```
candidates:
  - first_simple:
      variants:
        - speech: Transaction requirements check failed.
```
In Transizione, seleziona Termina conversazione per terminare la conversazione se un utente non è in grado di effettuare transazioni.

Richiedi un indirizzo di consegna (facoltativo)

Se la transazione richiede l'indirizzo di consegna di un utente, devi richiederlo all'utente. Questo potrebbe essere utile per determinare il prezzo totale, la località di consegna/ritiro o per garantire che l'utente si trovi nella tua regione coperta dal servizio. Per farlo, devi passare a una scena che richiede all'utente l'indirizzo di consegna.

Crea scena indirizzo di consegna

Dalla scheda Scene, aggiungi una nuova scena con il nome DeliveryAddress.
In Riempimento slot, fai clic su + per aggiungere una nuova area.
In Seleziona tipo, scegli actions.type.DeliveryAddressValue come tipo di area.
Nel campo del nome dell'area, assegna all'area il nome TransactionDeliveryAddress.
Attiva la casella di controllo Personalizza il writeback del valore dell'area annuncio (attivata per impostazione predefinita).
Fai clic su Salva.

Durante la configurazione dello slot, puoi fornire un reason che ti consente di anteporre la richiesta dell'assistente di ottenere un indirizzo con una stringa.La stringa del motivo predefinita è "sapere dove inviare l'ordine". Pertanto, l'assistente potrebbe chiedere all'utente: "Per sapere dove inviare l'ordine, devo avere il tuo indirizzo di consegna".

Sulle piattaforme con uno schermo, l'utente sceglierà l'indirizzo da utilizzare per la transazione. Se non ha ancora fornito un indirizzo, potrà inserirne uno nuovo.
Sulle piattaforme solo vocale, l'assistente chiederà all'utente l'autorizzazione a condividere il suo indirizzo predefinito per la transazione. Se non ha ancora fornito un indirizzo, la conversazione verrà consegnata a un telefono per l'accesso.

Per gestire il risultato relativo all'indirizzo di consegna, procedi nel seguente modo:

Dalla scheda Scene, seleziona la scena DeliveryAddress appena creata.
In Condizione, fai clic su + per aggiungere una nuova condizione.
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.TransactionDeliveryAddress.userDecision == "ACCEPTED"
```
Passa il cursore sulla condizione appena aggiunta e fai clic sulla Freccia su per posizionarla prima di if scene.slots.status == "FINAL".

Abilita Invia richieste e fornisci un semplice messaggio per informare l'utente che hai ricevuto il suo indirizzo:

candidates:
  - first_simple:
      variants:
        - speech: >-
            Great! Your order will be delivered to
            $session.params.TransactionDeliveryAddress.location.postalAddress.locality
            $session.params.TransactionDeliveryAddress.location.postalAddress.administrativeArea
            $session.params.TransactionDeliveryAddress.location.postalAddress.regionCode
            $session.params.TransactionDeliveryAddress.location.postalAddress.postalCode

In Transizione, seleziona un'altra scena, in modo che l'utente possa continuare la conversazione.
Seleziona la condizione else if scene.slots.status == "FINAL".
Attiva Invia richieste e fornisci una semplice richiesta per far sapere all'utente che non è possibile effettuare una transazione:
```
candidates:
  - first_simple:
      variants:
        - speech: I failed to get your delivery address.
```
In Transizione, seleziona Termina conversazione per terminare la conversazione se un utente non è in grado di effettuare transazioni.

Crea l'ordine

Una volta che disponi delle informazioni utente necessarie, creerai un'esperienza di "assemblaggio del carrello" che guiderà l'utente nella creazione di un ordine. Ogni Azione avrà un flusso di assemblaggio del carrello leggermente diverso a seconda del prodotto o servizio.

L'esperienza di assemblaggio del carrello più semplice prevede che l'utente scelga da un elenco gli articoli da aggiungere all'ordine, anche se puoi progettare la conversazione per semplificare l'esperienza utente. Potresti creare un'esperienza di assemblaggio del carrello che consenta all'utente di riordinare l'acquisto più recente con una semplice domanda sì o no. Puoi anche presentare all'utente un carosello o una scheda elenco degli elementi più "in primo piano" o "consigliati".

Ti consigliamo di utilizzare risposte dettagliate per presentare visivamente le opzioni dell'utente, ma anche di progettare la conversazione in modo che l'utente possa creare il carrello utilizzando solo la voce. Per alcune best practice ed esempi di esperienze di assemblaggio del carrello di alta qualità, consulta le linee guida per la progettazione delle transazioni.

Creazione di un ordine

Nel corso della conversazione, dovrai raccogliere gli elementi che un utente vuole acquistare e poi creare un oggetto Order.

Come minimo, il tuo Order deve contenere quanto segue:

buyerInfo: informazioni sull'utente che effettua l'acquisto.
transactionMerchant: informazioni sul commerciante che ha gestito l'ordine.
contents. I contenuti effettivi dell'ordine indicato come lineItems.
priceAttributes: dettagli dei prezzi dell'ordine, inclusi il costo totale dell'ordine con sconti e tasse.

Per creare il tuo carrello, consulta la documentazione relativa alle risposte di Order. Tieni presente che potrebbe essere necessario includere campi diversi a seconda dell'ordine.

Il codice campione riportato di seguito mostra un ordine completo, inclusi campi facoltativi:

const order = {
  createTime: '2019-09-24T18:00:00.877Z',
  lastUpdateTime: '2019-09-24T18:00:00.877Z',
  merchantOrderId: orderId, // A unique ID String for the order
  userVisibleOrderId: orderId,
  transactionMerchant: {
    id: 'http://www.example.com',
    name: 'Example Merchant',
  },
  contents: {
    lineItems: [
      {
        id: 'LINE_ITEM_ID',
        name: 'Pizza',
        description: 'A four cheese pizza.',
        priceAttributes: [
          {
            type: 'REGULAR',
            name: 'Item Price',
            state: 'ACTUAL',
            amount: {
              currencyCode: 'USD',
              amountInMicros: 8990000,
            },
            taxIncluded: true,
          },
          {
            type: 'TOTAL',
            name: 'Total Price',
            state: 'ACTUAL',
            amount: {
              currencyCode: 'USD',
              amountInMicros: 9990000,
            },
            taxIncluded: true,
          },
        ],
        notes: [
          'Extra cheese.',
        ],
        purchase: {
          quantity: 1,
          unitMeasure: {
            measure: 1,
            unit: 'POUND',
          },
          itemOptions: [
            {
              id: 'ITEM_OPTION_ID',
              name: 'Pepperoni',
              prices: [
                {
                  type: 'REGULAR',
                  state: 'ACTUAL',
                  name: 'Item Price',
                  amount: {
                    currencyCode: 'USD',
                    amountInMicros: 1000000,
                  },
                  taxIncluded: true,
                },
                {
                  type: 'TOTAL',
                  name: 'Total Price',
                  state: 'ACTUAL',
                  amount: {
                    currencyCode: 'USD',
                    amountInMicros: 1000000,
                  },
                  taxIncluded: true,
                },
              ],
              note: 'Extra pepperoni',
              quantity: 1,
              subOptions: [],
            },
          ],
        },
      },
    ],
  },
  buyerInfo: {
    email: 'janedoe@gmail.com',
    firstName: 'Jane',
    lastName: 'Doe',
    displayName: 'Jane Doe',
  },
  priceAttributes: [
    {
      type: 'SUBTOTAL',
      name: 'Subtotal',
      state: 'ESTIMATE',
      amount: {
        currencyCode: 'USD',
        amountInMicros: 9990000,
      },
      taxIncluded: true,
    },
    {
      type: 'DELIVERY',
      name: 'Delivery',
      state: 'ACTUAL',
      amount: {
        currencyCode: 'USD',
        amountInMicros: 2000000,
      },
      taxIncluded: true,
    },
    {
      type: 'TAX',
      name: 'Tax',
      state: 'ESTIMATE',
      amount: {
        currencyCode: 'USD',
        amountInMicros: 3780000,
      },
      taxIncluded: true,
    },
    {
      type: 'TOTAL',
      name: 'Total Price',
      state: 'ESTIMATE',
      amount: {
        currencyCode: 'USD',
        amountInMicros: 15770000,
      },
      taxIncluded: true,
    },
  ],
  followUpActions: [
    {
      type: 'VIEW_DETAILS',
      title: 'View details',
      openUrlAction: {
        url: 'http://example.com',
      },
    },
    {
      type: 'CALL',
      title: 'Call us',
      openUrlAction: {
        url: 'tel:+16501112222',
      },
    },
    {
      type: 'EMAIL',
      title: 'Email us',
      openUrlAction: {
        url: 'mailto:person@example.com',
      },
    },
  ],
  termsOfServiceUrl: 'http://www.example.com',
  note: 'Sale event',
  promotions: [
    {
      coupon: 'COUPON_CODE',
    },
  ],
  purchase: {
    status: 'CREATED',
    userVisibleStatusLabel: 'CREATED',
    type: 'FOOD',
    returnsInfo: {
      isReturnable: false,
      daysToReturn: 1,
      policyUrl: 'http://www.example.com',
    },
    fulfillmentInfo: {
      id: 'FULFILLMENT_SERVICE_ID',
      fulfillmentType: 'DELIVERY',
      expectedFulfillmentTime: {
        timeIso8601: '2019-09-25T18:00:00.877Z',
      },
      location: location,
      price: {
        type: 'REGULAR',
        name: 'Delivery Price',
        state: 'ACTUAL',
        amount: {
          currencyCode: 'USD',
          amountInMicros: 2000000,
        },
        taxIncluded: true,
      },
      fulfillmentContact: {
        email: 'johnjohnson@gmail.com',
        firstName: 'John',
        lastName: 'Johnson',
        displayName: 'John Johnson',
      },
    },
    purchaseLocationType: 'ONLINE_PURCHASE',
  },
};

Crea opzioni per ordine e presentazione

Prima che l'utente confermi l'ordine, visualizzerà una scheda d'ordine proposta. Puoi personalizzare il modo in cui questa scheda viene presentata all'utente impostando diverse opzioni di ordine e presentazione.

Di seguito sono riportate le opzioni di ordine e presentazione per effettuare un ordine che richiede un indirizzo di consegna, inclusa l'email dell'utente nella scheda di conferma dell'ordine:

const orderOptions = {
      'requestDeliveryAddress': true,
      'userInfoOptions': {
        'userInfoProperties': ['EMAIL']
      }
    };

const presentationOptions = {
      'actionDisplayName': 'PLACE_ORDER'
    };

Creare parametri di pagamento

L'oggetto paymentParameters include un merchantPaymentOption con campi che descrivono il metodo di pagamento dell'utente per l'ordine. Di seguito è riportato un esempio di parametri di pagamento con carta di credito Visa:

const paymentParamenters = {
      'merchantPaymentOption': {
        'defaultMerchantPaymentMethodId': '12345678',
        'managePaymentMethodUrl': 'https://example.com/managePayment',
        'merchantPaymentMethod': [{
          'paymentMethodDisplayInfo': {
            'paymentMethodDisplayName': 'VISA **** 1234',
            'paymentType': 'PAYMENT_CARD'
          },
          'paymentMethodGroup': 'Payment method group',
          'paymentMethodId': '12345678',
          'paymentMethodStatus': {
            'status': 'STATUS_OK',
            'statusMessage': 'Status message'
          }
        }]
      }
    };

Salva i dati degli ordini nel parametro di sessione

Dal tuo evasione degli ordini, salva i dati dell'ordine in un parametro session. L'oggetto dell'ordine verrà utilizzato nelle varie scene per la stessa sessione.

conv.session.params.order = {
    '@type': 'type.googleapis.com/google.actions.transactions.v3.TransactionDecisionValueSpec',
    order: order,
    orderOptions: orderOptions,
    presentationOptions: presentationOptions,
    paymentParameters: paymentParameters
};

Proponi l'ordine

Una volta creato un ordine, devi presentarlo all'utente per la conferma o il rifiuto. Per farlo, devi passare a una scena in cui è presa una decisione in merito alla transazione.

Crea scena della decisione della transazione

Dalla scheda Scene, aggiungi una nuova scena con il nome TransactionDecision.
In Riempimento slot, fai clic su + per aggiungere una nuova area.
In Seleziona tipo, scegli actions.type.TransactionDecisionValue come tipo di area annuncio.
Nel campo del nome dell'area, assegna all'area il nome TransactionDecision.
Attiva la casella di controllo Personalizza il writeback del valore dell'area annuncio (attivata per impostazione predefinita).
In Configura slot, seleziona Utilizza parametro sessione dal menu a discesa.
In Configura slot,inserisci il nome del parametro di sessione utilizzato per archiviare l'ordine nel campo di testo (ad es. $session.params.order).
Fai clic su Salva.

Nel tentativo di riempire uno slot TransactionDecisionValue, l'assistente avvia un'esperienza integrata in cui i Order che hai passato vengono visualizzati direttamente in una "scheda di anteprima del carrello". L'utente può dire "emetti ordine", rifiutare la transazione, modificare un'opzione di pagamento, ad esempio la carta di credito o l'indirizzo, oppure richiedere di modificare i contenuti dell'ordine.

A questo punto, l'utente può anche richiedere modifiche all'ordine. In questo caso, devi assicurarti che l'evasione degli ordini sia in grado di gestire le richieste di modifica dell'ordine dopo aver completato l'esperienza di assemblaggio del carrello.

Gestire il risultato della decisione della transazione

Quando uno slot TransactionDecisionValue viene riempito, la risposta dell'utente alla decisione sulla transazione viene archiviata in un parametro sessione. Questo valore contiene quanto segue:

ORDER_ACCEPTED,
ORDER_REJECTED,
DELIVERY_ADDRESS_UPDATED,
CART_CHANGE_REQUESTED
USER_CANNOT_TRANSACT.

Per gestire il risultato di una decisione relativa a una transazione:

Dalla scheda Scene, seleziona la scena TransactionDecision appena creata.
In Condizione, fai clic su + per aggiungere una nuova condizione.
Nel campo di testo, inserisci la seguente sintassi della condizione per verificare la condizione di esito positivo:
```
scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"
```
Passa il cursore sulla condizione appena aggiunta e fai clic sulla Freccia su per posizionarla prima di if scene.slots.status == "FINAL".

Attiva Invia richieste e fornisci un semplice messaggio per informare l'utente che l'ordine è stato completato:

candidates:
  - first_simple:
      variants:
        - speech: >-
            Transaction completed! Your order
            $session.params.TransactionDecision.order.merchantOrderId is all
            set!

In Transizione, seleziona Termina conversazione per terminare la conversazione.
In Condizione, fai clic su + per aggiungere una nuova condizione.

Nel campo di testo, inserisci la seguente sintassi della condizione per verificare le condizioni di errore:

  scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_REJECTED"

Passa il cursore sulla condizione appena aggiunta e fai clic sulla Freccia su per posizionarla prima di if scene.slots.status == "FINAL".
Attiva l'opzione Invia richieste e fornisci un semplice messaggio per informare l'utente che l'ordine è stato rifiutato:
```
candidates:
  - first_simple:
      variants:
        - speech: Look like you don't want to order anything. Goodbye.
```
In Transizione, seleziona Termina conversazione per terminare la conversazione.
Seleziona la condizione else if scene.slots.status == "FINAL".

Abilita Invia richieste e fornisci un semplice messaggio per informare l'utente che non è possibile effettuare una transazione:

candidates:
  - first_simple:
      variants:
        - speech: >-
            Transaction failed with status
            $session.params.TransactionDecision.transactionDecision

In Transizione, seleziona Termina conversazione per terminare la conversazione se un utente non è in grado di effettuare transazioni.

Finalizza l'ordine e invia una ricevuta

Quando lo slot TransactionDecisionValue restituisce il risultato ORDER_ACCEPTED, devi eseguire immediatamente l'elaborazione necessaria per "confermare" l'ordine (ad esempio, memorizzarlo nel tuo database e addebitare costi all'utente).

Puoi terminare la conversazione con questa risposta, ma devi includere una risposta semplice per mantenere viva la conversazione. Quando fornisci questo orderUpdate iniziale, l'utente vedrà una "scheda della ricevuta compressa" insieme al resto della risposta. Questa scheda rispecchierà la ricevuta che l'utente trova nella sua Cronologia ordini.

Durante la conferma dell'ordine, l'oggetto dell'ordine può includere un userVisibleOrderId, ovvero l'ID dell'ordine visualizzato dall'utente. Puoi riutilizzare merchantOrderId per questo campo.

Parte dell'oggetto OrderUpdate dovrà contenere un oggetto di azione follow-up, che si manifesta sotto forma di pulsanti URL nella parte inferiore dei dettagli dell'ordine che l'utente può trovare nella propria cronologia ordini dell'assistente.

Devi fornire, come minimo, un' VIEW_DETAILS Azione di follow-up per ogni ordine. che deve contenere un link diretto alla rappresentazione dell'ordine sulla tua app mobile o sul tuo sito web.
È inoltre necessario inviare una ricevuta formale via email che soddisfi tutti i requisiti legali per eseguire una transazione, oltre alla scheda della ricevuta nella conversazione dell'Azione.

Per inviare un aggiornamento iniziale dell'ordine:

Dalla scheda Scene, seleziona la tua scena TransactionDecision.

In Condizione, seleziona la condizione che verifica il risultato positivo, ORDER_ACCEPTED:

  scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"

Per questa condizione, attiva Chiama il webhook e fornisci un nome per il gestore di intent, ad esempio update_order.

Nel codice webhook, aggiungi un gestore di intent per l'invio di un aggiornamento iniziale dell'ordine:

app.handle('update_order', conv => {
  const currentTime = new Date().toISOString();
  let order = conv.session.params.TransactionDecision.order;
  conv.add(new OrderUpdate({
    'updateMask': {
      'paths': [
        'purchase.status',
        'purchase.user_visible_status_label'
      ]
    },
    'order': {
      'merchantOrderId': order.merchantOrderId,
      'lastUpdateTime': currentTime,
      'purchase': {
        'status': 'CONFIRMED',
        'userVisibleStatusLabel': 'Order confirmed'
      },
    },
    'reason': 'Reason string
  }));
});

Invia aggiornamenti sull'ordine

Dovrai informare l'utente sullo stato dell'ordine nel corso della sua durata. Invia gli aggiornamenti sull'ordine degli utenti inviando richieste PATCH HTTP all'API Orders con lo stato e i dettagli dell'ordine.

Configurare le richieste asincrone all'API Orders

Le richieste di aggiornamento degli ordini all'API Orders sono autorizzate da un token di accesso. Per eseguire il PATCH di un aggiornamento di un ordine all'API Orders, scarica una chiave dell'account di servizio JSON associata al tuo progetto Actions Console, quindi scambia la chiave dell'account di servizio con un token di connessione che può essere trasmesso all'intestazione Authorization della richiesta HTTP.

Per recuperare la chiave dell'account di servizio, segui questi passaggi:

Nella console Google Cloud, vai a Menu Activate > API e servizi > Credenziali > Crea credenziali > Chiave dell'account di servizio.
In Service Account (Account di servizio), seleziona New Service Account (Nuovo account di servizio).
Imposta l'account di servizio su service-account.
Imposta Ruolo su Progetto > Proprietario.
Imposta il tipo di chiave su JSON.
Seleziona Crea.
Verrà scaricata sulla macchina locale una chiave JSON privata dell'account di servizio.

Nel codice di aggiornamento dell'ordine, puoi scambiare la chiave di servizio con un token di connessione utilizzando la libreria client delle API di Google e l'ambito "https://www.googleapis.com/auth/actions.order.developer". Puoi trovare la procedura di installazione e gli esempi nella pagina GitHub della libreria client API.

Puoi anche fare riferimento a order-update.js nel nostro esempio Node.js per uno scambio di chiavi di esempio.

Invia aggiornamenti sull'ordine

Dopo aver scambiato la chiave dell'account di servizio con un token di connessione OAuth, puoi inviare aggiornamenti degli ordini come richieste PATCH autorizzate all'API Orders.

URL API Orders: PATCH https://actions.googleapis.com/v3/orders/${orderId}

Fornisci le seguenti intestazioni nella richiesta:

"Authorization: Bearer token" con il token di connessione OAuth per cui hai scambiato la chiave dell'account di servizio.
"Content-Type: application/json".

La richiesta PATCH deve avere un corpo JSON con il seguente formato:

{ "orderUpdate": OrderUpdate }

L'oggetto OrderUpdate è costituito dai seguenti campi di primo livello:

updateMask. I campi dell'ordine che stai aggiornando. Per aggiornare lo stato dell'ordine, imposta il valore su purchase.status, purchase.userVisibleStatusLabel.
order: i contenuti dell'aggiornamento. Se aggiorni i contenuti dell'ordine, imposta il valore sull'oggetto Order aggiornato. Se stai aggiornando lo stato dell'ordine (ad esempio da "CONFIRMED" a "SHIPPED"), l'oggetto contiene i seguenti campi:
- merchantOrderId: lo stesso ID impostato nell'oggetto Order.
- lastUpdateTime: il timestamp di questo aggiornamento.
- purchase: un oggetto contenente i seguenti elementi:
  - status: lo stato dell'ordine come PurchaseStatus, ad esempio "SHIPPED" o "DELIVERED".
  - userVisibleStatusLabel: un'etichetta rivolta agli utenti che fornisce dettagli sullo stato dell'ordine, ad esempio "Il tuo ordine è stato spedito ed è in viaggio".
userNotification che può essere visualizzato sul dispositivo dell'utente quando viene inviato questo aggiornamento. Tieni presente che l'inclusione di questo oggetto non garantisce che venga visualizzata una notifica sul dispositivo dell'utente.

Il seguente codice campione mostra un esempio OrderUpdate che aggiorna lo stato dell'ordine a DELIVERED:

// Import the 'googleapis' module for authorizing the request.
const {google} = require('googleapis');
// Import the 'request-promise' module for sending an HTTP POST request.
const request = require('request-promise');
// Import the OrderUpdate class from the client library.
const {OrderUpdate} = require('@assistant/conversation');

// Import the service account key used to authorize the request.
// Replacing the string path with a path to your service account key.
// i.e. const serviceAccountKey = require('./service-account.json')

// Create a new JWT client for the Actions API using credentials
// from the service account key.
let jwtClient = new google.auth.JWT(
    serviceAccountKey.client_email,
    null,
    serviceAccountKey.private_key,
    ['https://www.googleapis.com/auth/actions.order.developer'],
    null,
);

// Authorize the client
let tokens = await jwtClient.authorize();

// Declare order update
const orderUpdate = new OrderUpdate({
    updateMask: {
      paths: [
        'purchase.status',
        'purchase.user_visible_status_label'
      ]
    },
    order: {
      merchantOrderId: orderId, // Specify the ID of the order to update
      lastUpdateTime: new Date().toISOString(),
      purchase: {
        status: 'DELIVERED',
        userVisibleStatusLabel: 'Order delivered',
      },
    },
    reason: 'Order status updated to delivered.',
});

// Set up the PATCH request header and body,
// including the authorized token and order update.
let options = {
  method: 'PATCH',
  uri: `https://actions.googleapis.com/v3/orders/${orderId}`,
  auth: {
    bearer: tokens.access_token,
  },
  body: {
    header: {
      isInSandbox: true,
    },
    orderUpdate,
  },
  json: true,
};

// Send the PATCH request to the Orders API.
try {
  await request(options);
} catch (e) {
  console.log(`Error: ${e}`);
}

Impostare lo stato di acquisto

Il valore status di un aggiornamento dell'ordine deve descrivere lo stato attuale dell'ordine. Nel campo order.purchase.status dell'aggiornamento, utilizza uno dei seguenti valori:

CREATED: l'ordine è accettato dall'utente e "creato" dal punto di vista dell'Azione, ma richiede l'elaborazione manuale nel backend.
CONFIRMED: l'ordine è attivo ed è in fase di elaborazione per l'evasione.
IN_PREPARATION: l'ordine è in fase di preparazione per la spedizione/consegna, ad esempio per la preparazione di cibo o l'imballaggio di un articolo.
READY_FOR_PICKUP: l'ordine è disponibile per il ritiro da parte del destinatario.
DELIVERED - L'ordine è stato recapitato al destinatario
OUT_OF_STOCK: uno o più articoli nell'ordine non sono disponibili.
CHANGE_REQUESTED - L'utente ha richiesto una modifica all'ordine, che è in fase di elaborazione.
RETURNED: l'ordine è stato restituito dall'utente dopo la consegna.
REJECTED - Se non sei riuscito a elaborare, addebitare o "attivare" in altro modo l'ordine.
CANCELLED - L'ordine è stato annullato dall'utente.

Devi inviare aggiornamenti sull'ordine per ogni stato pertinente alla tua transazione. Ad esempio, se la transazione richiede l'elaborazione manuale per registrare l'ordine dopo la sua esecuzione, invia un aggiornamento dell'ordine CREATED fino al termine dell'ulteriore elaborazione. Non tutti gli ordini richiedono un valore di stato.

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:

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

Per le transazioni fisiche, puoi anche impostare il campo isInSandbox su true nel campione. Questa azione equivale all'attivazione dell'impostazione della modalità sandbox nella console di Actions. Per visualizzare uno snippet di codice che utilizza isInSandbox, consulta la sezione Invia aggiornamenti sull'ordine.

Risolvere i problemi

Se riscontri problemi durante il test, consulta la nostra procedura di risoluzione dei problemi relativa alle transazioni.