Tindakan Percakapan tidak akan digunakan lagi pada 13 Juni 2023. Untuk mengetahui informasi selengkapnya, lihat Penghentian Action Percakapan.

Membuat transaksi fisik dengan pembayaran yang dikelola penjual

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Panduan ini akan memandu Anda dalam proses pengembangan project Actions yang menggabungkan transaksi barang fisik menggunakan metode pembayaran yang dikelola oleh situs Anda.

Alur transaksi

Saat project Actions Anda menangani transaksi fisik menggunakan pembayaran yang dikelola penjual, project ini menggunakan alur berikut:

  1. Tautkan akun pengguna - Agar pengguna dapat menggunakan metode pembayaran yang disimpan di layanan Anda, gunakan Penautan Akun untuk mengaitkan Akun Google-nya dengan akunnya di layanan Anda.
  2. Kumpulkan informasi (opsional) - Bergantung pada sifat transaksi Anda, Anda dapat mengumpulkan informasi berikut dari pengguna di awal percakapan:
    1. Memvalidasi persyaratan transaksi - Pada awal bagian transaksi, validasikan bahwa pengguna memenuhi persyaratan untuk melakukan transaksi, seperti mengonfigurasikan informasi pembayaran dengan benar dan tersedia sebelum membuat keranjang.
    2. Meminta alamat pengiriman - Jika transaksi memerlukan alamat pengiriman, kumpulkan alamat tersebut dari pengguna.
  3. Membuat pesanan - Arahkan pengguna melalui "rakitan keranjang" tempat mereka memilih item yang ingin dibeli.
  4. Mengusulkan pesanan - Setelah keranjang selesai, ajukan pesanan kepada pengguna sehingga mereka dapat mengonfirmasi bahwa pesanan sudah benar. Jika pesanan sudah dikonfirmasi, Anda akan menerima respons yang berisi detail pesanan dan token pembayaran.
  5. Menyelesaikan pesanan dan mengirim tanda terima - Setelah pesanan dikonfirmasi, perbarui pelacakan inventaris atau layanan pemenuhan lainnya, lalu kirim tanda terima kepada pengguna.
  6. Kirim update pesanan - Selama masa aktif pemenuhan pesanan, berikan update pesanan pengguna dengan mengirimkan permintaan PATCH ke Orders API.

Panduan pembatasan dan peninjauan

Perlu diingat bahwa kebijakan tambahan berlaku untuk Tindakan dengan transaksi. Kami perlu waktu hingga enam minggu untuk meninjau Action dengan transaksi, jadi pertimbangkan waktu saat merencanakan jadwal rilis. Untuk memudahkan proses peninjauan, pastikan Anda mematuhi kebijakan dan pedoman untuk transaksi sebelum mengirimkan Action untuk ditinjau.

Anda hanya dapat men-deploy Action yang menjual barang fisik di negara-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, lakukan hal berikut:

  1. Buat project baru atau impor project yang sudah ada.
  2. Buka Deploy > Directory information.

  3. Di bagian Informasi tambahan > Transaksi > centang kotak yang menyatakan "Apakah Action Anda menggunakan Transactions API untuk melakukan transaksi barang fisik?".

Saat menggunakan metode pembayaran Anda untuk menagih pengguna, sebaiknya tautkan akun Google-nya dengan akun yang ia miliki ke layanan Anda untuk mengambil, menampilkan, dan menagih metode pembayaran yang disimpan di sana.

Mendesain antarmuka pengguna suara untuk alur autentikasi

Memeriksa apakah pengguna telah diverifikasi dan memulai alur penautan akun

  1. Buka project Actions Builder Anda di Actions Console.
  2. Buat scene baru untuk memulai penautan akun di Action Anda:
    1. Klik Scenes.
    2. Klik ikon add (+) untuk menambahkan tampilan baru.
  3. Pada scene yang baru dibuat, klik ikon tambahkan untuk Conditions.
  4. Tambahkan kondisi yang memeriksa apakah pengguna yang terkait dengan percakapan tersebut adalah pengguna terverifikasi. Jika pemeriksaan gagal, Action Anda tidak dapat melakukan penautan akun selama percakapan, dan harus kembali untuk memberikan akses ke fungsi yang tidak memerlukan penautan akun.
    1. Di kolom Enter new expression di bagian Kondisi, masukkan logika berikut: user.verificationStatus != "VERIFIED"
    2. Di bagian Transisi, pilih scene yang tidak memerlukan penautan akun atau scene yang merupakan titik entri ke fungsi khusus tamu.

  1. Klik ikon tambahkan untuk Kondisi.
  2. Tambahkan kondisi untuk memicu alur penautan akun jika pengguna tidak memiliki identitas terkait.
    1. Di kolom Enter new expression di bagian Kondisi, masukkan logika berikut: user.verificationStatus == "VERIFIED"
    2. Di bagian Transisi, pilih tampilan sistem Penautan Akun.
    3. Klik Simpan.

Setelah menyimpan, scene sistem penautan akun baru bernama <SceneName>_AccountLinking akan ditambahkan ke project Anda.

Menyesuaikan tampilan penautan akun

  1. Di bagian Scene, pilih scene sistem penautan akun.
  2. Klik Kirim perintah dan tambahkan kalimat singkat untuk menjelaskan kepada pengguna alasan Action perlu mengakses identitasnya (misalnya "Untuk menyimpan preferensi Anda").
  3. Klik Simpan.

  1. Di bagian Kondisi, klik Jika pengguna berhasil menyelesaikan penautan akun.
  2. Konfigurasikan alur agar tetap berjalan jika pengguna setuju untuk menautkan akun. Misalnya, panggil webhook untuk memproses logika bisnis kustom yang diperlukan dan bertransisi kembali ke scene asal.
  3. Klik Simpan.

  1. Di bagian Kondisi, klik Jika pengguna membatalkan atau menolak penautan akun.
  2. Mengonfigurasi alur yang harus dilanjutkan jika pengguna tidak setuju untuk menautkan akunnya. Misalnya, kirim pesan konfirmasi dan alihkan ke scene yang memberikan fungsi yang tidak memerlukan penautan akun.
  3. Klik Simpan.

  1. Pada bagian Kondisi, klik Jika terjadi error sistem atau jaringan.
  2. Konfigurasi bagaimana alur harus dilanjutkan jika alur penautan akun tidak dapat diselesaikan karena error sistem atau jaringan. Misalnya, kirim pesan konfirmasi dan alihkan ke scene yang memberikan fungsi yang tidak memerlukan penautan akun.
  3. Klik Simpan.

Kumpulkan informasi (opsional)

Memvalidasi persyaratan transaksi (opsional)

Segera setelah pengguna mengindikasikan bahwa mereka ingin melakukan pembelian, Anda harus memeriksa untuk memastikan bahwa mereka dapat melakukan transaksi. Misalnya, saat dipanggil,Action Anda mungkin bertanya, "Apakah Anda ingin memesan sepatu, atau memeriksa saldo akun Anda?" Jika pengguna mengatakan "pesan sepatu", Anda harus memastikan bahwa mereka dapat melanjutkan dan memberi mereka kesempatan untuk memperbaiki setelan apa pun yang 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 Pengisian slot, 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 untuk slot.
  5. Aktifkan kotak centang Sesuaikan nilai penulisan ulang slot slot (diaktifkan secara default).

  6. Klik Simpan.

Pemeriksaan persyaratan transaksi akan menghasilkan salah satu hasil berikut:

  • Jika persyaratan terpenuhi, parameter sesi akan ditetapkan dengan kondisi berhasil dan Anda dapat melanjutkan pembuatan pesanan 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 pada perangkat mereka. Jika percakapan terjadi di platform suara saja, handoff akan dimulai ke ponsel pengguna.

Menangani hasil Pemeriksaan Persyaratan Transaksi

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

  3. Di kolom teks, masukkan sintaksis kondisi berikut untuk memeriksa kondisi sukses:

    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 berikan perintah sederhana yang memberi tahu pengguna bahwa mereka siap untuk melakukan transaksi:

    candidates:
  - first_simple:
      variants:
        - speech: >-
            You are ready to purchase physical goods.

  6. Di bagian Transition, pilih scene lain, yang memungkinkan pengguna melanjutkan percakapan dan melanjutkan transaksi.

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

  8. Aktifkan Send prompt, lalu berikan perintah sederhana yang memberi tahu pengguna bahwa 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.

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 region layanan Anda. Untuk melakukannya, Anda harus beralih ke scene yang meminta alamat pengiriman pengguna.

Membuat Adegan Alamat Pengiriman

  1. Dari tab Scenes, tambahkan scene baru dengan nama DeliveryAddress.
  2. Di bagian Pengisian slot, klik + untuk menambahkan slot baru.
  3. Di bagian Select type, pilih actions.type.DeliveryAddressValue sebagai jenis slot.
  4. Di kolom nama slot, beri nama TransactionDeliveryAddress untuk slot.
  5. Aktifkan kotak centang Sesuaikan nilai penulisan ulang slot slot (diaktifkan secara default).
  6. Klik Simpan.

Saat mengonfigurasi slot, Anda dapat memberikan reason yang memungkinkan Anda memulai permintaan Asisten untuk mendapatkan alamat dengan string.String alasan defaultnya adalah "mengetahui tempat untuk mengirim pesanan". Oleh karena itu, Asisten mungkin bertanya kepada pengguna: "Untuk mengetahui tujuan pengiriman pesanan, saya perlu mengetahui alamat pengiriman Anda".

  • Di platform dengan layar, pengguna akan memilih alamat mana yang ingin digunakan untuk transaksi. Jika belum pernah memberikan alamat, mereka dapat memasukkan alamat baru.
  • Pada platform khusus suara, Asisten akan meminta izin kepada pengguna untuk membagikan alamat default mereka untuk transaksi tersebut. Jika pengguna belum pernah memberikan alamat, percakapan akan diteruskan ke ponsel untuk dimasukkan.

Untuk menangani hasil Alamat Pengiriman, ikuti langkah-langkah berikut:

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

  3. Di kolom teks, masukkan sintaksis kondisi berikut untuk memeriksa kondisi sukses:

    scene.slots.status == "FINAL" && session.params.TransactionDeliveryAddress.userDecision == "ACCEPTED"

  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 berikan perintah sederhana untuk memberi tahu pengguna bahwa Anda telah menerima alamat mereka:

    candidates:
  - first_simple:
      variants:
        - speech: >-
            Great! Your order will be delivered to
            $session.params.TransactionDeliveryAddress.location.postalAddress.locality
            $session.params.TransactionDeliveryAddress.location.postalAddress.administrativeArea
            $session.params.TransactionDeliveryAddress.location.postalAddress.regionCode
            $session.params.TransactionDeliveryAddress.location.postalAddress.postalCode

  6. Di bagian Transition, pilih scene lain, yang memungkinkan pengguna melanjutkan percakapan.

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

  8. Aktifkan Send prompt, lalu 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.

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

Buat urutan

Setelah memiliki informasi pengguna yang diperlukan, Anda akan mem-build pengalaman "perakitan keranjang" yang memandu pengguna membuat pesanan. Setiap Action akan memiliki alur perakitan keranjang yang sedikit berbeda sesuai dengan produk atau layanannya.

Pengalaman perakitan keranjang yang paling dasar memiliki pengguna memilih item dari daftar untuk ditambahkan ke pesanan mereka, meskipun Anda dapat mendesain percakapan untuk menyederhanakan pengalaman pengguna. Anda dapat membangun pengalaman perakitan keranjang yang memungkinkan pengguna mengurutkan ulang pembelian terbaru mereka melalui pertanyaan ya atau tidak. Anda juga dapat menampilkan carousel atau kartu daftar item item "unggulan" atau "direkomendasikan" teratas.

Sebaiknya gunakan respons lengkap untuk menampilkan opsi pengguna secara visual, serta desain percakapan sedemikian rupa sehingga pengguna dapat membuat keranjang mereka hanya dengan suara mereka. Untuk beberapa praktik terbaik dan contoh pengalaman pemasangan keranjang berkualitas tinggi, lihat Panduan Desain Transaksi.

Membuat pesanan

Sepanjang percakapan, Anda harus mengumpulkan item yang ingin dibeli pengguna, lalu membuat objek Order.

Setidaknya, Order Anda harus berisi hal berikut:

  • buyerInfo - Informasi tentang pengguna yang melakukan pembelian.
  • transactionMerchant - Informasi tentang penjual yang memfasilitasi pesanan.
  • contents - Konten sebenarnya dari pesanan yang tercantum sebagai lineItems.
  • priceAttributes - Detail harga tentang pesanan, termasuk total biaya pesanan dengan diskon dan pajak.

Lihat dokumentasi respons Order untuk membuat keranjang Anda. Perhatikan bahwa Anda mungkin perlu menyertakan kolom yang berbeda bergantung pada urutannya.

Kode contoh di bawah menunjukkan pesanan lengkap, termasuk kolom opsional:

const order = {
  createTime: '2019-09-24T18:00:00.877Z',
  lastUpdateTime: '2019-09-24T18:00:00.877Z',
  merchantOrderId: orderId, // A unique ID String for the order
  userVisibleOrderId: orderId,
  transactionMerchant: {
    id: 'http://www.example.com',
    name: 'Example Merchant',
  },
  contents: {
    lineItems: [
      {
        id: 'LINE_ITEM_ID',
        name: 'Pizza',
        description: 'A four cheese pizza.',
        priceAttributes: [
          {
            type: 'REGULAR',
            name: 'Item Price',
            state: 'ACTUAL',
            amount: {
              currencyCode: 'USD',
              amountInMicros: 8990000,
            },
            taxIncluded: true,
          },
          {
            type: 'TOTAL',
            name: 'Total Price',
            state: 'ACTUAL',
            amount: {
              currencyCode: 'USD',
              amountInMicros: 9990000,
            },
            taxIncluded: true,
          },
        ],
        notes: [
          'Extra cheese.',
        ],
        purchase: {
          quantity: 1,
          unitMeasure: {
            measure: 1,
            unit: 'POUND',
          },
          itemOptions: [
            {
              id: 'ITEM_OPTION_ID',
              name: 'Pepperoni',
              prices: [
                {
                  type: 'REGULAR',
                  state: 'ACTUAL',
                  name: 'Item Price',
                  amount: {
                    currencyCode: 'USD',
                    amountInMicros: 1000000,
                  },
                  taxIncluded: true,
                },
                {
                  type: 'TOTAL',
                  name: 'Total Price',
                  state: 'ACTUAL',
                  amount: {
                    currencyCode: 'USD',
                    amountInMicros: 1000000,
                  },
                  taxIncluded: true,
                },
              ],
              note: 'Extra pepperoni',
              quantity: 1,
              subOptions: [],
            },
          ],
        },
      },
    ],
  },
  buyerInfo: {
    email: 'janedoe@gmail.com',
    firstName: 'Jane',
    lastName: 'Doe',
    displayName: 'Jane Doe',
  },
  priceAttributes: [
    {
      type: 'SUBTOTAL',
      name: 'Subtotal',
      state: 'ESTIMATE',
      amount: {
        currencyCode: 'USD',
        amountInMicros: 9990000,
      },
      taxIncluded: true,
    },
    {
      type: 'DELIVERY',
      name: 'Delivery',
      state: 'ACTUAL',
      amount: {
        currencyCode: 'USD',
        amountInMicros: 2000000,
      },
      taxIncluded: true,
    },
    {
      type: 'TAX',
      name: 'Tax',
      state: 'ESTIMATE',
      amount: {
        currencyCode: 'USD',
        amountInMicros: 3780000,
      },
      taxIncluded: true,
    },
    {
      type: 'TOTAL',
      name: 'Total Price',
      state: 'ESTIMATE',
      amount: {
        currencyCode: 'USD',
        amountInMicros: 15770000,
      },
      taxIncluded: true,
    },
  ],
  followUpActions: [
    {
      type: 'VIEW_DETAILS',
      title: 'View details',
      openUrlAction: {
        url: 'http://example.com',
      },
    },
    {
      type: 'CALL',
      title: 'Call us',
      openUrlAction: {
        url: 'tel:+16501112222',
      },
    },
    {
      type: 'EMAIL',
      title: 'Email us',
      openUrlAction: {
        url: 'mailto:person@example.com',
      },
    },
  ],
  termsOfServiceUrl: 'http://www.example.com',
  note: 'Sale event',
  promotions: [
    {
      coupon: 'COUPON_CODE',
    },
  ],
  purchase: {
    status: 'CREATED',
    userVisibleStatusLabel: 'CREATED',
    type: 'FOOD',
    returnsInfo: {
      isReturnable: false,
      daysToReturn: 1,
      policyUrl: 'http://www.example.com',
    },
    fulfillmentInfo: {
      id: 'FULFILLMENT_SERVICE_ID',
      fulfillmentType: 'DELIVERY',
      expectedFulfillmentTime: {
        timeIso8601: '2019-09-25T18:00:00.877Z',
      },
      location: location,
      price: {
        type: 'REGULAR',
        name: 'Delivery Price',
        state: 'ACTUAL',
        amount: {
          currencyCode: 'USD',
          amountInMicros: 2000000,
        },
        taxIncluded: true,
      },
      fulfillmentContact: {
        email: 'johnjohnson@gmail.com',
        firstName: 'John',
        lastName: 'Johnson',
        displayName: 'John Johnson',
      },
    },
    purchaseLocationType: 'ONLINE_PURCHASE',
  },
};

Membuat pesanan dan opsi presentasi

Sebelum mengonfirmasi pesanan, pengguna akan melihat kartu pesanan yang diusulkan. Anda dapat menyesuaikan cara kartu ini ditampilkan kepada pengguna dengan menyetel berbagai opsi urutan dan presentasi.

Berikut adalah opsi pesanan dan presentasi untuk melakukan pemesanan yang memerlukan alamat pengiriman, termasuk email pengguna di kartu konfirmasi pesanan:

const orderOptions = {
      'requestDeliveryAddress': true,
      'userInfoOptions': {
        'userInfoProperties': ['EMAIL']
      }
    };

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

Membuat parameter pembayaran

Objek paymentParameters Anda menyertakan merchantPaymentOption dengan kolom yang mendeskripsikan 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'
          }
        }]
      }
    };

Menyimpan data pesanan di parameter sesi

Dari fulfillment Anda, simpan data pesanan ke parameter session. Objek urutan akan digunakan di seluruh adegan untuk sesi yang sama.

conv.session.params.order = {
    '@type': 'type.googleapis.com/google.actions.transactions.v3.TransactionDecisionValueSpec',
    order: order,
    orderOptions: orderOptions,
    presentationOptions: presentationOptions,
    paymentParameters: paymentParameters
};

Mengusulkan perintah

Setelah membuat pesanan, Anda harus menyajikannya kepada pengguna untuk mengonfirmasi atau menolak. Untuk melakukannya, Anda harus beralih ke scene yang menjalankan keputusan transaksi.

Membuat scene Transaksi Keputusan

  1. Dari tab Scenes, tambahkan scene baru dengan nama TransactionDecision.
  2. Di bagian Pengisian slot, 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 untuk slot.
  5. Aktifkan kotak centang Sesuaikan nilai penulisan ulang slot slot (diaktifkan secara default).
  6. Di bagian Konfigurasi slot, pilih Gunakan parameter sesi dari menu dropdown.
  7. Di bagian Slot slot, masukkan nama parameter sesi yang digunakan untuk menyimpan pesanan ke dalam kolom teks (yaitu $session.params.order).
  8. Klik Simpan.

Dalam upaya untuk mengisi slot TransactionDecisionValue, Asisten memulai pengalaman bawaan saat Order yang Anda teruskan dirender langsung ke "kartu pratinjau keranjang". Pengguna dapat mengucapkan "pesanan", menolak transaksi, mengubah opsi pembayaran seperti kartu kredit atau alamat, atau meminta untuk mengubah konten pesanan.

Pengguna juga dapat meminta perubahan atas pesanan untuk saat ini. Dalam hal ini, Anda harus memastikan fulfillment Anda dapat menangani permintaan perubahan pesanan setelah menyelesaikan pengalaman perakitan keranjang.

Menangani hasil Keputusan Transaksi

Saat slot TransactionDecisionValue terisi, jawaban pengguna untuk 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:

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

  3. Di kolom teks, masukkan sintaksis kondisi berikut untuk memeriksa kondisi sukses:

    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 Send prompt dan berikan perintah sederhana untuk memberi tahu pengguna bahwa pesanannya telah selesai:

    candidates:
  - first_simple:
      variants:
        - speech: >-
            Transaction completed! Your order
            $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. Di kolom teks, masukkan sintaksis kondisi berikut untuk memeriksa kondisi gagal:

      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 Kirim perintah dan berikan perintah sederhana untuk memberi tahu pengguna bahwa pesanan telah ditolak:

    candidates:
  - first_simple:
      variants:
        - speech: Look like you don't want to order anything. Goodbye.

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

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

  13. Aktifkan Send prompt 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 Transisi, pilih Akhiri percakapan untuk mengakhiri percakapan jika pengguna tidak dapat melakukan transaksi.

Selesaikan pesanan dan kirimkan tanda terima

Saat slot TransactionDecisionValue menampilkan hasil ORDER_ACCEPTED, Anda harus segera melakukan pemrosesan apa pun yang diperlukan untuk "mengonfirmasi" pesanan (seperti mempertahankannya di database 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 yang diciutkan" beserta respons lainnya. Kartu ini akan mencerminkan tanda terima yang ditemukan pengguna di Histori Pesanannya.

Selama konfirmasi pesanan, objek pesanan Anda dapat menyertakan userVisibleOrderId, yang merupakan ID yang dilihat oleh pengguna untuk pesanan. Anda dapat menggunakan kembali merchantOrderId untuk kolom ini.

Bagian dari objek OrderUpdate harus berisi objek tindakan lanjutan, yang diwujudkan sebagai tombol URL di bagian bawah detail pesanan yang dapat ditemukan pengguna di Histori Pesanan Asisten.

  • Anda harus menyediakan tindakan minimal VIEW_DETAILS untuk setiap pesanan. Ini harus berisi deep-link ke representasi pesanan di aplikasi seluler atau situs Anda.
  • Anda juga harus mengirim 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:

  1. Dari tab Scenes, pilih scene TransactionDecision.

  2. Di bagian Kondisi, pilih kondisi yang memeriksa hasil sukses, 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. Pada 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 memberikan informasi kepada pengguna tentang status pesanan selama masa aktifnya. Kirim pembaruan pesanan pengguna dengan mengirimkan permintaan PATCH HTTP ke API Pesanan dengan status dan detail pesanan.

Menyiapkan permintaan asinkron ke Orders API

Permintaan update pesanan ke Orders API diotorisasi oleh token akses. Untuk menerapkan update pesanan ke Orders API, download kunci akun layanan JSON yang terkait dengan project Actions Console, lalu tukar kunci akun layanan dengan token pemilik yang dapat diteruskan ke header Authorization permintaan HTTP.

Untuk mengambil kunci akun layanan Anda, lakukan langkah-langkah berikut:

  1. Di Google Cloud Console, buka Menu ☰ > 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 > Owner.
  5. Setel jenis kunci ke JSON.
  6. Pilih Create.
  7. 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-langkah penginstalan dan contoh di halaman GitHub library klien API.

Anda juga dapat mereferensikan 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}

Berikan header berikut dalam permintaan Anda:

  • "Authorization: Bearer token" dengan token pemilik OAuth yang Anda tukarkan dengan kunci akun layanan.
  • "Content-Type: application/json".

Permintaan PATCH harus menggunakan isi JSON dengan format berikut:

{ "orderUpdate": OrderUpdate }

Objek OrderUpdate terdiri dari kolom tingkat atas berikut:

  • updateMask - Kolom pesanan yang ingin Anda perbarui. Untuk memperbarui status pesanan, tetapkan nilai ke purchase.status, purchase.userVisibleStatusLabel.

  • order - Konten update. Jika Anda memperbarui konten pesanan, tetapkan nilai ke objek Order yang telah diperbarui. Jika Anda memperbarui status pesanan (misalnya, dari "CONFIRMED" menjadi "SHIPPED"), objek akan berisi kolom berikut:

    • merchantOrderId - ID yang sama yang Anda tetapkan di objek Order.
    • lastUpdateTime - Stempel waktu untuk update ini ini.
    • purchase - Objek yang berisi hal berikut:
      • status - Status pesanan sebagai PurchaseStatus, seperti "SHIPPED" atau "DELIVERED".
      • userVisibleStatusLabel - Label yang dilihat pengguna menunjukkan detail status pesanan, seperti "Pesanan Anda telah dikirim dan sedang dikirim".

  • userNotification (opsional) - Objek userNotification yang dapat ditampilkan di perangkat pengguna saat update ini dikirim. Perlu diperhatikan 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 mendeskripsikan status pesanan saat ini. Pada kolom order.purchase.status update, gunakan salah satu nilai berikut:

  • CREATED - Pesanan diterima oleh pengguna dan "dibuat" dari perspektif Action Anda, tetapi memerlukan pemrosesan manual di backend.
  • CONFIRMED - Pesanan aktif dan sedang diproses untuk pemenuhan pesanan.
  • IN_PREPARATION - Pesanan sedang disiapkan untuk dikirim/dikirim, seperti makanan yang sedang dimasak atau item yang sedang dikemas.
  • READY_FOR_PICKUP - Pesanan dapat diambil oleh penerima.
  • DELIVERED - Pesanan telah dikirim ke penerima
  • OUT_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 pengiriman.
  • REJECTED - Jika Anda tidak dapat memproses, menagih, atau "mengaktifkan" pesanan.
  • CANCELLED - Pesanan dibatalkan oleh pengguna.

Anda harus mengirimkan pembaruan pesanan untuk setiap status yang relevan dengan transaksi Anda. Misalnya, jika transaksi Anda memerlukan pemrosesan manual untuk membuat log pesanan setelah dilakukan, kirim pembaruan pesanan CREATED hingga pemrosesan tambahan tersebut selesai. Tidak semua pesanan membutuhkan setiap nilai status.

Menguji project Anda

Saat menguji project, Anda dapat mengaktifkan mode sandbox di konsol Actions untuk menguji Action tanpa mengenakan metode pembayaran. Untuk mengaktifkan mode sandbox, ikuti langkah-langkah berikut:

  1. Di Konsol Actions, klik Test di navigasi.
  2. Klik Setelan.
  3. Aktifkan opsi Sandbox Pengembangan.

Untuk transaksi fisik, Anda juga dapat menetapkan kolom isInSandbox ke true dalam contoh. 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, sebaiknya baca langkah-langkah pemecahan masalah untuk transaksi.