Membuat reservasi

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:

  1. Validasi persyaratan transaksi (opsional) - Gunakan helper persyaratan transaksi di awal percakapan untuk memastikan pengguna dapat melakukan transaksi.
  2. Membuat pesanan - Pandu pengguna untuk melakukan "perakitan keranjang" tempat mereka membuat detail reservasi.
  3. 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.
  4. Menyelesaikan pesanan dan mengirim tanda terima - Setelah pesanan dikonfirmasi, update sistem reservasi Anda dan kirim tanda terima kepada pengguna.
  5. 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:

  1. Buat project baru atau impor project yang ada.
  2. Buka Deploy > Directory information.
  3. 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

  1. Dari tab Scenes, tambahkan scene baru dengan nama TransactionRequirementsCheck.
  2. Di bagian Slot fill, klik + untuk menambahkan slot baru.
  3. Di bagian Select type, pilih actions.type.TransactionRequirementsCheckResult sebagai jenis slot.
  4. Di kolom nama slot, beri nama TransactionRequirementsCheck pada slot.
  5. Aktifkan kotak centang Customize slot value writeback (diaktifkan secara default).
  6. 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

  1. Dari tab Scenes, pilih scene TransactionRequirementsCheck yang baru dibuat.
  2. Pada bagian Kondisi, klik + untuk menambahkan kondisi baru.
  3. Di 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 ditambahkan, lalu klik panah atas untuk menempatkannya sebelum if scene.slots.status == "FINAL".

  5. 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!.
    
  6. Di bagian Transition, pilih scene lain, yang memungkinkan pengguna melanjutkan percakapan dan melakukan transaksi.

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

  8. 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.
    
  9. 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 sebagai lineItems.

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

  1. Dari tab Scenes, tambahkan scene baru dengan nama TransactionDecision.
  2. Di bagian Slot fill, klik + untuk menambahkan slot baru.
  3. Di bagian Select type, pilih actions.type.TransactionDecisionValue sebagai jenis slot.
  4. Di kolom nama slot, beri nama TransactionDecision pada slot.
  5. Aktifkan kotak centang Customize slot value writeback (diaktifkan secara default).
  6. Pada Konfigurasi slot, pilih Gunakan parameter sesi dari dropdown.
  7. Di bagian Konfigurasi slot,masukkan nama parameter sesi yang digunakan untuk menyimpan urutan ke kolom teks (yaitu $session.params.order).
  8. 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:

  1. Dari tab Scenes, pilih scene TransactionDecision yang baru dibuat.
  2. Pada bagian Kondisi, klik + untuk menambahkan kondisi baru.
  3. Di 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 ditambahkan, lalu klik panah atas untuk menempatkannya sebelum if scene.slots.status == "FINAL".

  5. 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!
    
  6. Di bagian Transition, pilih End conversation untuk mengakhiri percakapan.

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

  8. Di 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 ditambahkan, lalu klik panah atas untuk menempatkannya sebelum if scene.slots.status == "FINAL".

  10. 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.
    
  11. Di bagian Transition, pilih End conversation untuk mengakhiri percakapan.

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

  13. 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
    
  14. 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:

  1. Dari tab Scenes, pilih scene TransactionDecision Anda.
  2. Di bagian Condition, pilih kondisi yang memeriksa hasil keberhasilan, ORDER_ACCEPTED:

    scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"
    
  3. Untuk kondisi ini, aktifkan Call your webhook,dan berikan nama pengendali intent, seperti update_order.

  4. 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:

  1. Di Konsol Google Cloud, buka Menu Changes > API & Layanan > Kredensial > Buat kredensial > Kunci akun layanan.
  2. Pada Akun Layanan, pilih Akun Layanan Baru.
  3. Tetapkan akun layanan ke service-account.
  4. Tetapkan Role ke Project > Owner.
  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 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 ke reservation.status, reservation.userVisibleStatusLabel.
  • order - Konten update. Jika Anda memperbarui konten reservasi, tetapkan nilai ke objek Order 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 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 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:

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