Panduan ini menuntun Anda melalui proses pengembangan project Action yang menggabungkan transaksi untuk barang fisik menggunakan metode pembayaran yang dikelola oleh situs Anda.
Alur transaksi
Saat project Action Anda menangani transaksi fisik menggunakan pembayaran yang dikelola penjual, project tersebut akan menggunakan alur berikut:
- Menautkan akun pengguna - Agar pengguna dapat menggunakan metode pembayaran yang telah mereka simpan di layanan Anda, gunakan Penautan Akun untuk mengaitkan Akun Google mereka dengan akun miliknya di layanan Anda.
- Kumpulkan informasi (opsional) - Bergantung pada sifat transaksi, sebaiknya Anda mengumpulkan informasi berikut dari pengguna di awal percakapan:
- Validasi persyaratan transaksi - Di awal bagian transaksi dalam percakapan, validasi bahwa pengguna memenuhi persyaratan untuk melakukan transaksi, seperti memiliki informasi pembayaran yang dikonfigurasi dan tersedia dengan benar sebelum membuat keranjang mereka.
- Meminta alamat pengiriman - Jika transaksi memerlukan alamat pengiriman, kumpulkan alamat pengiriman dari pengguna.
- Membuat pesanan - Pandu pengguna dalam "perakitan keranjang" untuk memilih item yang ingin dibeli.
- Mengusulkan pesanan - Setelah keranjang selesai, ajukan pesanan kepada pengguna agar mereka dapat mengonfirmasi bahwa pesanan tersebut sudah benar. Jika pesanan dikonfirmasi, Anda akan menerima respons dengan detail pesanan dan token pembayaran.
- Menyelesaikan pesanan dan mengirim tanda terima - Setelah pesanan dikonfirmasi, perbarui pelacakan inventaris atau layanan pemenuhan lainnya, lalu kirim tanda terima kepada pengguna.
- Mengirim pembaruan pesanan - Selama masa aktif pemenuhan pesanan, berikan pembaruan pesanan kepada pengguna dengan mengirimkan permintaan PATCH ke Orders API.
Pembatasan dan panduan peninjauan
Perlu diingat bahwa kebijakan tambahan berlaku untuk Action dengan transaksi. Kami memerlukan waktu hingga enam minggu untuk meninjau Action dengan transaksi, jadi pertimbangkan waktu tersebut saat merencanakan jadwal rilis Anda. Untuk memudahkan proses peninjauan, pastikan Anda mematuhi kebijakan dan panduan untuk transaksi sebelum mengirimkan Action untuk ditinjau.
Anda hanya dapat men-deploy Action yang menjual barang fisik di negara berikut:
Australia Brasil Kanada Indonesia |
Jepang Meksiko Qatar Rusia |
Singapura Swiss Thailand Turki Inggris Raya Amerika Serikat |
Mem-build project Anda
Untuk contoh percakapan transaksional, lihat contoh transaksi Node.js.
Penyiapan project
Saat 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 ada.
- Buka Deploy > Directory information.
Di bagian Additional information > Transactions > centang kotak yang bertuliskan "Apakah Actions Anda menggunakan Transactions API untuk melakukan transaksi barang fisik?".
Menautkan akun pengguna (opsional)
Saat menggunakan metode pembayaran Anda sendiri untuk menagih pengguna, sebaiknya tautkan Akun Google mereka dengan akun yang mereka miliki dengan layanan Anda sendiri untuk mengambil, menyajikan, dan menagih metode pembayaran yang disimpan di sana.
Mendesain antarmuka pengguna suara untuk alur autentikasi
Periksa apakah pengguna telah diverifikasi dan mulai alur penautan akun
- Buka project Action Builder Anda di Konsol Actions.
- Buat scene baru untuk memulai penautan akun di Action Anda:
- Klik Scene.
- Klik ikon add (+) untuk menambahkan adegan baru.
- Pada scene yang baru dibuat, klik ikon tambahkan add untuk Kondisi.
- Tambahkan kondisi yang memeriksa apakah pengguna yang terkait dengan percakapan adalah
pengguna terverifikasi. Jika pemeriksaan gagal, Action Anda tidak dapat melakukan penautan akun
selama percakapan, dan harus kembali menyediakan akses ke
fungsi yang tidak memerlukan penautan akun.
- Di kolom
Enter new expression
pada bagian Kondisi, masukkan logika berikut:user.verificationStatus != "VERIFIED"
- Di bagian Transition, pilih scene yang tidak memerlukan penautan akun atau scene yang merupakan titik entri ke fungsi khusus tamu.
- Di kolom
- Klik ikon tambahkan add untuk Kondisi.
- Tambahkan kondisi untuk memicu alur penautan akun jika pengguna tidak memiliki
identitas terkait.
- Di kolom
Enter new expression
pada bagian Kondisi, masukkan logika berikut:user.verificationStatus == "VERIFIED"
- Di bagian Transisi, pilih scene sistem Penautan Akun.
- Klik Simpan.
- Di kolom
Setelah disimpan, scene sistem penautan akun baru yang disebut <SceneName>_AccountLinking
akan ditambahkan ke project Anda.
Menyesuaikan adegan penautan akun
- Di bagian Scene, pilih scene sistem penautan akun.
- Klik Kirim perintah dan tambahkan kalimat singkat untuk menjelaskan kepada pengguna alasan Action perlu mengakses identitas mereka (misalnya, "Untuk menyimpan preferensi Anda").
- Klik Simpan.
- Di bagian Kondisi, klik Jika pengguna berhasil menyelesaikan penautan akun.
- Konfigurasi cara alur berjalan jika pengguna setuju untuk menautkan akun mereka. Misalnya, panggil webhook untuk memproses logika bisnis kustom yang diperlukan dan lakukan transisi kembali ke scene asal.
- Klik Simpan.
- Di bagian Kondisi, klik Jika pengguna membatalkan atau menolak penautan akun.
- Konfigurasikan cara alur akan dilanjutkan jika pengguna tidak setuju untuk menautkan akunnya. Misalnya, kirim pesan konfirmasi dan alihkan ke scene yang menyediakan fungsi yang tidak memerlukan penautan akun.
- Klik Simpan.
- Di bagian Kondisi, klik Jika terjadi error sistem atau jaringan.
- Konfigurasikan cara alur akan dilanjutkan jika alur penautan akun tidak dapat diselesaikan karena error sistem atau jaringan. Misalnya, kirim pesan konfirmasi dan alihkan ke scene yang menyediakan fungsi yang tidak memerlukan penautan akun.
- Klik Simpan.
Mengumpulkan informasi (opsional)
Memvalidasi persyaratan transaksi (opsional)
Segera setelah pengguna menyatakan bahwa mereka ingin melakukan pembelian, Anda harus memeriksa untuk memastikan bahwa mereka dapat melakukan transaksi. Misalnya, saat dipanggil,Action Anda mungkin menanyakan, "Apakah Anda ingin memesan sepatu, atau memeriksa saldo rekening?" Jika pengguna mengucapkan "pesan sepatu", Anda harus memastikan bahwa mereka dapat melanjutkan dan memberinya kesempatan untuk memperbaiki setelan apa pun yang mencegah mereka melanjutkan transaksi. Untuk melakukannya, Anda harus beralih ke adegan yang melakukan pemeriksaan persyaratan transaksi.
Membuat scene Pemeriksaan Persyaratan Transaksi
- Dari tab Scene, tambahkan Scene baru dengan nama
TransactionRequirementsCheck
. - Di bagian Slot fill, klik + untuk menambahkan slot baru.
- Di bagian Select type, pilih
actions.type.TransactionRequirementsCheckResult
sebagai jenis slot. - Di kolom nama slot, beri nama
TransactionRequirementsCheck
pada slot. - Aktifkan kotak centang Customize slot value writeback (diaktifkan secara default).
Klik Simpan.
Pemeriksaan persyaratan transaksi akan memberikan salah satu hasil berikut:
- Jika persyaratannya terpenuhi, parameter sesi akan ditetapkan dengan kondisi berhasil dan Anda dapat melanjutkan pembuatan urutan pengguna.
- Jika satu atau beberapa persyaratan tidak dapat dipenuhi, parameter sesi ditetapkan dengan kondisi kegagalan. Dalam hal ini, Anda harus mengalihkan percakapan
dari pengalaman transaksional, atau mengakhiri percakapan.
- Jika error yang mengakibatkan status kegagalan dapat diperbaiki oleh pengguna, mereka akan diminta untuk menyelesaikan masalah tersebut di perangkat. Jika percakapan terjadi di platform suara saja, serah terima akan dimulai di ponsel pengguna.
Menangani hasil Pemeriksaan Persyaratan Transaksi
- Dari tab Scenes, pilih scene
TransactionRequirementsCheck
yang baru dibuat. - Pada bagian Kondisi, klik + untuk menambahkan kondisi baru.
Di 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 ditambahkan, lalu klik panah atas untuk menempatkannya sebelum
if scene.slots.status == "FINAL"
.Aktifkan Kirim perintah dan berikan perintah sederhana yang memberi tahu pengguna bahwa mereka siap melakukan transaksi:
candidates: - first_simple: variants: - speech: >- You are ready to purchase physical goods.
Di bagian Transition, pilih scene lain yang memungkinkan pengguna melanjutkan percakapan dan melakukan transaksi.
Pilih kondisi
else if scene.slots.status == "FINAL"
.Aktifkan Kirim perintah dan berikan perintah sederhana yang memberi tahu pengguna bahwa mereka tidak dapat melakukan transaksi:
candidates: - first_simple: variants: - speech: Transaction requirements check failed.
Di bagian Transition, pilih End conversation untuk mengakhiri percakapan jika pengguna tidak dapat melakukan transaksi.
Meminta alamat pengiriman (opsional)
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 wilayah layanan Anda. Untuk melakukannya, Anda harus beralih ke scene yang meminta pengguna untuk memasukkan alamat pengiriman.
Membuat Adegan Alamat Pengiriman
- Dari tab Scenes, tambahkan scene baru dengan nama
DeliveryAddress
. - Di bagian Slot fill, klik + untuk menambahkan slot baru.
- Di bagian Pilih jenis, pilih
actions.type.DeliveryAddressValue
sebagai jenis slot. - Di kolom nama slot, beri nama
TransactionDeliveryAddress
pada slot. - Aktifkan kotak centang Customize slot value writeback (diaktifkan secara default).
- Klik Save.
Saat mengonfigurasi slot, Anda dapat memberikan reason
yang memungkinkan Anda
mengawali permintaan Asisten untuk mendapatkan alamat dengan string.String alasan
defaultnya adalah "mengetahui ke mana harus mengirimkan pesanan". Oleh karena itu, Asisten
mungkin bertanya kepada pengguna: "Untuk mengetahui alamat pengiriman pesanan Anda, saya perlu mendapatkan alamat pengiriman".
- Pada platform dengan layar, pengguna akan memilih alamat yang ingin mereka gunakan untuk transaksi. Jika sebelumnya belum pernah memberikan alamat, mereka akan dapat memasukkan alamat baru.
- Pada platform suara saja, Asisten akan meminta izin kepada pengguna untuk membagikan alamat default mereka untuk transaksi. Jika mereka belum pernah memberikan alamat, percakapan akan diserahkan ke ponsel untuk entri.
Untuk menangani hasil Alamat Pengiriman, ikuti langkah-langkah berikut:
- Dari tab Scenes, pilih scene
DeliveryAddress
yang baru dibuat. - Pada bagian Kondisi, klik + untuk menambahkan kondisi baru.
Di 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 ditambahkan, lalu klik panah atas untuk menempatkannya sebelum
if scene.slots.status == "FINAL"
.Aktifkan Kirim perintah dan berikan perintah sederhana yang memberi tahu pengguna bahwa Anda telah menerima alamatnya:
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 Transition, pilih scene lain yang memungkinkan pengguna melanjutkan percakapan.
Pilih kondisi
else if scene.slots.status == "FINAL"
.Aktifkan Kirim perintah dan berikan perintah sederhana yang memberi tahu pengguna bahwa mereka tidak dapat melakukan transaksi:
candidates: - first_simple: variants: - speech: I failed to get your delivery address.
Di bagian Transition, pilih End conversation untuk mengakhiri percakapan jika pengguna tidak dapat melakukan transaksi.
Membuat pesanan
Setelah memiliki informasi pengguna yang dibutuhkan, Anda akan mem-build pengalaman "keranjang keranjang" yang memandu pengguna untuk membuat pesanan. Setiap Action akan memiliki alur perakitan keranjang yang sedikit berbeda yang sesuai untuk produk atau layanannya.
Pengalaman perakitan keranjang yang paling dasar memungkinkan pengguna memilih item dari daftar untuk ditambahkan ke pesanannya, meskipun Anda dapat mendesain percakapan untuk menyederhanakan pengalaman pengguna. Anda dapat mem-build pengalaman perakitan keranjang yang memungkinkan pengguna memesan ulang pembelian terbarunya melalui pertanyaan sederhana ya atau tidak. Anda juga dapat menyajikan carousel atau kartu daftar dari item "unggulan" atau "direkomendasikan" kepada pengguna.
Sebaiknya gunakan respons lengkap untuk menampilkan opsi pengguna secara visual, sekaligus desain percakapan sedemikian rupa sehingga pengguna dapat membuat keranjangnya hanya menggunakan suara. Untuk beberapa praktik terbaik dan contoh pengalaman penggabungan keranjang yang berkualitas tinggi, lihat Panduan Desain Transaksi.
Membuat pesanan
Selama percakapan, Anda harus mengumpulkan item yang ingin dibeli pengguna, lalu membuat objek Order
.
Minimal, Order
Anda harus berisi hal berikut:
buyerInfo
- Informasi tentang pengguna yang melakukan pembelian.transactionMerchant
- Informasi tentang penjual yang memfasilitasi pesanan.contents
- Konten pesanan sebenarnya yang dicantumkan sebagailineItems
.priceAttributes
- Detail harga pesanan, termasuk total biaya pesanan dengan diskon dan pajak.
Lihat dokumentasi respons Order
untuk membuat keranjang. Perhatikan bahwa Anda mungkin perlu menyertakan
kolom yang berbeda bergantung pada urutannya.
Kode contoh di bawah menunjukkan urutan 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',
},
};
Buat opsi urutan dan presentasi
Sebelum mengonfirmasi pesanan, pengguna akan melihat kartu pesanan yang diusulkan. Anda dapat menyesuaikan cara kartu ini ditampilkan kepada pengguna dengan menetapkan berbagai opsi urutan dan presentasi.
Berikut adalah opsi urutan dan presentasi untuk melakukan pesanan 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 menyertakan merchantPaymentOption
dengan kolom
yang menjelaskan metode pembayaran pengguna untuk pesanannya. Berikut adalah contoh parameter pembayaran, menggunakan kartu kredit 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'
}
}]
}
};
Simpan data pesanan di parameter sesi
Dari fulfillment Anda, simpan data pesanan ke parameter session
.
Objek urutan akan digunakan di seluruh scene 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
};
Mengusulkan pesanan
Setelah membuat pesanan, Anda harus menunjukkannya kepada pengguna untuk mengonfirmasi atau menolak. Untuk melakukannya, Anda harus bertransisi ke scene yang melakukan keputusan transaksi.
Membuat scene Keputusan Transaksi
- Dari tab Scenes, tambahkan scene baru dengan nama
TransactionDecision
. - Di bagian Slot fill, klik + untuk menambahkan slot baru.
- Di bagian Pilih jenis, pilih
actions.type.TransactionDecisionValue
sebagai jenis slot. - Di kolom nama slot, beri nama
TransactionDecision
pada slot. - Aktifkan kotak centang Customize slot value writeback (diaktifkan secara default).
- Pada Konfigurasi slot, pilih Gunakan parameter sesi dari dropdown.
- Pada bagian Konfigurasi slot,masukkan nama parameter sesi yang digunakan untuk menyimpan urutan ke dalam kolom teks (yaitu
$session.params.order
). - Klik Save.
Dalam upaya untuk 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 untuk mengubah
isi pesanan.
Pada tahap ini, pengguna juga dapat meminta perubahan pesanan. Dalam hal ini, Anda harus memastikan fulfillment 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. - Pada bagian Kondisi, klik + untuk menambahkan kondisi baru.
Di kolom teks, masukkan sintaksis kondisi berikut untuk memeriksa kondisi keberhasilan:
scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"
Arahkan kursor ke kondisi yang baru saja ditambahkan, lalu klik panah atas untuk menempatkannya sebelum
if scene.slots.status == "FINAL"
.Aktifkan Send prompt dan memberikan perintah sederhana yang memberi tahu pengguna bahwa pesanannya sudah selesai:
candidates: - first_simple: variants: - speech: >- Transaction completed! Your order $session.params.TransactionDecision.order.merchantOrderId is all set!
Di bagian Transition, pilih End conversation untuk mengakhiri percakapan.
Pada bagian Kondisi, klik + untuk menambahkan kondisi baru.
Di 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 ditambahkan, lalu klik panah atas untuk menempatkannya sebelum
if scene.slots.status == "FINAL"
.Aktifkan Send prompt dan memberikan perintah sederhana yang memberi tahu pengguna bahwa pesanan telah ditolak:
candidates: - first_simple: variants: - speech: Look like you don't want to order anything. Goodbye.
Di bagian Transition, pilih End conversation untuk mengakhiri percakapan.
Pilih kondisi
else if scene.slots.status == "FINAL"
.Aktifkan Kirim perintah dan berikan perintah sederhana yang memberi tahu pengguna bahwa mereka tidak dapat melakukan transaksi:
candidates: - first_simple: variants: - speech: >- Transaction failed with status $session.params.TransactionDecision.transactionDecision
Di bagian Transition, pilih End conversation untuk mengakhiri percakapan jika pengguna tidak dapat melakukan transaksi.
Selesaikan pesanan dan kirim tanda terima
Saat slot TransactionDecisionValue
menampilkan hasil ORDER_ACCEPTED
, Anda harus segera melakukan pemrosesan apa pun yang diperlukan untuk "mengonfirmasi" pesanan (seperti mempertahankannya dalam database Anda sendiri dan menagih pengguna).
Anda dapat mengakhiri percakapan dengan respons ini, tetapi Anda harus menyertakan respons
sederhana agar percakapan tetap berjalan. Saat Anda memberikan orderUpdate
awal ini, pengguna akan melihat "kartu tanda terima diciutkan" beserta sisa respons Anda. Kartu ini akan mencerminkan tanda terima yang ditemukan pengguna di
Histori Pesanan mereka.
Selama konfirmasi pesanan, objek pesanan Anda dapat menyertakan userVisibleOrderId
,
yaitu ID yang dilihat pengguna untuk pesanan tersebut. Anda dapat menggunakan kembali
merchantOrderId
untuk kolom ini.
Bagian dari objek OrderUpdate
harus berisi objek tindakan tindak lanjut,
yang muncul sebagai tombol URL di bagian bawah detail pesanan yang dapat ditemukan
pengguna di Histori Pesanan Asisten mereka.
- Setidaknya Anda harus memberikan
Tindakan tindak lanjut
VIEW_DETAILS
dengan setiap pesanan. Daftar ini harus berisi deep link ke representasi pesanan di aplikasi seluler atau situs Anda. - Anda juga harus mengirimkan tanda terima resmi melalui email yang memenuhi semua persyaratan hukum untuk melakukan transaksi, selain kartu tanda terima dalam percakapan Action Anda.
Untuk mengirim pembaruan pesanan awal:
- Dari tab Scenes, pilih scene
TransactionDecision
Anda. Di bagian Condition, pilih kondisi yang memeriksa hasil keberhasilan,
ORDER_ACCEPTED
:scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"
Untuk kondisi ini, aktifkan Call your webhook, dan berikan nama pengendali intent, seperti
update_order
.Dalam kode webhook Anda, tambahkan pengendali intent untuk mengirim pembaruan pesanan awal:
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 aktifnya. Kirim pembaruan pesanan pengguna dengan mengirimkan permintaan PATCH HTTP ke Orders API beserta status dan detail pesanan.
Menyiapkan permintaan asinkron ke Orders API
Permintaan pembaruan pesanan ke Orders API diotorisasi oleh token akses. Untuk mem-PATCH pembaruan pesanan ke Orders API, download kunci akun layanan
JSON yang terkait dengan project Konsol Actions Anda, lalu tukar
kunci akun layanan dengan token pemilik yang dapat diteruskan ke
header Authorization
permintaan HTTP.
Untuk mengambil kunci akun layanan, lakukan langkah-langkah berikut:
- Di Konsol Google Cloud, buka Menu Changes > API & Layanan > Kredensial > Buat kredensial > Kunci akun layanan.
- Pada Akun Layanan, pilih Akun Layanan Baru.
- Tetapkan akun layanan ke
service-account
. - Tetapkan Role ke Project > Owner.
- 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 cakupan "https://www.googleapis.com/auth/actions.order.developer". Anda dapat menemukan langkah dan contoh penginstalan di halaman GitHub library klien API.
Anda juga dapat merujuk order-update.js
dalam contoh Node.js kami untuk contoh pertukaran kunci.
Kirim pembaruan pesanan
Setelah menukar kunci akun layanan dengan token pemilik OAuth, Anda dapat mengirim pembaruan pesanan sebagai permintaan PATCH yang diotorisasi ke Orders API.
URL Orders API:
PATCH https://actions.googleapis.com/v3/orders/${orderId}
Masukkan header berikut dalam permintaan Anda:
"Authorization: Bearer token"
dengan token pemilik OAuth yang Anda tukarkan kunci akun layanannya."Content-Type: application/json"
.
Permintaan PATCH harus mengambil isi JSON dari format berikut:
{ "orderUpdate": OrderUpdate }
Objek OrderUpdate
terdiri dari kolom level teratas berikut:
updateMask
- Kolom pesanan yang Anda perbarui. Untuk memperbarui status pesanan, tetapkan nilai kepurchase.status, purchase.userVisibleStatusLabel
.order
- Konten update. Jika Anda memperbarui konten pesanan, tetapkan nilai ke objekOrder
yang diperbarui. Jika Anda memperbarui status pesanan (misalnya, dari"CONFIRMED"
menjadi"SHIPPED"
), objek akan berisi kolom berikut:merchantOrderId
- ID yang sama dengan yang Anda tetapkan dalam 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 sedang dalam perjalanan".
userNotification
yang dapat ditampilkan di perangkat pengguna saat update ini dikirim. Perhatikan bahwa menyertakan objek ini tidak menjamin 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 deskriptif tentang status pesanan saat ini. Di kolom order.purchase.status
update Anda, gunakan salah satu nilai berikut:
CREATED
- Pesanan diterima oleh pengguna dan "dibuat" dari perspektif Action, tetapi memerlukan pemrosesan manual di back-end Anda.CONFIRMED
- Pesanan aktif dan sedang diproses untuk pemenuhan.IN_PREPARATION
- Pesanan sedang disiapkan untuk pengiriman, seperti makanan yang sedang dimasak atau item yang sedang dikemas.READY_FOR_PICKUP
- Pesanan dapat 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 sedang diproses.RETURNED
- Pesanan telah dikembalikan oleh pengguna setelah diterima.REJECTED
- Jika Anda tidak dapat memproses, mengisi daya, atau "mengaktifkan" pesanan.CANCELLED
- Pesanan dibatalkan oleh pengguna.
Anda harus mengirim pembaruan pesanan untuk setiap status yang relevan dengan
transaksi Anda. Misalnya, jika transaksi Anda memerlukan pemrosesan manual untuk mencatat pesanan ke dalam log setelah pemesanan dilakukan, kirim pembaruan pesanan CREATED
hingga pemrosesan tambahan 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 tanpa mengenakan biaya 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
dalam
contoh Anda. Tindakan ini setara dengan mengaktifkan setelan mode sandbox di
konsol Actions. Untuk melihat cuplikan kode yang menggunakan isInSandbox
, lihat bagian
Mengirim pembaruan pesanan.
Pemecahan masalah
Jika mengalami masalah selama pengujian, sebaiknya baca langkah pemecahan masalah untuk transaksi.