Panduan ini menuntun Anda melalui proses pengembangan project Action yang menggunakan Orders API untuk melakukan reservasi.
Alur transaksi
Saat project Action Anda menangani reservasi, project tersebut menggunakan alur berikut:
- Validasi persyaratan transaksi (opsional) - Gunakan helper persyaratan transaksi di awal percakapan untuk memastikan pengguna dapat melakukan transaksi.
- Membuat pesanan - Pandu pengguna untuk melakukan "perakitan keranjang" tempat mereka membuat detail reservasi.
- Mengusulkan pesanan - Setelah "keranjang" selesai, ajukan "pesanan" reservasi kepada pengguna, agar mereka dapat mengonfirmasi bahwa pesanan sudah benar. Jika reservasi dikonfirmasi, Anda akan menerima respons dengan detail pemesanan.
- Menyelesaikan pesanan dan mengirim tanda terima - Setelah pesanan dikonfirmasi, update sistem reservasi Anda dan kirim tanda terima kepada pengguna.
- Mengirim pembaruan pesanan - Selama masa aktif reservasi, berikan pembaruan status reservasi pengguna dengan mengirimkan permintaan PATCH ke Orders API.
Pembatasan dan panduan peninjauan
Perlu diingat bahwa kebijakan tambahan berlaku untuk Action yang menggunakan transaksi dan Orders API. Kami membutuhkan 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 menggunakan Orders API 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 lengkap percakapan transaksional, lihat Contoh transaksi di Node.js.
Penyiapan
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?".
Memvalidasi persyaratan transaksi (opsional)
Segera setelah pengguna menunjukkan bahwa mereka ingin menyiapkan reservasi, Anda harus memeriksa apakah mereka dapat mengajukan reservasi. Misalnya, saat dipanggil, Action Anda mungkin menanyakan, "Apakah Anda ingin memesan tempat?" Jika pengguna menyatakan "ya", Anda harus memastikan bahwa mereka dapat melanjutkan dan memberi mereka kesempatan untuk memperbaiki setelan apa pun sehingga mencegah mereka melanjutkan transaksi. Untuk melakukannya, Anda harus beralih ke scene yang melakukan pemeriksaan persyaratan transaksi.
Membuat scene Pemeriksaan Persyaratan Transaksi
- Dari tab Scenes, 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 menghasilkan 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 akan 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 Send prompt dan memberikan perintah sederhana yang memberi tahu pengguna bahwa mereka siap melakukan transaksi:
candidates: - first_simple: variants: - speech: >- Looks like you're good to go!.
Di bagian Transition, pilih scene lain, yang memungkinkan pengguna melanjutkan percakapan dan melakukan transaksi.
Pilih kondisi
else if scene.slots.status == "FINAL"
.Aktifkan Send prompt dan memberikan 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.
Membuat pesanan
Setelah Anda memiliki informasi pengguna yang dibutuhkan, buat pengalaman "keranjang keranjang" yang memandu pengguna untuk melakukan reservasi. Setiap Action akan memiliki alur perakitan keranjang yang sedikit berbeda yang sesuai untuk layanannya.
Dalam pengalaman penggabungan keranjang dasar, pengguna memilih opsi dari daftar untuk ditambahkan ke reservasi mereka, meskipun Anda dapat mendesain percakapan untuk menyederhanakan pengalaman pengguna. Misalnya, buat pengalaman perakitan keranjang yang memungkinkan pengguna menjadwalkan reservasi bulanan dengan pertanyaan ya atau tidak yang sederhana. Anda juga dapat menampilkan carousel atau kartu daftar reservasi "direkomendasikan" kepada pengguna.
Sebaiknya gunakan respons yang kaya untuk mempresentasikan opsi pengguna secara visual, tetapi juga desain percakapan agar pengguna dapat membuat keranjangnya hanya dengan suara. Untuk beberapa praktik terbaik dan contoh pengalaman perakitan keranjang, lihat Pedoman desain.
Membuat pesanan
Dalam percakapan, kumpulkan detail reservasi pengguna, lalu
buat 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
.
Lihat dokumentasi respons Order
untuk membuat keranjang. Perhatikan bahwa Anda mungkin perlu menyertakan kolom yang berbeda bergantung pada reservasi.
Kode contoh di bawah menunjukkan pesanan reservasi 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: 'Dinner reservation',
description: 'A world of flavors all in one destination.',
reservation: {
status: 'PENDING',
userVisibleStatusLabel: 'Reservation is pending.',
type: 'RESTAURANT',
reservationTime: {
timeIso8601: '2020-01-16T01:30:15.01Z',
},
userAcceptableTimeRange: {
timeIso8601: '2020-01-15/2020-01-17',
},
partySize: 6,
staffFacilitators: [
{
name: 'John Smith',
},
],
location: {
zipCode: '94086',
city: 'Sunnyvale',
postalAddress: {
regionCode: 'US',
postalCode: '94086',
administrativeArea: 'CA',
locality: 'Sunnyvale',
addressLines: [
'222, Some other Street',
],
},
},
},
},
],
},
buyerInfo: {
email: 'janedoe@gmail.com',
firstName: 'Jane',
lastName: 'Doe',
displayName: 'Jane Doe',
},
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'
};
Buat opsi urutan dan presentasi
const orderOptions = {
'requestDeliveryAddress': false,
};
const presentationOptions = {
'actionDisplayName': 'RESERVE'
};
Simpan data pesanan di parameter sesi
Dari fulfillment Anda, simpan data pesanan ke parameter sesi. 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
};
Mengusulkan pesanan
Setelah membuat pesanan reservasi, 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 Select type, 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.
- Di bagian Konfigurasi slot,masukkan nama parameter sesi yang digunakan untuk menyimpan urutan ke kolom teks (yaitu
$session.params.order
). Klik Simpan.
Dalam upaya untuk mengisi slot TransactionDecisionValue
, Asisten memulai
pengalaman bawaan tempat Order
yang Anda teruskan dirender langsung ke "kartu pratinjau keranjang". Pengguna dapat mengucapkan "jadwalkan reservasi", menolak transaksi, atau meminta untuk mengubah detail reservasi.
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
,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 Kirim perintah dan berikan perintah sederhana yang memberi tahu pengguna bahwa reservasi mereka telah selesai:
candidates: - first_simple: variants: - speech: >- Transaction completed! Your reservation $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: Looks like you don't want to set up a reservation. 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 reservasi dan kirim tanda terima
Saat slot TransactionDecisionValue
menampilkan hasil ORDER_ACCEPTED
,
Anda harus segera melakukan pemrosesan apa pun yang diperlukan untuk menjadwalkan
reservasi (seperti mempertahankannya dalam database Anda sendiri).
Kirimkan respons sederhana untuk menjaga percakapan tetap mengalir. Pengguna akan menerima "kartu tanda terima yang diciutkan" beserta respons 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
.Di kode webhook, 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': [ 'reservation.status', 'reservation.user_visible_status_label', 'reservation.confirmation_code' ] }, 'order': { 'merchantOrderId': order.merchantOrderId, 'lastUpdateTime': currentTime, 'reservation': { 'status': 'CONFIRMED', 'userVisibleStatusLabel': 'Reservation confirmed', 'confirmationCode': '123ABCDEFGXYZ', }, }, 'reason': 'Reason string' })); });
Kirim pembaruan pesanan
Status reservasi akan berubah selama masa aktifnya. Kirim pembaruan pesanan reservasi pengguna dengan permintaan PATCH HTTP ke Orders API, yang berisi 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, tukar 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.
Referensikan order-update.js
dalam contoh Node.js kami untuk contoh pertukaran kunci.
Kirim pembaruan pesanan
Setelah menukar kunci akun layanan dengan token pemilik OAuth, kirim 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 reservasi, tetapkan nilai kereservation.status, reservation.userVisibleStatusLabel
.order
- Konten update. Jika Anda memperbarui konten reservasi, tetapkan nilai ke objekOrder
yang diperbarui. Jika Anda hanya memperbarui status reservasi (misalnya, dari"PENDING"
menjadi"FULFILLED"
), 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 sebagaiReservationStatus
, seperti "CONFIRMED
" atau "CANCELLED
".userVisibleStatusLabel
- Label yang ditampilkan kepada pengguna yang memberikan detail tentang status pesanan, seperti "Reservasi Anda telah dikonfirmasi".
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 reservasi menjadi FULFILLED
:
// 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 the ID of the order to update.
const orderId = '<UNIQUE_MERCHANT_ORDER_ID>';
// Declare order update
const orderUpdate = new OrderUpdate({
updateMask: {
paths: [
'contents.lineItems.reservation.status',
'contents.lineItems.reservation.userVisibleStatusLabel'
]
},
order: {
merchantOrderId: orderId, // Specify the ID of the order to update
lastUpdateTime: new Date().toISOString(),
contents: {
lineItems: [
{
reservation: {
status: 'FULFILLED',
userVisibleStatusLabel: 'Reservation fulfilled',
},
}
]
},
},
reason: 'Reservation status was updated to fulfilled.',
});
// 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 reservasi
ReservationStatus
pembaruan pesanan
harus deskriptif tentang status pesanan saat ini. Di kolom order.ReservationStatus
update Anda, gunakan salah satu nilai berikut:
PENDING
- Reservasi telah "dibuat" oleh Action Anda, tetapi memerlukan pemrosesan tambahan pada backend Anda.CONFIRMED
- Reservasi telah dikonfirmasi di back-end penjadwalan Anda.CANCELLED
- Pengguna membatalkan reservasinya.FULFILLED
- Reservasi pengguna dipenuhi oleh layanan.CHANGE_REQUESTED
- Pengguna meminta perubahan pada reservasi, dan perubahan sedang diproses.REJECTED
- Jika Anda tidak dapat memproses atau mengonfirmasi reservasi.
Mengirim pembaruan pesanan untuk setiap status yang relevan dengan reservasi Anda. Misalnya, jika reservasi Anda memerlukan pemrosesan manual untuk mengonfirmasi reservasi setelah diminta, kirim pembaruan pesanan PENDING
hingga pemrosesan tambahan selesai. Tidak semua reservasi 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 Anda mengalami masalah selama pengujian, baca langkah pemecahan masalah untuk transaksi.