Questa guida ti accompagna nella procedura di sviluppo di un progetto Actions che incorpora transazioni per beni fisici e utilizza Google Pay per i pagamenti.
Flusso delle transazioni
Quando il tuo progetto Actions gestisce le transazioni fisiche mediante pagamenti gestiti dal commerciante, utilizza il seguente flusso:
- Raccogliere informazioni (facoltativo). A seconda della natura della transazione, potresti voler raccogliere le seguenti informazioni dall'utente all'inizio della conversazione:
- Convalida dei requisiti della transazione: all'inizio della conversazione, verifica che l'utente soddisfi i requisiti per effettuare una transazione, ad esempio se i dati di pagamento sono configurati e disponibili correttamente prima di creare il carrello.
- 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 Russia |
Singapore Thailandia Turchia Regno Unito Stati Uniti |
Crea il tuo progetto
Per esempi completi di conversazioni transazionali, visualizza l'esempio di transazioni Node.js.
Configurazione
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?".
1. Raccogliere informazioni (facoltativo)
1a. (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 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 (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
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 sulla progettazione.
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 comelineItems
.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, incluso l'indirizzo 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
includerà parametri di tokenizzazione che cambiano a seconda del processore di Google Pay che intendi utilizzare (ad esempio Stripe, Braintree, ACI e così via).
const paymentParamenters = {
'googlePaymentOption': {
// facilitationSpec is expected to be a serialized JSON string
'facilitationSpec': JSON.stringify({
'apiVersion': 2,
'apiVersionMinor': 0,
'merchantInfo': {
'merchantName': 'Example Merchant',
},
'allowedPaymentMethods': [
{
'type': 'CARD',
'parameters': {
'allowedAuthMethods': ['PAN_ONLY', 'CRYPTOGRAM_3DS'],
'allowedCardNetworks': [
'AMEX', 'DISCOVER', 'JCB', 'MASTERCARD', 'VISA'],
},
'tokenizationSpecification': {
'type': 'PAYMENT_GATEWAY',
'parameters': {
'gateway': 'example',
'gatewayMerchantId': 'exampleGatewayMerchantId',
},
},
},
],
'transactionInfo': {
'totalPriceStatus': 'FINAL',
'totalPrice': '15.77',
'currencyCode': 'USD',
},
}),
},
};
I contenuti dell'oggetto tokenizationSpecification
saranno diversi per ciascun gateway di pagamento. La tabella seguente mostra i parametri utilizzati da ciascun gateway:
"parameters": { "gateway": "example", "gatewayMerchantId": "exampleGatewayMerchantId" }
"parameters": { "gateway": "aciworldwide", "gatewayMerchantId": "YOUR_ENTITY_ID" }
"parameters": { "gateway": "adyen", "gatewayMerchantId": "YOUR_MERCHANT_ACCOUNT_NAME" }
"parameters": { "gateway": "alfabank", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "bluemedia", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "bluesnap", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "braintree", "braintree:apiVersion": "v1", "braintree:sdkVersion": braintree.client.VERSION, "braintree:merchantId": "YOUR_BRAINTREE_MERCHANT_ID", "braintree:clientKey": "YOUR_BRAINTREE_TOKENIZATION_KEY" }
"parameters": { "gateway": "chase", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ACCOUNT_NUMBER" }
"parameters": { "gateway": "checkoutltd", "gatewayMerchantId": "YOUR_PUBLIC_KEY" }
"parameters": { "gateway": "cloudpayments", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "cybersource", "gatewayMerchantId": "YOUR_MERCHANT_ID" }
"parameters": { "gateway": "datatrans", "gatewayMerchantId": "YOUR_MERCHANT_ID" }
"parameters": { "gateway": "ebanx", "gatewayMerchantId": "YOUR_PUBLIC_INTEGRATION_KEY" }
"parameters": { "gateway": "firstdata", "gatewayMerchantId": "YOUR_MERCHANT_ID" }
"parameters": { "gateway": "globalpayments", "gatewayMerchantId": "YOUR_MERCHANT_ID" }
"parameters": { "gateway": "gopay", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "hitrustpay", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "imsolutions", "gatewayMerchantId": "YOUR_MERCHANT_ID" }
"parameters": { "gateway": "lyra", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "mpgs", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "moneymailru", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "newebpay", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "nexi", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "creditcall", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "paysafe", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "payture", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "payu", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "przelewy24", "gatewayMerchantId": "YOUR_MERCHANT_ID" }
"parameters": { "gateway": "rbkmoney", "gatewayMerchantId": "YOUR_MERCHANT_ID" }
"parameters": { "gateway": "sberbank", "gatewayMerchantId": "YOUR_ORGANIZATION_NAME" }
"parameters": { "gateway": "square", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "stripe", "stripe:version": "2018-10-31", "stripe:publishableKey": "YOUR_PUBLIC_STRIPE_KEY" }
"parameters": { "gateway": "tappay", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "tinkoff", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "uniteller", "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID" }
"parameters": { "gateway": "vantiv", "vantiv:merchantPayPageId": "YOUR_PAY_PAGE_ID", "vantiv:merchantOrderId": "YOUR_ORDER_ID", "vantiv:merchantTransactionId": "YOUR_TRANSACTION_ID", "vantiv:merchantReportGroup": "*web" }
"parameters": { "gateway": "worldpay", "gatewayMerchantId": "YOUR_WORLDPAY_MERCHANT_ID" }
"parameters": { "gateway": "yandexcheckout", "gatewayMerchantId": "YOUR_SHOP_ID" }
Salva i dati degli ordini nel parametro di sessione
Dal evasione degli ordini, salva i dati dell'ordine in un parametro di sessione. L'oggetto 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 supurchase.status, purchase.userVisibleStatusLabel
.order
: i contenuti dell'aggiornamento. Se aggiorni i contenuti dell'ordine, imposta il valore sull'oggettoOrder
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'oggettoOrder
.lastUpdateTime
: il timestamp di questo aggiornamento.purchase
: un oggetto contenente i seguenti elementi:status
: lo stato dell'ordine comePurchaseStatus
, 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 destinatarioOUT_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.