Panduan ini menuntun Anda dalam proses pengembangan project Action yang menggabungkan transaksi untuk barang fisik dan menggunakan Google Pay untuk pembayaran.
Alur transaksi
Jika project Action Anda menangani transaksi fisik menggunakan pembayaran yang dikelola penjual, menggunakan alur berikut:
- Kumpulkan informasi (opsional) - Tergantung pada sifat
Anda mungkin ingin mengumpulkan informasi berikut dari pengguna di awal
percakapan:
- Validasi persyaratan transaksi - Di awal percakapan, memvalidasi bahwa pengguna memenuhi persyaratan untuk melakukan transaksi, seperti memiliki informasi pembayaran yang dikonfigurasi dengan benar dan tersedia sebelum membuat keranjang belanja.
- Minta alamat pengiriman - Jika transaksi memerlukan pengiriman alamat, mengumpulkannya dari pengguna.
- Buat pesanan - Pandu pengguna untuk "perakitan keranjang" di mana mereka memilih item mana yang ingin mereka beli.
- Usulkan pesanan - Setelah keranjang selesai, usulkan pesanan untuk pengguna sehingga mereka dapat mengkonfirmasi bahwa itu benar. Jika pesanan telah dikonfirmasi, Anda akan menerima respons dengan detail pesanan dan token pembayaran.
- Menyelesaikan pesanan dan mengirimkan tanda terima - Setelah pesanan dikonfirmasi, perbarui pelacakan inventaris atau layanan pemenuhan pesanan lainnya, lalu kirimkan tanda terima kepada pengguna.
- Kirim pembaruan pesanan - Selama masa pakai pemenuhan pesanan, memberikan pembaruan pesanan kepada pengguna dengan mengirimkan permintaan PATCH ke Pesanan Compute Engine API.
Pembatasan dan panduan peninjauan
Perlu diingat bahwa kebijakan tambahan berlaku untuk Tindakan dengan transaksi. Ini kita memerlukan waktu hingga enam minggu untuk meninjau Actions dengan transaksi, jadi pertimbangkan saat merencanakan jadwal rilis. Untuk memudahkan proses peninjauan, pastikan Anda mematuhi kebijakan dan panduan untuk transaksi sebelum mengirimkan Action Anda untuk ditinjau.
Anda hanya dapat men-deploy Action yang menjual barang fisik di negara berikut:
Australia Brasil Kanada Indonesia |
Jepang Meksiko Rusia |
Singapura Thailand Turkiye Inggris Raya Amerika Serikat |
Mem-build project Anda
Untuk melihat contoh lengkap percakapan transaksional, lihat transaksi Node.js contoh.
Penyiapan
Ketika membuat Action, Anda harus menentukan bahwa Anda ingin melakukan transaksi di Konsol Actions.
Untuk menyiapkan project dan fulfillment Anda, lakukan hal berikut:
- Buat project baru atau impor project yang sudah ada.
- Buka Deploy > Informasi direktori.
Di bagian Informasi tambahan > Transaksi > centang kotak yang bertuliskan "Lakukan Tindakan Anda menggunakan Transactions API untuk melakukan transaksi barang fisik?".
1. Mengumpulkan informasi (opsional)
1a. Memvalidasi persyaratan transaksi (opsional)
Segera setelah pengguna menunjukkan bahwa mereka ingin melakukan pembelian, Anda harus memeriksa untuk memastikan bahwa mereka dapat melakukan transaksi. Misalnya, saat dipanggil,Action Anda mungkin bertanya, "apakah Anda ingin memesan sepatu, atau memeriksa saldo rekening?" Jika pengguna mengatakan "pesan sepatu", Anda harus memastikan bahwa mereka dapat melanjutkan dan memberi mereka kesempatan untuk memperbaiki pengaturan apa pun yang mencegah mereka agar tidak melanjutkan transaksi. Untuk melakukannya, Anda harus beralih ke yang melakukan pemeriksaan persyaratan transaksi.
Membuat scene Pemeriksaan Persyaratan Transaksi
- Dari tab Scenes, tambahkan Scene baru dengan nama
TransactionRequirementsCheck
. - Di bagian Pengisian slot, klik + untuk menambahkan slot baru.
- Di bagian Select type, pilih
actions.type.TransactionRequirementsCheckResult
sebagai jenis slot. - Di kolom nama slot, berikan nama
TransactionRequirementsCheck
untuk slot. - Aktifkan kotak centang Customize slot value writeback (diaktifkan secara default).
- Klik Simpan.
Pemeriksaan persyaratan transaksi akan memberikan salah satu hasil berikut:
- Jika persyaratan terpenuhi, parameter sesi ditetapkan dengan keberhasilan dan Anda dapat melanjutkan dengan membuat pesanan pengguna.
- Jika satu atau beberapa persyaratan tidak dapat dipenuhi, parameter sesi akan ditetapkan
dengan kondisi kegagalan. Dalam hal ini, Anda harus mengalihkan arah pembicaraan
dari pengalaman transaksional, atau mengakhiri percakapan.
- Jika ada kesalahan yang mengakibatkan status kegagalan bisa diperbaiki oleh pengguna, mereka akan diminta untuk menyelesaikan masalah itu di perangkat mereka. Jika percakapan akan berlangsung di platform suara saja, serah terima akan dimulai di ponsel pengguna.
Menangani hasil Pemeriksaan Persyaratan Transaksi
- Dari tab Scenes, pilih yang baru Anda buat.
TransactionRequirementsCheck
adegan. - Di bagian Kondisi, klik + untuk menambahkan kondisi baru.
Pada kolom teks, masukkan sintaksis kondisi berikut untuk memeriksa kondisi keberhasilan:
scene.slots.status == "FINAL" && session.params.TransactionRequirementsCheck.resultType == "CAN_TRANSACT"
Arahkan kursor ke kondisi yang baru saja Anda tambahkan dan klik panah atas untuk menempatkannya sebelum
if scene.slots.status == "FINAL"
.Aktifkan Kirim perintah dan berikan perintah sederhana yang memberi tahu pengguna mereka siap untuk melakukan transaksi:
candidates: - first_simple: variants: - speech: >- You are ready to purchase physical goods.
Di bagian Transisi, pilih adegan lain, sehingga pengguna dapat melanjutkan percakapan dan melanjutkan dengan melakukan transaksi.
Pilih kondisi
else if scene.slots.status == "FINAL"
.Aktifkan Kirim perintah dan berikan perintah sederhana yang memberi tahu pengguna mereka tidak dapat melakukan transaksi:
candidates: - first_simple: variants: - speech: Transaction requirements check failed.
Di bagian Transisi, pilih Akhiri percakapan untuk mengakhiri percakapan jika pengguna tidak dapat melakukan transaksi.
Meminta alamat pengiriman
Jika transaksi memerlukan alamat pengiriman pengguna, Anda harus memintanya dari pengguna. Hal ini mungkin berguna untuk menentukan harga total, lokasi pengiriman/pengambilan, atau untuk memastikan pengguna berada dalam region layanan Anda. Untuk melakukannya, Anda harus bertransisi ke adegan yang meminta pengguna untuk alamat pengiriman.
Membuat Adegan Alamat Pengiriman
- Dari tab Scenes, tambahkan scene baru dengan nama
DeliveryAddress
. - Di bagian Pengisian slot, klik + untuk menambahkan slot baru.
- Di bagian Select type, pilih
actions.type.DeliveryAddressValue
sebagai jenis slot. - Di kolom nama slot, berikan nama
TransactionDeliveryAddress
untuk slot. - Aktifkan kotak centang Customize slot value writeback (diaktifkan secara default).
- Klik Save.
Saat mengonfigurasi slot, Anda dapat memberikan reason
yang memungkinkan Anda untuk
mengawali permintaan Asisten untuk mendapatkan alamat dengan string.Setelan default
alasannya adalah "untuk mengetahui ke mana harus mengirim pesanan". Oleh karena itu, Asisten
mungkin bertanya kepada pengguna: "Untuk mengetahui tujuan pengiriman pesanan, saya perlu mendapatkan alamat pengiriman Anda".
- Pada platform dengan layar, pengguna akan memilih alamat yang ingin mereka gunakan untuk transaksi. Jika sebelumnya mereka tidak memberikan alamat, mereka akan bisa memasukkan alamat baru.
- Di platform khusus suara, Asisten akan meminta izin kepada pengguna untuk membagikan alamat {i> default<i} mereka untuk transaksi. Jika mereka belum pernah diberi alamat, percakapan akan diserahkan ke telepon untuk dimasuki.
Untuk menangani hasil Alamat Pengiriman, ikuti langkah-langkah berikut:
- Dari tab Scenes, pilih scene
DeliveryAddress
yang baru dibuat. - Di bagian Kondisi, klik + untuk menambahkan kondisi baru.
Pada kolom teks, masukkan sintaksis kondisi berikut untuk memeriksa kondisi keberhasilan:
scene.slots.status == "FINAL" && session.params.TransactionDeliveryAddress.userDecision == "ACCEPTED"
Arahkan kursor ke kondisi yang baru saja Anda tambahkan dan klik panah atas untuk menempatkannya sebelum
if scene.slots.status == "FINAL"
.Aktifkan Kirim perintah dan berikan perintah sederhana yang memungkinkan pengguna mengetahui bahwa Anda telah menerima alamat mereka:
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
Di bagian Transisi, pilih suasana lain, sehingga pengguna dapat melanjutkan percakapan tersebut.
Pilih kondisi
else if scene.slots.status == "FINAL"
.Aktifkan Kirim perintah dan berikan perintah sederhana yang memberi tahu pengguna mereka tidak dapat melakukan transaksi:
candidates: - first_simple: variants: - speech: I failed to get your delivery address.
Di bagian Transisi, pilih Akhiri percakapan untuk mengakhiri percakapan jika pengguna tidak dapat melakukan transaksi.
Membuat pesanan
Setelah memiliki informasi pengguna yang dibutuhkan, Anda akan membuat perakitan" pengalaman yang memandu pengguna untuk membuat pesanan. Setiap Tindakan akan memiliki alur perakitan keranjang yang sedikit berbeda yang sesuai dengan produk atau layanan Anda.
Pengalaman perakitan keranjang yang paling dasar membuat pengguna memilih item dari daftar untuk ditambahkan sesuai urutannya, meskipun Anda dapat merancang percakapan untuk menyederhanakan {i>user experience<i}. Anda dapat membangun pengalaman perakitan keranjang yang memungkinkan untuk memesan ulang pembelian terbaru mereka melalui pertanyaan ya atau tidak. Anda juga dapat menyajikan {i>carousel<i} atau kartu daftar dari daftar “{i>featured<i}” teratas atau "direkomendasikan" item.
Sebaiknya gunakan rich respons untuk menampilkan opsi pengguna secara visual, tetapi juga merancang percakapan sedemikian rupa sehingga pengguna dapat membangun keranjang hanya menggunakan suara mereka. Untuk beberapa praktik terbaik dan contoh perakitan keranjang berkualitas tinggi, lihat Pedoman desain.
Membuat pesanan
Sepanjang percakapan, Anda harus mengumpulkan hal-hal yang diinginkan pengguna
dibeli lalu membuat objek Order
.
Minimal, Order
Anda harus berisi hal berikut:
buyerInfo
- Informasi tentang pengguna yang melakukan pembelian.transactionMerchant
- Informasi tentang penjual yang difasilitasi pesanan.contents
- Konten pesanan sebenarnya yang tercantum sebagailineItems
.priceAttributes
- Detail harga pesanan, termasuk total biaya pesanan dengan diskon dan pajak.
Lihat Order
dokumentasi respons untuk menyusun keranjang. Perhatikan bahwa Anda mungkin perlu menyertakan
{i>field<i} yang berbeda tergantung
pada urutannya.
Kode contoh di bawah menunjukkan pesanan yang lengkap, termasuk kolom opsional:
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',
},
};
Membuat opsi urutan dan presentasi
Sebelum pengguna mengonfirmasi pesanan mereka, mereka akan disajikan dengan proposal kartu pesanan. Anda dapat menyesuaikan cara kartu ini ditampilkan kepada pengguna dengan mengatur berbagai opsi urutan dan presentasi.
Berikut adalah opsi pemesanan dan presentasi untuk melakukan pemesanan yang memerlukan alamat pengiriman, termasuk email pengguna di kartu konfirmasi pesanan:
const orderOptions = {
'requestDeliveryAddress': true,
'userInfoOptions': {
'userInfoProperties': ['EMAIL']
}
};
const presentationOptions = {
'actionDisplayName': 'PLACE_ORDER'
};
Membuat parameter pembayaran
Objek paymentParameters
Anda akan menyertakan parameter tokenisasi yang
berubah, bergantung pada pemroses Google Pay yang ingin Anda gunakan
(seperti Stripe, Braintree, ACI, dll.).
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',
},
}),
},
};
Konten objek tokenizationSpecification
akan berbeda untuk masing-masing
gateway pembayaran. Tabel berikut menunjukkan parameter yang digunakan oleh setiap 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" }
Simpan data pesanan di parameter sesi
Dari pemenuhan pesanan Anda, simpan data pesanan ke parameter sesi. Urutan akan digunakan di seluruh adegan untuk sesi yang sama.
conv.session.params.order = {
'@type': 'type.googleapis.com/google.actions.transactions.v3.TransactionDecisionValueSpec',
order: order,
orderOptions: orderOptions,
presentationOptions: presentationOptions,
paymentParameters: paymentParameters
};
Ajukan pesanan
Setelah membuat pesanan, Anda harus menunjukkannya kepada pengguna untuk dikonfirmasi atau ditolak. Untuk melakukannya, Anda harus beralih ke adegan yang menjalankan keputusan transaksi.
Membuat scene Keputusan Transaksi
- Dari tab Scenes, tambahkan scene baru dengan nama
TransactionDecision
. - Di bagian Pengisian slot, klik + untuk menambahkan slot baru.
- Di bagian Select type, pilih
actions.type.TransactionDecisionValue
sebagai jenis slot. - Di kolom nama slot, berikan nama
TransactionDecision
untuk slot. - Aktifkan kotak centang Customize slot value writeback (diaktifkan secara default).
- Di bagian Konfigurasi slot, pilih Gunakan parameter sesi dari menu dropdown.
- Di bagian Konfigurasi slot, masukkan nama parameter sesi yang digunakan
untuk menyimpan pesanan ke dalam kolom teks (yaitu
$session.params.order
). - Klik Save.
Dalam upaya mengisi slot TransactionDecisionValue
, Asisten memulai
pengalaman bawaan tempat Order
yang Anda teruskan dirender langsung ke
"kartu pratinjau keranjang". Pengguna dapat mengucapkan "lakukan pemesanan", menolak transaksi,
mengubah opsi pembayaran seperti kartu kredit atau alamat, atau meminta perubahan
isi pesanan.
Pengguna juga dapat meminta perubahan pada pesanan pada tahap ini. Dalam hal ini, Anda harus memastikan bahwa pemenuhan pesanan Anda dapat menangani permintaan perubahan pesanan setelah menyelesaikan pengalaman perakitan keranjang.
Menangani hasil Keputusan Transaksi
Saat slot TransactionDecisionValue
terisi, jawaban pengguna atas
keputusan transaksi akan
disimpan dalam parameter sesi. Nilai ini berisi
hal berikut:
ORDER_ACCEPTED
,ORDER_REJECTED
,DELIVERY_ADDRESS_UPDATED
,CART_CHANGE_REQUESTED
USER_CANNOT_TRANSACT
.
Untuk menangani hasil keputusan transaksi:
- Dari tab Scenes, pilih scene
TransactionDecision
yang baru dibuat. - Di bagian Kondisi, klik + untuk menambahkan kondisi baru.
Di kolom teks, masukkan sintaksis kondisi berikut untuk memeriksa kondisi berhasil:
scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"
Arahkan kursor ke kondisi yang baru saja Anda tambahkan dan klik panah atas untuk menempatkannya sebelum
if scene.slots.status == "FINAL"
.Aktifkan Kirim perintah dan berikan perintah sederhana yang memberi tahu pengguna pesanannya selesai:
candidates: - first_simple: variants: - speech: >- Transaction completed! Your order $session.params.TransactionDecision.order.merchantOrderId is all set!
Di bagian Transisi, pilih Akhiri percakapan untuk mengakhiri percakapan.
Di bagian Kondisi, klik + untuk menambahkan kondisi baru.
Pada kolom teks, masukkan sintaksis kondisi berikut untuk memeriksa kondisi kegagalan:
scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_REJECTED"
Arahkan kursor ke kondisi yang baru saja Anda tambahkan dan klik panah atas untuk menempatkannya sebelum
if scene.slots.status == "FINAL"
.Aktifkan Kirim perintah dan berikan perintah sederhana yang memberi tahu pengguna pesanan telah ditolak:
candidates: - first_simple: variants: - speech: Look like you don't want to order anything. Goodbye.
Di bagian Transisi, pilih Akhiri percakapan untuk mengakhiri percakapan.
Pilih kondisi
else if scene.slots.status == "FINAL"
.Aktifkan Kirim perintah dan berikan perintah sederhana yang memungkinkan pengguna tahu bahwa mereka tidak dapat melakukan transaksi:
candidates: - first_simple: variants: - speech: >- Transaction failed with status $session.params.TransactionDecision.transactionDecision
Di bagian Transisi, pilih Akhiri percakapan untuk mengakhiri percakapan jika pengguna tidak dapat melakukan transaksi.
Menyelesaikan pesanan dan mengirimkan tanda terima
Saat slot TransactionDecisionValue
menampilkan hasil ORDER_ACCEPTED
,
Anda harus segera melakukan pemrosesan
apa pun yang diperlukan untuk "mengonfirmasi" tindakan
urutannya (seperti mempertahankannya di {i>database<i} Anda sendiri dan menagih pengguna).
Anda dapat mengakhiri percakapan dengan respons ini, tetapi Anda harus menyertakan
untuk menjaga agar percakapan tetap berjalan. Saat Anda memberikan
orderUpdate
, pengguna akan melihat "kartu tanda terima diciutkan" beserta sisanya
respons Anda. Kartu ini akan mencerminkan tanda terima yang ditemukan pengguna di
Histori Pesanan.
Selama konfirmasi pesanan, objek pesanan Anda dapat menyertakan userVisibleOrderId
,
yang merupakan ID yang dilihat
pengguna untuk pesanan itu. Anda dapat menggunakan kembali
merchantOrderId
untuk kolom ini.
Bagian dari objek OrderUpdate
harus berisi objek tindakan tindak lanjut,
yang berwujud sebagai tombol URL di bagian bawah detail pesanan yang
dapat ditemukan di Histori Pesanan Asisten mereka.
- Anda harus memberikan, minimal,
VIEW_DETAILS
Menindaklanjuti setiap pesanan. Kolom ini harus berisi deep link ke representasi pesanan di aplikasi seluler atau situs web Anda. - Anda juga harus mengirimkan tanda terima resmi melalui email yang memenuhi persyaratan hukum persyaratan untuk melakukan transaksi, selain kartu tanda terima dalam percakapan Action Anda.
Untuk mengirim pembaruan pesanan awal:
- Dari tab Scenes, pilih scene
TransactionDecision
. Di bagian Kondisi, pilih kondisi yang memeriksa hasil yang berhasil.
ORDER_ACCEPTED
:scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"
Untuk kondisi ini, aktifkan Call your webhook, dan berikan intent nama pengendali, seperti
update_order
.Di kode webhook Anda, tambahkan pengendali intent untuk mengirim pesanan awal perbarui:
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 })); });
Kirim pembaruan pesanan
Anda harus terus memberi tahu pengguna tentang status pesanan selama masa pakainya. Mengirim pembaruan pesanan pengguna dengan mengirim HTTP Permintaan PATCH ke Orders API dengan status dan detail pesanan.
Menyiapkan permintaan asinkron ke Orders API
Permintaan pembaruan pesanan ke Orders API diotorisasi oleh akses
sebelumnya yang benar. Untuk melakukan PATCH pembaruan pesanan ke Orders API, download JSON
kunci akun layanan yang terkait dengan project Konsol Actions Anda, lalu tukar
kunci akun layanan untuk token pemilik yang dapat diteruskan ke
Header Authorization
dari permintaan HTTP.
Untuk mengambil kunci akun layanan Anda, lakukan langkah-langkah berikut:
- Di Konsol Google Cloud, buka Menu Unduh > API & Layanan > Kredensial > Buat kredensial > Kunci akun layanan.
- Di bagian Akun Layanan, pilih Akun Layanan Baru.
- Setel akun layanan ke
service-account
. - Tetapkan Role ke Project > Pemilik.
- Tetapkan jenis kunci ke JSON.
- Pilih Create.
- Kunci akun layanan JSON pribadi akan didownload ke komputer lokal Anda.
Dalam kode pembaruan pesanan, Anda dapat menukar kunci layanan dengan token pemilik menggunakan library klien Google API dan "https://www.googleapis.com/auth/actions.order.developer". Anda dapat menemukan langkah-langkah dan contoh penginstalan di library klien API Halaman GitHub.
Anda juga dapat mereferensikan order-update.js
di
Contoh Node.js
untuk contoh pertukaran kunci.
Kirim pembaruan pesanan
Setelah menukarkan kunci akun layanan dengan token pembawa OAuth, Anda dapat mengirimkan pembaruan pesanan sebagai permintaan PATCH yang diberi otorisasi ke Orders API.
URL API Pesanan:
PATCH https://actions.googleapis.com/v3/orders/${orderId}
Berikan header berikut dalam permintaan Anda:
"Authorization: Bearer token"
dengan token pemilik OAuth yang Anda tukarkan dengan kunci akun layanan Anda."Content-Type: application/json"
.
Permintaan PATCH harus menggunakan isi JSON dengan format berikut:
{ "orderUpdate": OrderUpdate }
OrderUpdate
terdiri dari kolom level teratas berikut ini:
updateMask
- Kolom pesanan yang sedang Anda perbarui. Untuk memperbarui status pesanan, tetapkan nilai kepurchase.status, purchase.userVisibleStatusLabel
.order
- Konten update. Jika Anda memperbarui isi pesanan, tetapkan nilai ke objekOrder
yang diperbarui. Jika Anda memperbarui status pesanan (misalnya, dari"CONFIRMED"
hingga"SHIPPED"
), objek berisi kolom berikut:merchantOrderId
- ID yang sama dengan yang Anda tetapkan di objekOrder
.lastUpdateTime
- Stempel waktu update ini.purchase
- Objek yang berisi hal berikut:status
- Status pesanan sebagaiPurchaseStatus
, seperti "SHIPPED
" atau "DELIVERED
".userVisibleStatusLabel
- Label yang ditampilkan kepada pengguna yang memberikan detail tentang status pesanan, seperti "Pesanan Anda telah dikirim dan berada di ".
userNotification
(opsional) - AuserNotification
yang dapat ditampilkan di perangkat pengguna saat pembaruan ini dikirimkan. Catatan bahwa menyertakan objek ini tidak menjamin bahwa notifikasi muncul di perangkat pengguna.
Kode contoh berikut menunjukkan contoh OrderUpdate
yang memperbarui
status pesanan menjadi 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}`);
}
Menetapkan status pembelian
status
pembaruan pesanan
harus mendeskripsikan status pesanan saat ini. Dalam order.purchase.status
update Anda
gunakan salah satu nilai berikut:
CREATED
- Pesanan diterima oleh pengguna dan "dibuat" dari perspektif Action Anda, tetapi memerlukan pemrosesan manual di back-end Anda.CONFIRMED
- Pesanan aktif dan sedang diproses untuk pemenuhan pesanan.IN_PREPARATION
- Pesanan sedang disiapkan untuk pengiriman, seperti makanan sedang dimasak atau barang yang dikemas.READY_FOR_PICKUP
- Pesanan tersedia untuk diambil oleh penerima.DELIVERED
- Pesanan telah dikirim ke penerimaOUT_OF_STOCK
- Satu atau beberapa item dalam pesanan habis.CHANGE_REQUESTED
- Pengguna meminta perubahan pada pesanan, dan perubahan tersebut sedang diproses.RETURNED
- Pesanan telah dikembalikan oleh pengguna setelah pengiriman.REJECTED
- Jika Anda tidak dapat memproses, menagih, atau melakukan tindakan lainnya "aktifkan" pesanan.CANCELLED
- Pesanan dibatalkan oleh pengguna.
Anda harus mengirimkan pembaruan pesanan untuk setiap status yang relevan dengan
transaksi. Misalnya, jika transaksi Anda memerlukan pemrosesan manual untuk
catat pesanan setelah dilakukan, kirim pembaruan pesanan CREATED
hingga
bahwa pemrosesan tambahan itu selesai. Tidak semua pesanan memerlukan setiap nilai status.
Menguji project Anda
Saat menguji project, Anda dapat mengaktifkan mode sandbox di Konsol Actions untuk menguji Action Anda tanpa menagih metode pembayaran. Untuk mengaktifkan mode sandbox, ikuti langkah-langkah berikut:
- Di Konsol Actions, klik Test di navigasi.
- Klik Setelan.
- Aktifkan opsi Development Sandbox.
Untuk transaksi fisik, Anda juga dapat menetapkan kolom isInSandbox
ke true
di
sampel Anda. Tindakan ini sama dengan mengaktifkan setelan mode {i>sandbox<i} di
konsol Actions. Untuk melihat cuplikan kode yang menggunakan isInSandbox
, lihat
Bagian Kirim pembaruan pesanan.
Pemecahan masalah
Jika mengalami masalah selama pengujian, Anda harus membaca langkah pemecahan masalah kami untuk transaksi.