Transactions API tidak akan digunakan lagi mulai 3 Mei 2023, sebelum penghentian Percakapan Percakapan pada 13 Juni 2023. Untuk mengetahui informasi selengkapnya, lihat Penghentian Action Percakapan.

Halaman ini diterjemahkan oleh Cloud Translation API.

Membuat transaksi fisik dengan pembayaran yang dikelola penjual

Panduan ini menuntun Anda dalam proses pengembangan project Action yang menggabungkan transaksi untuk barang fisik menggunakan metode pembayaran yang dikelola oleh situs Anda.

Alur transaksi

Jika project Action Anda menangani transaksi fisik menggunakan pembayaran yang dikelola penjual, menggunakan alur berikut:

Tautkan akun pengguna - Agar pengguna dapat menggunakan metode pembayaran yang telah disimpan dengan layanan Anda, gunakan Penautan Akun untuk mengaitkan Akun Google mereka dengan akun mereka di layanan Anda.
Kumpulkan informasi (opsional) - Tergantung pada sifat Anda mungkin ingin mengumpulkan informasi berikut dari pengguna di awal percakapan:
1. Memvalidasi persyaratan transaksi - Di awal bagian transaksi dalam percakapan, memvalidasi bahwa pengguna memenuhi persyaratan untuk melakukan transaksi, seperti memiliki informasi pembayaran yang dikonfigurasi dengan benar dan tersedia sebelum membuat keranjang belanja.
2. Minta alamat pengiriman - Jika transaksi memerlukan pengiriman alamat, mengumpulkannya dari pengguna.
Buat pesanan - Pandu pengguna untuk "perakitan keranjang" di mana mereka memilih item mana yang ingin mereka beli.
Usulkan pesanan - Setelah keranjang selesai, usulkan pesanan untuk pengguna sehingga mereka dapat mengkonfirmasi bahwa itu benar. Jika pesanan telah dikonfirmasi, Anda akan menerima respons dengan detail pesanan dan token pembayaran.
Menyelesaikan pesanan dan mengirimkan tanda terima - Setelah pesanan dikonfirmasi, perbarui pelacakan inventaris atau layanan pemenuhan pesanan lainnya, lalu kirimkan tanda terima kepada pengguna.
Kirim pembaruan pesanan - Selama masa pakai pemenuhan pesanan, memberikan pembaruan pesanan kepada pengguna dengan mengirimkan permintaan PATCH ke Pesanan Compute Engine API.

Pembatasan dan panduan peninjauan

Perlu diingat bahwa kebijakan tambahan berlaku untuk Tindakan dengan transaksi. Ini kita memerlukan waktu hingga enam minggu untuk meninjau Actions dengan transaksi, jadi saat merencanakan jadwal rilis. Untuk memudahkan proses peninjauan, pastikan Anda mematuhi kebijakan dan panduan untuk transaksi sebelum mengirimkan Action Anda untuk ditinjau.

Anda hanya dapat men-deploy Action yang menjual barang fisik di negara berikut:

Australia
Brasil
Kanada
Indonesia

Jepang
Meksiko
Qatar
Rusia

Singapura
Swiss
Thailand
Turkiye
Inggris Raya
Amerika Serikat

Mem-build project Anda

Untuk contoh percakapan transaksional, lihat transaksi Node.js contoh.

Penyiapan project

Ketika 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 sudah ada.
Buka Deploy > Informasi direktori.
Di bagian Informasi tambahan > Transaksi > centang kotak yang bertuliskan "Lakukan Tindakan Anda menggunakan Transactions API untuk melakukan transaksi barang fisik?".

Tautkan akun pengguna (opsional)

Saat menggunakan metode pembayaran sendiri untuk menagih pengguna, sebaiknya tautkan akun Google mereka dengan akun yang mereka miliki dengan layanan Anda sendiri untuk mengambil, tersedia, dan menagih metode pembayaran yang tersimpan di sana.

Mendesain antarmuka pengguna suara untuk alur otentikasi

Periksa apakah pengguna telah diverifikasi dan mulai alur penautan akun

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

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

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

Menyesuaikan adegan penautan akun

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

Di bagian Kondisi, klik Jika pengguna berhasil menyelesaikan penautan akun.
Konfigurasi cara melanjutkan alur jika pengguna setuju untuk menautkan akun mereka. Misalnya, panggil webhook untuk memproses logika bisnis kustom yang diperlukan dan bertransisi kembali ke scene awal.
Klik Simpan.

Di bagian Kondisi, klik Jika pengguna membatalkan atau menolak penautan akun.
Konfigurasikan bagaimana alur akan berjalan jika pengguna tidak setuju untuk menautkan menggunakan akun layanan. Misalnya, kirim pesan konfirmasi dan alihkan ke adegan yang menyediakan fungsi yang tidak memerlukan penautan akun.
Klik Simpan.

Di bagian Kondisi, klik Jika terjadi error sistem atau jaringan.
Konfigurasi cara alur selanjutnya jika alur penautan akun tidak dapat diselesaikan karena kesalahan sistem atau jaringan. Misalnya, kirim pesan konfirmasi dan alihkan ke adegan yang menyediakan fungsi yang tidak memerlukan penautan akun.
Klik Simpan.

Mengumpulkan informasi (opsional)

Memvalidasi persyaratan transaksi (opsional)

Segera setelah pengguna menunjukkan 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 rekening?" Jika pengguna mengatakan "pesan sepatu", Anda harus memastikan bahwa mereka dapat melanjutkan dan memberi mereka kesempatan untuk memperbaiki pengaturan apa pun yang mencegah mereka agar tidak melanjutkan transaksi. Untuk melakukannya, Anda harus beralih ke yang melakukan pemeriksaan persyaratan transaksi.

Membuat scene Pemeriksaan Persyaratan Transaksi

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

Pemeriksaan persyaratan transaksi akan memberikan salah satu hasil berikut:

Jika persyaratan terpenuhi, parameter sesi ditetapkan dengan keberhasilan dan Anda dapat melanjutkan dengan membuat pesanan pengguna.
Jika satu atau beberapa persyaratan tidak dapat dipenuhi, parameter sesi akan ditetapkan dengan kondisi kegagalan. Dalam hal ini, Anda harus mengalihkan arah pembicaraan dari 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 di ponsel pengguna.

Menangani hasil Pemeriksaan Persyaratan Transaksi

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

Pada 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 Anda tambahkan dan klik panah atas untuk menempatkannya sebelum if scene.slots.status == "FINAL".

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

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

Di bagian Transisi, pilih adegan lain, sehingga pengguna dapat melanjutkan percakapan dan melanjutkan dengan melakukan transaksi.
Pilih kondisi else if scene.slots.status == "FINAL".

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.

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 bertransisi ke adegan yang meminta pengguna untuk alamat pengiriman.

Membuat Adegan Alamat Pengiriman

Dari tab Scenes, tambahkan scene baru dengan nama DeliveryAddress.
Di bagian Pengisian slot, klik + untuk menambahkan slot baru.
Di bagian Select type, pilih actions.type.DeliveryAddressValue sebagai jenis slot.
Di kolom nama slot, berikan nama TransactionDeliveryAddress untuk slot.
Aktifkan kotak centang Customize slot value writeback (diaktifkan secara default).
Klik Save.

Saat mengonfigurasi slot, Anda dapat memberikan reason yang memungkinkan Anda untuk mengawali permintaan Asisten untuk mendapatkan alamat dengan string.Setelan default alasannya adalah "untuk mengetahui ke mana harus mengirim pesanan". Oleh karena itu, Asisten mungkin bertanya kepada pengguna: "Untuk mengetahui tujuan pengiriman pesanan, saya perlu mendapatkan alamat pengiriman Anda".

Pada platform dengan layar, pengguna akan memilih alamat yang ingin mereka gunakan untuk transaksi. Jika sebelumnya mereka tidak memberikan alamat, mereka akan bisa memasukkan alamat baru.
Di platform khusus suara, Asisten akan meminta izin kepada pengguna untuk membagikan alamat {i> default<i} mereka untuk transaksi. Jika mereka belum pernah diberi alamat, percakapan akan diserahkan ke telepon untuk dimasuki.

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

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

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

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

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

Aktifkan Kirim perintah dan berikan perintah sederhana yang memungkinkan pengguna mengetahui 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

Di bagian Transisi, pilih suasana lain, sehingga pengguna dapat melanjutkan percakapan tersebut.
Pilih kondisi else if scene.slots.status == "FINAL".

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

candidates:
  - first_simple:
      variants:
        - speech: I failed to get your delivery address.

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

Membuat pesanan

Setelah memiliki informasi pengguna yang dibutuhkan, Anda akan membuat perakitan" pengalaman yang memandu pengguna untuk membuat pesanan. Setiap Tindakan akan memiliki alur perakitan keranjang yang sedikit berbeda yang sesuai dengan produk atau layanan Anda.

Pengalaman perakitan keranjang yang paling dasar membuat pengguna memilih item dari daftar untuk ditambahkan sesuai urutannya, meskipun Anda dapat merancang percakapan untuk menyederhanakan {i>user experience<i}. Anda dapat membangun pengalaman perakitan keranjang yang memungkinkan untuk memesan ulang pembelian terbaru mereka melalui pertanyaan ya atau tidak. Anda juga dapat menyajikan {i>carousel<i} atau kartu daftar dari daftar “{i>featured<i}” teratas atau "direkomendasikan" item.

Sebaiknya gunakan rich respons untuk menampilkan opsi pengguna secara visual, tetapi juga merancang percakapan sedemikian rupa sehingga pengguna dapat membangun keranjang hanya menggunakan suara mereka. Untuk beberapa praktik terbaik dan contoh perakitan keranjang berkualitas tinggi, lihat Panduan Desain Transaksi.

Membuat pesanan

Sepanjang percakapan, Anda harus mengumpulkan hal-hal yang diinginkan pengguna dibeli lalu membuat objek Order.

Minimal, Order Anda harus berisi hal berikut:

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

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

Kode contoh di bawah menunjukkan pesanan 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: '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 opsi urutan dan presentasi

Sebelum pengguna mengonfirmasi pesanan mereka, mereka akan disajikan dengan proposal kartu pesanan. Anda dapat menyesuaikan cara kartu ini ditampilkan kepada pengguna dengan mengatur berbagai opsi urutan dan presentasi.

Di bawah ini adalah opsi pemesanan 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 menjelaskan metode pembayaran pengguna untuk pesanan mereka. Di bawah ini adalah contoh untuk parameter pembayaran, menggunakan kartu kredit Visa:

const paymentParamenters = {
      'merchantPaymentOption': {
        'defaultMerchantPaymentMethodId': '12345678',
        'managePaymentMethodUrl': 'https://example.com/managePayment',
        'merchantPaymentMethod': [{
          'paymentMethodDisplayInfo': {
            'paymentMethodDisplayName': 'VISA **** 1234',
            'paymentType': 'PAYMENT_CARD'
          },
          'paymentMethodGroup': 'Payment method group',
          'paymentMethodId': '12345678',
          'paymentMethodStatus': {
            'status': 'STATUS_OK',
            'statusMessage': 'Status message'
          }
        }]
      }
    };

Simpan data pesanan di parameter sesi

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

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

Ajukan pesanan

Setelah membuat pesanan, Anda harus menunjukkannya kepada pengguna untuk dikonfirmasi atau ditolak. Untuk melakukannya, Anda harus beralih ke adegan yang menjalankan keputusan transaksi.

Membuat scene Keputusan Transaksi

Dari tab Scenes, tambahkan scene baru dengan nama TransactionDecision.
Di bagian Pengisian slot, klik + untuk menambahkan slot baru.
Di bagian Select type, pilih actions.type.TransactionDecisionValue sebagai jenis slot.
Di kolom nama slot, berikan nama TransactionDecision untuk slot.
Aktifkan kotak centang Customize slot value writeback (diaktifkan secara default).
Di bagian Konfigurasi slot, pilih Gunakan parameter sesi dari menu dropdown.
Di bagian Konfigurasi slot, masukkan nama parameter sesi yang digunakan untuk menyimpan pesanan ke dalam kolom teks (yaitu $session.params.order).
Klik Save.

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

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

Untuk menangani hasil keputusan transaksi:

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

Di kolom teks, masukkan sintaksis kondisi berikut untuk memeriksa kondisi berhasil:

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

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

Aktifkan Kirim perintah dan berikan perintah sederhana yang memberi tahu pengguna pesanannya selesai:

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

Di bagian Transisi, pilih Akhiri percakapan untuk mengakhiri percakapan.
Di bagian Kondisi, klik + untuk menambahkan kondisi baru.

Pada 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 Anda tambahkan dan klik panah atas untuk menempatkannya sebelum if scene.slots.status == "FINAL".

Aktifkan Kirim perintah dan berikan perintah sederhana yang memberi tahu pengguna pesanan telah ditolak:

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

Di bagian Transisi, pilih Akhiri percakapan untuk mengakhiri percakapan.
Pilih kondisi else if scene.slots.status == "FINAL".

Aktifkan Kirim perintah dan berikan perintah sederhana yang memungkinkan pengguna tahu bahwa mereka tidak dapat melakukan transaksi:

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

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

Menyelesaikan pesanan dan mengirimkan tanda terima

Saat slot TransactionDecisionValue menampilkan hasil ORDER_ACCEPTED, Anda harus segera melakukan pemrosesan apa pun yang diperlukan untuk "mengonfirmasi" tindakan urutannya (seperti mempertahankannya di {i>database<i} Anda sendiri dan menagih pengguna).

Anda dapat mengakhiri percakapan dengan respons ini, tetapi Anda harus menyertakan untuk menjaga agar percakapan tetap berjalan. Saat Anda memberikan orderUpdate, pengguna akan melihat "kartu tanda terima diciutkan" beserta sisanya respons Anda. Kartu ini akan mencerminkan tanda terima yang ditemukan pengguna di Histori Pesanan.

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

Bagian dari objek OrderUpdate harus berisi objek tindakan tindak lanjut, yang berwujud sebagai tombol URL di bagian bawah detail pesanan yang dapat ditemukan di Histori Pesanan Asisten mereka.

Anda harus memberikan, minimal, VIEW_DETAILS Menindaklanjuti setiap pesanan. Kolom ini harus berisi deep link ke representasi pesanan di aplikasi seluler atau situs web Anda.
Anda juga harus mengirimkan tanda terima resmi melalui email yang memenuhi persyaratan hukum persyaratan untuk melakukan transaksi, selain kartu tanda terima dalam percakapan Action Anda.

Untuk mengirim pembaruan pesanan awal:

Dari tab Scenes, pilih scene TransactionDecision.

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

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

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

Di kode webhook Anda, tambahkan pengendali intent untuk mengirim pesanan awal perbarui:

app.handle('update_order', conv => {
  const currentTime = new Date().toISOString();
  let order = conv.session.params.TransactionDecision.order;
  conv.add(new OrderUpdate({
    'updateMask': {
      'paths': [
        'purchase.status',
        'purchase.user_visible_status_label'
      ]
    },
    'order': {
      'merchantOrderId': order.merchantOrderId,
      'lastUpdateTime': currentTime,
      'purchase': {
        'status': 'CONFIRMED',
        'userVisibleStatusLabel': 'Order confirmed'
      },
    },
    'reason': 'Reason string
  }));
});

Kirim pembaruan pesanan

Anda harus terus memberi tahu pengguna tentang status pesanan selama masa pakainya. Mengirim pembaruan pesanan pengguna dengan mengirim HTTP Permintaan PATCH ke Orders API dengan 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:

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

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

Anda juga dapat mereferensikan order-update.js di Contoh Node.js untuk contoh pertukaran kunci.

Kirim pembaruan pesanan

Setelah menukarkan kunci akun layanan dengan token pembawa OAuth, Anda dapat mengirimkan pembaruan pesanan sebagai permintaan PATCH yang diberi otorisasi 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 pesanan, tetapkan nilai ke purchase.status, purchase.userVisibleStatusLabel.
order - Konten update. Jika Anda memperbarui isi pesanan, tetapkan nilai ke objek Order yang diperbarui. Jika Anda memperbarui status pesanan (misalnya, dari "CONFIRMED" hingga "SHIPPED"), 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 PurchaseStatus, seperti "SHIPPED" atau "DELIVERED".
  - userVisibleStatusLabel - Label yang ditampilkan kepada pengguna yang memberikan detail tentang status pesanan, seperti "Pesanan Anda telah dikirim dan berada di ".
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 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. Dalam order.purchase.status update Anda gunakan salah satu nilai berikut:

CREATED - Pesanan diterima oleh pengguna dan "dibuat" dari perspektif Action Anda, tetapi memerlukan pemrosesan manual di back-end Anda.
CONFIRMED - Pesanan aktif dan sedang diproses untuk pemenuhan pesanan.
IN_PREPARATION - Pesanan sedang disiapkan untuk pengiriman, seperti makanan sedang dimasak atau barang yang dikemas.
READY_FOR_PICKUP - Pesanan tersedia untuk 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 tersebut sedang diproses.
RETURNED - Pesanan telah dikembalikan oleh pengguna setelah pengiriman.
REJECTED - Jika Anda tidak dapat memproses, menagih, atau melakukan tindakan lainnya "aktifkan" pesanan.
CANCELLED - Pesanan dibatalkan oleh pengguna.

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

Menguji project Anda

Saat menguji project, Anda dapat mengaktifkan mode sandbox di Konsol Actions untuk menguji Action Anda tanpa menagih 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 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 mengalami masalah selama pengujian, Anda harus membaca langkah pemecahan masalah kami untuk transaksi.