Membuat transaksi fisik dengan pembayaran yang dikelola penjual

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

Alur transaksi

Saat project Action Anda menangani transaksi fisik menggunakan pembayaran yang dikelola penjual, project tersebut akan menggunakan alur berikut:

  1. Menautkan akun pengguna - Agar pengguna dapat menggunakan metode pembayaran yang telah mereka simpan di layanan Anda, gunakan Penautan Akun untuk mengaitkan Akun Google mereka dengan akun miliknya di layanan Anda.
  2. Kumpulkan informasi (opsional) - Bergantung pada sifat transaksi, sebaiknya Anda mengumpulkan informasi berikut dari pengguna di awal percakapan:
    1. Validasi persyaratan transaksi - Di awal bagian transaksi dalam percakapan, validasi bahwa pengguna memenuhi persyaratan untuk melakukan transaksi, seperti memiliki informasi pembayaran yang dikonfigurasi dan tersedia dengan benar sebelum membuat keranjang mereka.
    2. Meminta alamat pengiriman - Jika transaksi memerlukan alamat pengiriman, kumpulkan alamat pengiriman dari pengguna.
  3. Membuat pesanan - Pandu pengguna dalam "perakitan keranjang" untuk memilih item yang ingin dibeli.
  4. Mengusulkan pesanan - Setelah keranjang selesai, ajukan pesanan kepada pengguna agar mereka dapat mengonfirmasi bahwa pesanan tersebut sudah benar. Jika pesanan dikonfirmasi, Anda akan menerima respons dengan 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. Mengirim pembaruan pesanan - Selama masa aktif pemenuhan pesanan, berikan pembaruan pesanan kepada pengguna dengan mengirimkan permintaan PATCH ke Orders API.

Pembatasan dan panduan peninjauan

Perlu diingat bahwa kebijakan tambahan berlaku untuk Action dengan transaksi. Kami memerlukan 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 menjual barang fisik 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 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 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?".

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

Mendesain antarmuka pengguna suara untuk alur autentikasi

Periksa apakah pengguna telah diverifikasi dan mulai alur penautan akun

  1. Buka project Action Builder Anda di Konsol Actions.
  2. Buat scene baru untuk memulai penautan akun di Action Anda:
    1. Klik Scene.
    2. Klik ikon add (+) untuk menambahkan adegan baru.
  3. Pada scene yang baru dibuat, klik ikon tambahkan untuk Kondisi.
  4. 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 menyediakan akses ke fungsi yang tidak memerlukan penautan akun.
    1. Di kolom Enter new expression pada bagian Kondisi, masukkan logika berikut: user.verificationStatus != "VERIFIED"
    2. Di bagian Transition, 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 pada bagian Kondisi, masukkan logika berikut: user.verificationStatus == "VERIFIED"
    2. Di bagian Transisi, pilih scene sistem Penautan Akun.
    3. Klik Simpan.

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

Menyesuaikan adegan 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 identitas mereka (misalnya, "Untuk menyimpan preferensi Anda").
  3. Klik Simpan.

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

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

  1. Di bagian Kondisi, klik Jika terjadi error sistem atau jaringan.
  2. Konfigurasikan cara alur akan dilanjutkan jika alur penautan akun tidak dapat diselesaikan karena error sistem atau jaringan. Misalnya, kirim pesan konfirmasi dan alihkan ke scene yang menyediakan fungsi yang tidak memerlukan penautan akun.
  3. Klik Simpan.

Mengumpulkan informasi (opsional)

Memvalidasi persyaratan transaksi (opsional)

Segera setelah pengguna menyatakan bahwa mereka ingin melakukan pembelian, Anda harus memeriksa untuk memastikan bahwa mereka dapat melakukan transaksi. Misalnya, saat dipanggil,Action Anda mungkin menanyakan, "Apakah Anda ingin memesan sepatu, atau memeriksa saldo rekening?" Jika pengguna mengucapkan "pesan sepatu", Anda harus memastikan bahwa mereka dapat melanjutkan dan memberinya kesempatan untuk memperbaiki setelan apa pun yang mencegah mereka melanjutkan transaksi. Untuk melakukannya, Anda harus beralih ke adegan yang melakukan pemeriksaan persyaratan transaksi.

Membuat scene Pemeriksaan Persyaratan Transaksi
  1. Dari tab Scene, 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 akan memberikan 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 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 Kirim perintah dan berikan perintah sederhana yang memberi tahu pengguna bahwa mereka siap 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 melakukan transaksi.

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

  8. Aktifkan Kirim perintah dan 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 Transition, pilih End conversation 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 wilayah layanan Anda. Untuk melakukannya, Anda harus beralih ke scene yang meminta pengguna untuk memasukkan alamat pengiriman.

Membuat Adegan Alamat Pengiriman

  1. Dari tab Scenes, tambahkan scene baru dengan nama DeliveryAddress.
  2. Di bagian Slot fill, klik + untuk menambahkan slot baru.
  3. Di bagian Pilih jenis, pilih actions.type.DeliveryAddressValue sebagai jenis slot.
  4. Di kolom nama slot, beri nama TransactionDeliveryAddress pada slot.
  5. Aktifkan kotak centang Customize slot value writeback (diaktifkan secara default).
  6. Klik Save.

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

  • Pada platform dengan layar, pengguna akan memilih alamat yang ingin mereka gunakan untuk transaksi. Jika sebelumnya belum pernah memberikan alamat, mereka akan dapat memasukkan alamat baru.
  • Pada platform suara saja, Asisten akan meminta izin kepada pengguna untuk membagikan alamat default mereka untuk transaksi. Jika mereka belum pernah memberikan alamat, percakapan akan diserahkan ke ponsel untuk entri.

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

  1. Dari tab Scenes, pilih scene DeliveryAddress 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.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 Kirim perintah dan berikan perintah sederhana yang memberi tahu pengguna bahwa Anda telah menerima alamatnya:

    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 Kirim perintah dan 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 Transition, pilih End conversation untuk mengakhiri percakapan jika pengguna tidak dapat melakukan transaksi.

Membuat pesanan

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

Pengalaman perakitan keranjang yang paling dasar memungkinkan pengguna memilih item dari daftar untuk ditambahkan ke pesanannya, meskipun Anda dapat mendesain percakapan untuk menyederhanakan pengalaman pengguna. Anda dapat mem-build pengalaman perakitan keranjang yang memungkinkan pengguna memesan ulang pembelian terbarunya melalui pertanyaan sederhana ya atau tidak. Anda juga dapat menyajikan carousel atau kartu daftar dari item "unggulan" atau "direkomendasikan" kepada pengguna.

Sebaiknya gunakan respons lengkap untuk menampilkan opsi pengguna secara visual, sekaligus desain percakapan sedemikian rupa sehingga pengguna dapat membuat keranjangnya hanya menggunakan suara. Untuk beberapa praktik terbaik dan contoh pengalaman penggabungan keranjang yang berkualitas tinggi, lihat Panduan Desain Transaksi.

Membuat pesanan

Selama percakapan, Anda harus mengumpulkan item yang ingin dibeli pengguna, lalu membuat 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.
  • priceAttributes - Detail harga pesanan, termasuk total biaya pesanan dengan diskon dan pajak.

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

Kode contoh di bawah menunjukkan urutan 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',
  },
};

Buat opsi urutan dan presentasi

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

Berikut adalah opsi urutan dan presentasi untuk melakukan pesanan 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 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'
          }
        }]
      }
    };

Simpan data pesanan di parameter sesi

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

Mengusulkan pesanan

Setelah membuat pesanan, 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 Pilih jenis, 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. Pada bagian Konfigurasi slot,masukkan nama parameter sesi yang digunakan untuk menyimpan urutan ke dalam kolom teks (yaitu $session.params.order).
  8. Klik Save.

Dalam upaya untuk 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 untuk mengubah isi pesanan.

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,
  • 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. 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 Send prompt dan memberikan perintah sederhana yang memberi tahu pengguna bahwa pesanannya sudah selesai:

    candidates:
      - first_simple:
          variants:
            - speech: >-
                Transaction completed! Your order
                $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: Look like you don't want to order anything. 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 pesanan dan kirim tanda terima

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

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

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

  • Setidaknya Anda harus memberikan Tindakan tindak lanjut VIEW_DETAILS dengan setiap pesanan. Daftar ini harus berisi deep link ke representasi pesanan di aplikasi seluler atau situs Anda.
  • Anda juga harus mengirimkan 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 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. Dalam 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 memberi tahu pengguna tentang status pesanan selama masa aktifnya. Kirim pembaruan pesanan pengguna dengan mengirimkan permintaan PATCH HTTP ke Orders API beserta 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 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 dan contoh penginstalan di halaman GitHub library klien API.

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

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 pesanan, tetapkan nilai ke purchase.status, purchase.userVisibleStatusLabel.
  • order - Konten update. Jika Anda memperbarui konten pesanan, tetapkan nilai ke objek Order yang diperbarui. Jika Anda memperbarui status pesanan (misalnya, dari "CONFIRMED" menjadi "SHIPPED"), 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 PurchaseStatus, seperti "SHIPPED" atau "DELIVERED".
      • userVisibleStatusLabel - Label yang ditampilkan kepada pengguna yang memberikan detail tentang status pesanan, seperti "Pesanan Anda telah dikirim dan sedang dalam perjalanan".
  • 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 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 deskriptif tentang status pesanan saat ini. Di kolom order.purchase.status update Anda, gunakan salah satu nilai berikut:

  • CREATED - Pesanan diterima oleh pengguna dan "dibuat" dari perspektif Action, tetapi memerlukan pemrosesan manual di back-end Anda.
  • CONFIRMED - Pesanan aktif dan sedang diproses untuk pemenuhan.
  • IN_PREPARATION - Pesanan sedang disiapkan untuk pengiriman, 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 diterima.
  • REJECTED - Jika Anda tidak dapat memproses, mengisi daya, atau "mengaktifkan" pesanan.
  • CANCELLED - Pesanan dibatalkan oleh pengguna.

Anda harus mengirim pembaruan pesanan untuk setiap status yang relevan dengan transaksi Anda. Misalnya, jika transaksi Anda memerlukan pemrosesan manual untuk mencatat pesanan ke dalam log setelah pemesanan dilakukan, kirim pembaruan pesanan CREATED hingga pemrosesan tambahan 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 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 mengalami masalah selama pengujian, sebaiknya baca langkah pemecahan masalah untuk transaksi.