Membuat reservasi

Panduan ini menuntun Anda dalam proses pengembangan project Action yang menggunakan Orders API untuk melakukan reservasi.

Alur transaksi

Ketika project Action Anda menangani reservasi, menggunakan alur berikut:

  1. Memvalidasi persyaratan transaksi (opsional) - Menggunakan transaksi persyaratan helper di awal percakapan untuk memastikan pengguna dapat melakukan transaksi.
  2. Buat pesanan - Pandu pengguna untuk "perakitan keranjang" di mana mereka membuat detail pemesanan mereka.
  3. Usulkan pesanan - Setelah "keranjang" selesai, usulkan "pesanan" reservasi dapat pengguna, sehingga mereka dapat mengkonfirmasi bahwa itu benar. Jika reservasi dikonfirmasi, Anda menerima respons dengan detail reservasi.
  4. Menyelesaikan pesanan dan mengirimkan tanda terima - Setelah pesanan dikonfirmasi, perbarui sistem reservasi Anda dan mengirimkan tanda terima kepada pengguna.
  5. Kirim pembaruan pesanan - Selama masa aktif reservasi, memberikan 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 Tindakan 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 Anda untuk ditinjau.

Anda hanya dapat men-deploy Actions yang menggunakan Orders API di negara berikut:

Australia
Brasil
Kanada
Indonesia 		Jepang
Meksiko
Qatar
Rusia 		Singapura
Swiss
Thailand
Turkiye
Inggris Raya
Amerika Serikat

Mem-build project Anda

Untuk melihat contoh lengkap percakapan transaksional, lihat halaman Transaksi contoh di Node.js.

Penyiapan

Ketika membuat Action, Anda harus menentukan bahwa Anda ingin melakukan transaksi di Konsol Actions.

Untuk menyiapkan project dan fulfillment Anda, lakukan hal berikut:

  1. Buat project baru atau impor project yang sudah ada.
  2. Buka Deploy > Informasi direktori.

  3. Di bagian Informasi tambahan > Transaksi > centang kotak yang bertuliskan "Lakukan Tindakan Anda menggunakan Transactions API untuk melakukan transaksi barang fisik?".

Memvalidasi persyaratan transaksi (opsional)

Segera setelah pengguna menunjukkan bahwa mereka ingin melakukan reservasi, Anda harus memeriksa bahwa mereka dapat melakukan reservasi. Misalnya, jika dipanggil, Action Anda mungkin tanyakan, "Apakah Anda ingin memesan tempat duduk?" Jika pengguna mengatakan "ya", Anda harus memastikan bahwa mereka dapat melanjutkan dan memberi mereka kesempatan untuk memperbaiki setelan apa pun mencegah mereka melanjutkan transaksi. Untuk melakukannya, Anda harus transisi ke adegan yang melakukan pemeriksaan persyaratan transaksi.

Membuat scene Pemeriksaan Persyaratan Transaksi

  1. Dari tab Scenes, tambahkan scene baru dengan nama TransactionRequirementsCheck.
  2. Di bagian Pengisian slot, klik + untuk menambahkan slot baru.
  3. Di bagian Select type, pilih actions.type.TransactionRequirementsCheckResult sebagai jenis slot.
  4. Di kolom nama slot, berikan nama TransactionRequirementsCheck untuk slot.
  5. Aktifkan kotak centang Customize slot value writeback (diaktifkan secara default).

  6. Klik Simpan.

Pemeriksaan persyaratan transaksi memberikan salah satu hasil berikut:

  • Jika persyaratan terpenuhi, parameter sesi ditetapkan dengan keberhasilan dan Anda dapat melanjutkan dengan membuat pesanan pengguna.
  • Jika satu atau lebih persyaratan tidak dapat dipenuhi, parameter sesi akan yang ditetapkan dengan kondisi kegagalan. Dalam hal ini, Anda harus mengubah arah pembicaraan meninggalkan 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 ke ponsel pengguna.

Menangani hasil Pemeriksaan Persyaratan Transaksi

  1. Dari tab Scenes, pilih yang baru Anda buat. TransactionRequirementsCheck adegan.
  2. Di bagian Kondisi, klik + untuk menambahkan kondisi baru.

  3. Pada kolom teks, masukkan sintaksis kondisi berikut untuk memeriksa kondisi keberhasilan:

    scene.slots.status == "FINAL" && session.params.TransactionRequirementsCheck.resultType == "CAN_TRANSACT"

  4. Arahkan kursor ke kondisi yang baru saja Anda tambahkan dan klik panah atas untuk menempatkannya sebelum if scene.slots.status == "FINAL".

  5. Aktifkan Kirim perintah dan berikan perintah sederhana yang memberi tahu pengguna mereka siap untuk melakukan transaksi:

    candidates:
  - first_simple:
      variants:
        - speech: >-
            Looks like you're good to go!.

  6. Di bagian Transisi, pilih suasana lain, sehingga pengguna dapat melanjutkan percakapan dan melanjutkan dengan melakukan transaksi.

  7. Pilih kondisi else if scene.slots.status == "FINAL".

  8. 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.

  9. Di bagian Transisi, pilih Akhiri percakapan untuk mengakhiri percakapan jika pengguna tidak dapat melakukan transaksi.

Membuat pesanan

Setelah memiliki informasi pengguna yang Anda butuhkan, buat "keranjang perakitan" pengalaman yang memandu pengguna untuk membuat reservasi mereka. Setiap Action akan memiliki alur perakitan keranjang yang sedikit berbeda yang sesuai dengan layanan.

Dalam pengalaman perakitan keranjang dasar, pengguna memilih opsi dari daftar untuk ditambahkan ke reservasi mereka, meskipun Anda dapat merancang percakapan untuk menyederhanakan {i>user experience<i}. Misalnya, bangun pengalaman perakitan keranjang yang memungkinkan untuk menjadwalkan reservasi bulanan dengan pertanyaan ya atau tidak. Anda juga dapat menampilkan carousel atau kartu daftar "direkomendasikan" kepada pengguna beberapa pemesanan.

Sebaiknya gunakan respons kaya untuk menyajikan pilihan pengguna secara visual, tetapi juga mendesain percakapan sehingga pengguna dapat membuat keranjang hanya dengan menggunakan suara. Untuk beberapa praktik terbaik dan contoh pengalaman perakitan keranjang, lihat Pedoman desain.

Membuat pesanan

Sepanjang percakapan Anda, kumpulkan detail reservasi pengguna, 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 tercantum sebagai lineItems.

Lihat Order dokumentasi respons untuk menyusun keranjang. Perhatikan bahwa Anda mungkin perlu menyertakan {i>field<i} yang berbeda tergantung pada pemesanan.

Kode contoh di bawah menunjukkan pesanan reservasi 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: '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'
 };

Membuat opsi urutan dan presentasi

const orderOptions = {
      'requestDeliveryAddress': false,
    };

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

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
};

Ajukan pesanan

Setelah Anda membuat pesanan reservasi, Anda harus menunjukkannya kepada pengguna konfirmasi atau tolak. Untuk melakukannya, Anda harus bertransisi ke adegan yang melakukan transaksi keputusan tersebut.

Membuat scene Keputusan Transaksi

  1. Dari tab Scenes, tambahkan scene baru dengan nama TransactionDecision.
  2. Di bagian Pengisian slot, klik + untuk menambahkan slot baru.
  3. Di bagian Pilih jenis, pilih actions.type.TransactionDecisionValue sebagai jenis slot.
  4. Di kolom nama slot, berikan nama TransactionDecision untuk slot.
  5. Aktifkan kotak centang Customize slot value writeback (diaktifkan secara default).
  6. Di bagian Konfigurasi slot, pilih Gunakan parameter sesi dari menu dropdown.
  7. Di bagian Konfigurasi slot, masukkan nama parameter sesi yang digunakan untuk simpan pesanan ke dalam kolom teks (misalnya, $session.params.order).

  8. Klik Simpan.

Dalam upaya 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.

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,
  • CART_CHANGE_REQUESTED
  • USER_CANNOT_TRANSACT.

Untuk menangani hasil keputusan transaksi:

  1. Dari tab Scenes, pilih scene TransactionDecision yang baru dibuat.
  2. Di bagian Kondisi, klik + untuk menambahkan kondisi baru.

  3. Pada kolom teks, masukkan sintaksis kondisi berikut untuk memeriksa kondisi keberhasilan:

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

  4. Arahkan kursor ke kondisi yang baru saja Anda tambahkan dan klik panah atas untuk menempatkannya sebelum if scene.slots.status == "FINAL".

  5. Aktifkan Kirim perintah dan berikan perintah sederhana yang memberi tahu pengguna reservasi mereka selesai:

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

  6. Di bagian Transisi, pilih Akhiri percakapan untuk mengakhiri percakapan.

  7. Di bagian Kondisi, klik + untuk menambahkan kondisi baru.

  8. Pada kolom teks, masukkan sintaksis kondisi berikut untuk memeriksa kondisi kegagalan:

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

  9. Arahkan kursor ke kondisi yang baru saja Anda tambahkan dan klik panah atas untuk menempatkannya sebelum if scene.slots.status == "FINAL".

  10. Aktifkan Send prompt dan berikan perintah sederhana yang memberi tahu pengguna pesanan telah ditolak:

    candidates:
  - first_simple:
      variants:
        - speech: Looks like you don't want to set up a reservation. Goodbye.

  11. Di bagian Transisi, pilih Akhiri percakapan untuk mengakhiri percakapan.

  12. Pilih kondisi else if scene.slots.status == "FINAL".

  13. Aktifkan Kirim perintah dan berikan perintah sederhana yang memberi tahu pengguna mereka tidak dapat melakukan transaksi:

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

  14. Di bagian Transisi, pilih Akhiri percakapan untuk mengakhiri percakapan jika pengguna tidak dapat melakukan transaksi.

Menyelesaikan reservasi dan mengirimkan tanda terima

Saat slot TransactionDecisionValue menampilkan hasil ORDER_ACCEPTED, Anda harus segera melakukan pemrosesan apa pun yang diperlukan untuk menjadwalkan reservasi (seperti mempertahankannya di {i>database<i} Anda sendiri).

Kirimkan tanggapan sederhana agar percakapan terus mengalir. Pengguna menerima "kartu tanda terima diciutkan" beserta jawaban Anda.

Untuk mengirim pembaruan pesanan awal:

  1. Dari tab Scenes, pilih scene TransactionDecision.

  2. Di bagian Kondisi, pilih kondisi yang memeriksa hasil yang berhasil. ORDER_ACCEPTED:

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

  3. Untuk kondisi ini, aktifkan Call your webhook, dan berikan intent nama pengendali, seperti update_order.

  4. Di 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': [
        '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 berubah selama masa aktifnya. Mengirim pengguna pembaruan pesanan reservasi 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 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:

  1. Di Konsol Google Cloud, buka Menu Unduh > API & Layanan > Kredensial > Buat kredensial > Kunci akun layanan.
  2. Di bagian Akun Layanan, pilih Akun Layanan Baru.
  3. Setel akun layanan ke service-account.
  4. Tetapkan Role ke Project > Pemilik.
  5. Tetapkan jenis kunci ke JSON.
  6. Pilih Create.
  7. Kunci akun layanan JSON pribadi akan didownload ke komputer lokal Anda.

Dalam kode pembaruan pesanan, tukar kunci layanan dengan token pemilik menggunakan library klien Google API dan &quot;https://www.googleapis.com/auth/actions.order.developer&quot;. Anda dapat menemukan langkah-langkah dan contoh penginstalan di library klien API Halaman GitHub.

Referensikan order-update.js dalam contoh Node.js kami untuk contoh pertukaran kunci.

Kirim pembaruan pesanan

Setelah Anda menukar kunci akun layanan dengan token pemilik OAuth, kirim pembaruan pesanan sebagai permintaan PATCH yang diotorisasi 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 reservasi, tetapkan nilai ke reservation.status, reservation.userVisibleStatusLabel.

  • order - Konten update. Jika Anda memperbarui isi reservasi, tetapkan nilai ke objek Order yang diperbarui. Jika Anda baru saja memperbarui status reservasi (misalnya, dari "PENDING" hingga "FULFILLED"), objek berisi kolom berikut:

    • merchantOrderId - ID yang sama dengan yang Anda tetapkan di objek Order.
    • lastUpdateTime - Stempel waktu update ini.
    • purchase - Objek yang berisi hal berikut:
      • status - Status pesanan sebagai ReservationStatus, seperti "CONFIRMED" atau "CANCELLED".
      • userVisibleStatusLabel - Label yang ditampilkan kepada pengguna yang memberikan detail tentang status pesanan, seperti "Reservasi Anda telah dikonfirmasi".

  • userNotification (opsional) - A userNotification 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 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 mendeskripsikan status pesanan saat ini. Dalam order.ReservationStatus update Anda gunakan salah satu nilai berikut:

  • PENDING - Reservasi telah "dibuat" oleh Action Anda, tetapi memerlukan pemrosesan tambahan di backend Anda.
  • CONFIRMED - Pemesanan dikonfirmasi di back-end penjadwalan Anda.
  • CANCELLED - Pengguna membatalkan reservasi.
  • FULFILLED - Pemesanan pengguna telah dipenuhi oleh layanan.
  • CHANGE_REQUESTED - Pengguna meminta perubahan pada reservasi, dan perubahan tersebut sedang diproses.
  • REJECTED - Jika Anda tidak dapat memproses atau cara lainnya mengonfirmasi reservasi.

Kirim pembaruan pesanan untuk setiap status yang relevan dengan pemesanan tambahan. Misalnya, jika reservasi Anda memerlukan pemrosesan manual untuk konfirmasi reservasi setelah diminta, kirimkan pembaruan pesanan sebesar PENDING hingga bahwa pemrosesan tambahan itu 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 Anda tanpa menagih metode pembayaran. Untuk mengaktifkan mode sandbox, ikuti langkah-langkah berikut:

  1. Di Konsol Actions, klik Test di navigasi.
  2. Klik Setelan.
  3. 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 Anda mengalami masalah selama pengujian, baca langkah pemecahan masalah kami untuk transaksi.