Panduan developer agen Conversational Commerce

Panduan ini menjelaskan cara berintegrasi dengan Conversational API untuk memberikan pengalaman chat dinamis yang didukung AI bagi pelanggan Anda. Dengan memahami berbagai jenis kueri dan memanfaatkan respons API, Anda dapat memberikan penelusuran produk yang relevan, menjawab pertanyaan pelanggan, dan memandu pengguna akhir melalui perjalanan belanja mereka.

conversationalFilteringMode di Conversational API memperjelas perbedaan antara agen Conversational Commerce dan pemfilteran produk percakapan.

Penyiapan

Conversational API mendukung fitur agen Conversational Commerce:

Conversational API memungkinkan pengalaman chat di mana pengguna Anda mengirimkan kueri dan sistem menampilkan respons teks, jenis kueri yang diklasifikasikan, dan opsi penelusuran yang lebih baik.

API ini beroperasi sebagai layanan streaming, sehingga memungkinkan deteksi awal maksud kueri. Interaksi berikutnya dalam percakapan memerlukan lampiran conversation_id.

Untuk menampilkan hasil penelusuran, Retail API lama harus dipanggil secara paralel dengan Conversational API.

Mengirim kueri dari pengguna akhir

Bagian ini menjelaskan cara memulai pengalaman agen Conversational Commerce. Misalnya, pengguna Anda dapat memasukkan Bantu rencanakan pesta di kolom penelusuran.

Mengirim permintaan ke Vertex AI Search untuk commerce

Ada dua endpoint API yang berbeda:

  1. Conversational API harus digunakan untuk mengambil pengalaman percakapan.
  2. Search API inti harus digunakan untuk mengambil hasil penelusuran.

Endpoint 1: Permintaan API percakapan

  • Anda harus membuat permintaan agen Conversational Commerce dengan menetapkan input pengguna sebagai kueri.
  • Permintaan harus dikirim sebagai permintaan HTTP POST ke endpoint projects/*/locations/*/catalogs/*/placements/*:conversationalSearch.

Metode dan endpoint HTTP

  POST https://retail.googleapis.com/v2alpha/{placement=projects/*/locations/*/catalogs/*/placements/*}:conversationalSearch

Permintaan API percakapan:

Kueri awal

{
  "query": "Help me plan a party",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "placement": "projects/799252947591/locations/global/catalogs/default_catalog/placements/default_search",
  "visitorId": "your_visitor_id",
  "conversationId": "", // Leave empty for the first query
  "searchParams": {
    // IMPORTANT: These search parameters should mirror the configuration
    // of your core Search API calls to ensure consistency between LLM answers and search results.
    "filter": "categories:(\"Party Supplies\" OR \"Decorations\" OR \"Food & Drink\")"
  },
  "userInfo": {
    // Optional: User information for enhanced personalization
    // Example: "userId": "user123", "userAgent": "Chrome/120.0"
  },
  "conversationalFilteringSpec": {
    // Optional: Controls conversational filtering behavior. Defaults to DISABLED if unset.
    // "conversational_filtering_mode": "DISABLED" - Otherwise you can also explicitly set to disabled.
}
  • placement: Nama resource penempatan (seperti projects/your-project-id/locations/global/catalogs/default_catalog/placements/default_branch). Ini adalah parameter jalur dan wajib.
  • query: Kueri penelusuran mentah dari pengguna Anda. Kolom ini wajib diisi.
  • branch: Nama resource cabang, seperti projects/P/locations/L/catalogs/C/branches/B. Jika tidak disetel, default_branch akan digunakan. Kolom ini wajib diisi.
  • visitorId: ID unik untuk melacak pengunjung. Kolom ini wajib diisi.
  • conversationId: ID unik untuk melacak sesi percakapan. Untuk permintaan initial dalam percakapan baru, kolom ini harus kosong. Untuk permintaan berikutnya dalam percakapan yang sama, parameter ini harus ditetapkan ke conversation_id yang diterima dalam ConversationalSearchResponse sebelumnya.
  • searchParams: (Opsional) Parameter Penelusuran inti standar, seperti filter, canonicalFilter, sortBy, dan boostSpec. Sangat penting agar parameter ini mencerminkan konfigurasi yang digunakan dalam panggilan Search API inti Anda untuk memastikan konsistensi antara jawaban LLM dan hasil penelusuran produk yang ditampilkan.
  • userInfo: (Opsional) Informasi pengguna untuk personalisasi yang lebih baik. Dapat menyertakan userId, user_agent, direct_user_request (boolean).
  • conversationalFilteringSpec: (Opsional) Menentukan mode pemfilteran percakapan. Jika tidak disetel, nilai defaultnya adalah DISABLED.

    mode: Integrasikan Conversational API menggunakan salah satu dari tiga mode berikut untuk mengontrol pemfilteran produk percakapan:

    • DISABLED: Dalam mode ini, klien hanya menerapkan penelusuran agen Conversational Commerce. Ini adalah mode yang lebih disukai untuk panduan penerapan ini pada penelusuran agen Conversational Commerce.

      • Contoh permintaan API

              placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search"
        branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch"
        query: "show me some monster energy drinks"
        visitor_id: "test"
        conversational_filtering_spec {
          conversational_filtering_mode: DISABLED
        }

      Contoh respons API

              user_query_types: "SIMPLE_PRODUCT_SEARCH"
        conversation_id: "479fd093-c701-4899-bcc3-9e711233bdf9"
        refined_search {
          query: "monster energy drinks"
        }
    • ENABLED: Dalam mode ini, klien mengimplementasikan semua kemampuan percakapan, yang mencakup penelusuran agen Conversational Commerce dan pemfilteran produk percakapan.

      • Baca panduan tambahan tentang cara mengintegrasikan kedua produk percakapan.

      Contoh permintaan API

              placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search"
        branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch"
        query: "show me some monster energy drinks"
        visitor_id: "test"
        conversational_filtering_spec {
          conversational_filtering_mode: ENABLED
        }

      Contoh respons API

              user_query_types: "SIMPLE_PRODUCT_SEARCH"
        conversation_id: "479fd093-c701-4899-bcc3-9e711233bdf9"
        refined_search {
          query: "monster energy drinks"
        }
        conversational_filtering_result: {
            followup_question{
              followup_question: "What is the size?"
              suggested_answers {
                product_attribute_value {
                  name: "size",
                  value: "12oz"
                }
              }
        }
        }
    • CONVERSATIONAL_FILTER_ONLY: Jika dipilih, klien hanya menerapkan Pemfilteran produk percakapan. Dengan mode ini dipilih, pengguna hanya akan mengalami pemfilteran produk percakapan tanpa menghasilkan jawaban LLM, klasifikasi kueri, atau kueri penelusuran yang disarankan.

      • Lihat Panduan developer filter produk percakapan untuk mengetahui informasi selengkapnya.

Endpoint 2: Permintaan Core Search API

Ada dua pendekatan utama untuk menampilkan hasil penelusuran di antarmuka web Anda.

Opsi 1: Selalu tampilkan hasil penelusuran

Jika desain pengalaman pengguna Anda menentukan bahwa hasil penelusuran harus selalu ditampilkan terlepas dari output percakapan, seperti di area hasil penelusuran khusus di samping chat, kirim kueri asli pengguna Anda ke Product Search API inti dengan panggilan Anda ke Conversational API. Hal ini membantu memastikan listingan produk langsung tersedia.

Opsi 2: Menampilkan hasil penelusuran berdasarkan output percakapan

Jika desain pengalaman pengguna Anda lebih dinamis dan Anda hanya ingin menampilkan hasil penelusuran bergantung pada respons Conversational API, seperti hanya untuk kueri SIMPLE_PRODUCT_SEARCH atau setiap kali saran refined_search diberikan, tunggu respons Conversational API sebelum mengirimkan kueri apa pun ke Product Search API inti. Jika ada respons, gunakan kueri refined_search yang diberikan untuk mengambil hasil produk.

Terlepas dari opsi antarmuka pengguna yang Anda pilih, saat Anda perlu mengambil hasil produk sebenarnya, Anda dapat melakukan panggilan ke Retail API. Untuk mengetahui informasi selengkapnya, lihat Memahami jenis kueri dan tindakan retailer.

Metode dan endpoint HTTP

    POST https://retail.googleapis.com/v2beta/{placement=projects/*/locations/*/catalogs/*/servingConfigs/*}:search

Permintaan API Penelusuran produk inti:

Kueri awal

    {
      "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/servingConfigs/default_search",
        // Or if using legacy placements:
        // "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
      "query": "Help me plan a party", // This is the original user query
      "visitorId": "your_visitor_id",
      "branch": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/branches/default_branch",
      "pageSize": 20, // Optional: Number of results to return per page
      "filter": "categories:(\"Party Supplies\" OR \"Decorations\" OR \"Food & Drink\")", // Mirroring the filter from the Conversational Commerce API
      "orderBy": "relevance DESC", // Optional
      "userInfo": {
        // Optional: User information for enhanced personalization, should mirror Conversational Commerce API
        // "userId": "user123", "userAgent": "Chrome/120.0"
      },
      "searchMode": "PRODUCT_SEARCH" // Typically for product searches
    }
  • placement (Wajib): Nama resource konfigurasi penayangan Retail Search atau penempatan lama. Contoh: projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/servingConfigs/default_search.
  • query: Wajib diisi. Kueri penelusuran. Ini bisa berupa input mentah pengguna Anda seperti Bantu saya merencanakan pesta atau refinedSearch.query yang lebih dioptimalkan (seperti perlengkapan perencanaan pesta, dekorasi) yang diperoleh dari respons Conversational Commerce API.
  • visitorId: Wajib diisi. ID unik untuk melacak pengunjung. Nilai ini harus konsisten dengan visitorId yang dikirim ke Conversational Commerce API untuk pengguna akhir yang sama.
  • branch (Wajib): Nama resource cabang, seperti projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/branches/default_branch.
  • pageSize (Opsional): Jumlah maksimum produk yang akan ditampilkan.
  • filter (Opsional): Digunakan untuk memfilter hasil penelusuran. Di sinilah Anda akan menerapkan filter apa pun yang mencerminkan apa yang Anda kirim di `searchParams` ke Conversational Commerce API agar konsisten.
  • orderBy (Opsional): Menentukan urutan produk ditampilkan (seperti berdasarkan relevansi atau harga).
  • userInfo (Opsional): Informasi pengguna untuk personalisasi, harus konsisten dengan panggilan Conversational Commerce API.
  • searchMode (Opsional): Menentukan perilaku penelusuran. PRODUCT_SEARCH umum untuk kueri produk umum.

Memahami respons

Contoh kode ini menunjukkan respons dari Conversational Commerce API.

Respons API (ConversationalSearchResponse) mencakup query_types, conversational_text_response (jika berlaku), opsi refined_search, dan kemungkinan followup_question atau conversational_filtering_result. conversation_id sangat penting untuk melanjutkan sesi.

Respons dari Vertex AI Search untuk commerce

Contoh kode ini menunjukkan respons Conversational API:

Respons awal

    {
      "userQueryTypes": ["INTENT_REFINEMENT"],
      "conversationalTextResponse": "To plan a party, you'll need decorations, snacks, party supplies, drinks, and a cake. You can find a wide variety of decorations, snacks, and drinks. For party supplies, you can find everything from plates and cups to balloons and streamers. And for cake, you can choose from a variety of flavors and sizes.",
      "followupQuestion": {
        "followupQuestion": "What kind of party are you planning?"
      },
      "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
      "refinedSearch": [
        { "query": "Decorations" },
        { "query": "Snacks" },
        { "query": "Party Supplies" },
        { "query": "Drinks" },
        { "query": "Cake" }
      ],
      "state": "SUCCEEDED"
    }

Yang harus dilakukan retailer dengan respons (Umum)

Render kolom ini dari respons:

  • user_query_types: Kolom ini memberikan klasifikasi maksud pengguna Anda. Untuk mengetahui tindakan mendetail berdasarkan jenis ini, lihat Memahami jenis kueri dan tindakan retailer.
  • conversation_id: Anda dapat menyimpan ID unik ini di penyimpanan sesi browser atau penyimpanan sisi klien serupa untuk mempertahankan sesi percakapan dengan server. Hal ini sangat penting untuk membedakan beberapa percakapan yang sedang berlangsung untuk satu pembeli. Model Anda mempertahankan konteks untuk conversation_id tertentu. Mengirim conversation_id baru akan memulai sesi baru. Sebaiknya tentukan durasi sesi Anda, seperti tidak ada aktivitas selama 30 menit.
  • refined_search: Ini adalah daftar kueri penelusuran yang disempurnakan yang diusulkan dan digunakan untuk mengambil hasil penelusuran yang relevan. Untuk SIMPLE_PRODUCT_SEARCH, selalu berupa satu kueri. Untuk kueri lain yang mencari jawaban LLM, jumlahnya adalah satu atau lebih. Kueri refined_search dapat digunakan untuk panggilan ke Search API inti (SearchService.Search) atau juga dapat ditampilkan kepada pengguna Anda sebagai saran.
  • conversational_text_response: Menampilkan teks ini kepada pengguna Anda sebagai respons utama buatan AI terhadap kueri mereka.
  • followup_question: Opsional. followup_question akan ditampilkan.
  • state: Kolom ini menunjukkan status pembuatan respons ("STREAMING" atau "SUCCEEDED"). Anda dapat menggunakan kolom ini untuk memberikan masukan pengalaman pengguna, seperti menampilkan indikator pemuatan hingga "SUCCEEDED". Detail selengkapnya tentang hal ini ada di bagian berikutnya.

Memahami streaming API

Conversational Commerce API beroperasi sebagai API streaming. Artinya, pengguna Anda menerima bagian respons dalam beberapa bagian, bukan satu payload lengkap.

Chunk pertama respons mencakup kueri query_types dan refined_search, dan state-nya ditunjukkan sebagai STREAMING. Deteksi niat yang lebih awal dan ketersediaan penyempurnaan penelusuran yang langsung ini memungkinkan model Anda membuat keputusan cepat tentang cara menangani kueri pengguna dan cara mengelola pengalaman pengguna terkait latensi dari respons LLM:

  • Untuk jenis kueri yang tidak mengharapkan respons teks percakapan, seperti SIMPLE_PRODUCT_SEARCH, RETAIL_IRRELEVANT, BLOCKLISTED, QUERY_TYPE_UNSPECIFIED, ORDER_SUPPORT, DEALS_AND_COUPONS, STORE_RELEVANT:
    • Karena query_types berada di potongan pertama, sistem Anda akan langsung mengetahui bahwa tidak ada jawaban LLM yang akan muncul. Anda dapat melanjutkan penanganan yang telah ditentukan sebelumnya untuk jenis ini, seperti menampilkan pesan statis, mengalihkan ke dukungan, tanpa menunggu output percakapan lebih lanjut.
    • Khusus untuk SIMPLE_PRODUCT_SEARCH, sistem Anda dapat langsung melakukan panggilan langsung ke Search API inti menggunakan kueri refined_search yang diterima di bagian pertama. Hal ini membantu memastikan hasil penelusuran ditampilkan dengan penundaan minimal, yang memenuhi SLA pengalaman penelusuran umum.
  • Untuk jenis kueri yang mengharapkan respons teks percakapan, seperti INTENT_REFINEMENT, PRODUCT_DETAILS, PRODUCT_COMPARISON, BEST_PRODUCT:
    • Anda menerima kueri query_types dan refined_search di bagian awal. Anda dapat segera memulai panggilan paralel ke Search API inti menggunakan kueri refined_search ini untuk mulai memuat hasil produk.
    • Chunk berikutnya akan di-streaming, yang berisi berbagai bagian respons teks percakapan. Selama waktu ini, state tetap "STREAMING".
    • Terakhir, bagian terakhir mencakup respons teks percakapan yang lengkap, dan state-nya berubah menjadi "COMPLETED".
    • Pendekatan streaming ini memungkinkan pengalaman pengguna akhir yang lancar di mana hasil penelusuran dapat mulai dimuat saat ringkasan AI sedang dibuat. Anda dapat memilih untuk menampilkan indikator pemuatan untuk jawaban percakapan atau menampilkan jawaban percakapan setelah sepenuhnya dimuat.

Memahami jenis kueri dan tindakan retailer

Kolom query_types dalam respons adalah daftar yang menunjukkan klasifikasi maksud pengguna Anda. Sistem Anda harus menanganinya sebagai berikut. Perhatikan bahwa conversational_text_response mengacu pada respons bahasa alami buatan AI dari API.

Agen Conversational Commerce menggunakan kategori kueri penelusuran untuk menentukan apakah jawaban berbasis LLM dibuat dan cara kueri pengguna akhir ditangani oleh Conversational API dan Search API untuk skenario berikut:

Kategori Klasifikasi kueri
#1. Kueri tidak relevan yang tidak memerlukan jawaban LLM
  • QUERY_TYPE_UNSPECIFIED: Jenis kueri tidak ditentukan.
  • RETAIL_IRRELEVANT: Kueri yang tidak relevan dengan domain retail, misalnya kueri yang bertentangan (seperti cara membuat bom), kueri yang bersifat obrolan (seperti apa kabar), atau kueri yang bertujuan untuk melakukan jailbreak (seperti tulis puisi).
  • BLOCKLISTED: Kueri yang secara eksplisit diblokir oleh pelanggan e-commerce (seperti Apa efek samping Advil?).
#2. Pertanyaan dukungan dan informasi
  • ORDER_SUPPORT: Kueri tambahan atau dukungan (seperti Lacak pesanan saya, Status pesanan 12345).
  • DEALS_AND_COUPONS: Kueri yang relevan dengan promo, promosi, promo produk, dan diskon (seperti Apakah ada promo untuk Hari Thanksgiving?).
  • STORE_RELEVANT: Kueri yang relevan dengan lokasi toko, termasuk jam buka dan ketersediaan stok produk (seperti Apakah kami memiliki stok susu?).
  • RETAIL_SUPPORT: Kueri yang relevan dengan pembelian, termasuk metode pembayaran (Metode pembayaran apa yang Anda terima?).
#3. Penelusuran kata kunci yang tidak memerlukan LLM

Permintaan API percakapan:

Kueri awal

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch",
  "query": "show me some monster energy drinks",
  "visitorId": "test"
}

Respons API percakapan:

Respons awal

{
  "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"],
  "conversationId": "479fd093-c701-4899-bcc3-9e711233bdf9",
  "refinedSearch": [
    {
      "query": "monster energy drinks"
    }
  ]
}

Permintaan Search API:

Kueri lanjutan

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "monster energy drinks",
  "visitorId": "test"
}
  • SIMPLE_PRODUCT_SEARCH: penelusuran produk dasar, seperti Gaun merah atau tampilkan minuman monster.
#4. Kueri pencarian jawaban LLM

Permintaan API percakapan:

Kueri awal

  {
    "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
    "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch",
    "query": "Compare 1% milk with 2% milk",
    "visitorId": "test"
  }

Respons API percakapan:

Respons awal

{
  "userQueryTypes": ["PRODUCT_COMPARISON"],
  "conversationalTextResponse": "1% milk contains 110 calories, 1.5 g of saturated fat, and 140 mg of sodium per cup. 2% milk is reduced fat with 37% less fat than regular milk and contains vitamins A & D.",
  "conversationId": "0e1cfdac-802f-422d-906e-9fc9f9d733ba",
  "refinedSearch": [
    {
      "query": "1% milk"
    },
    {
      "query": "2% milk"
    }
  ]
}

Permintaan Search API:

Kueri lanjutan

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "1% milk",
  "visitorId": "test"
}
  • PRODUCT_DETAILS: Pengguna Anda mencari detail dan spesifikasi produk, seperti tunjukkan spesifikasi [nama produk], Berapa kandungan protein dalam susu 2%?.
  • PRODUCT_COMPARISON: Perbandingan produk, seperti bandingkan [nama produk] dan [nama produk], Bandingkan susu 1% dengan susu 2%.
  • BEST_PRODUCT: Kueri dengan pola yang paling cocok, seperti Apa itu kue paling sehat?, Merek susu mana yang terbaik?.
#5. Penyempurnaan intent

Permintaan API percakapan:

Kueri awal

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch",
  "query": "Help me plan a party",
  "visitorId": "test"
}

Respons API percakapan:

Respons awal

{
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "To plan a party, you'll need decorations, snacks, party supplies, drinks, and a cake. You can find a wide variety of decorations, snacks, and drinks. For party supplies, you can find everything from plates and cups to balloons and streamers. And for cake, you can choose from a variety of flavors and sizes.",
  "followupQuestion": {
    "followupQuestion": "What kind of party are you planning?"
  },
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "Decorations" },
    { "query": "Snacks" },
    { "query": "Party Supplies" },
    { "query": "Drinks" },
    { "query": "Cake" }
  ],
  "state": "SUCCEEDED"
}
  • INTENT_REFINEMENT: Jenisnya tidak jelas dan percakapan lanjutan atau penyempurnaan mungkin diperlukan untuk mengklarifikasi jenisnya, seperti Bantu saya merencanakan pesta. Ini sering kali merupakan maksud yang paling populer dalam percakapan.

Kategori 1. Kueri tidak relevan yang tidak memerlukan jawaban LLM

  • QUERY_TYPE_UNSPECIFIED:
    • Tidak ada conversational_text_response yang diberikan.
    • Tindakan: Tangani sebagai kasus default atau error. Anda dapat meminta pengguna untuk mengklarifikasi atau mengarahkan mereka ke tempat mereka bisa mendapatkan bantuan umum.
  • RETAIL_IRRELEVANT:
    • Tidak ada conversational_text_response yang diberikan.
    • Tindakan: Tangani hal ini dengan menampilkan pesan yang sesuai, seperti Saya tidak dapat menjawab pertanyaan itu, atau Saya adalah asisten belanja, bagaimana saya dapat membantu Anda?, sebagaimana ditentukan oleh desain aplikasi Anda.
  • BLOCKLISTED:
    • Tidak ada conversational_text_response yang diberikan.
    • Tindakan: Tangani sesuai dengan kebijakan daftar blokir Anda, biasanya dengan menampilkan pesan tidak dapat memenuhi permintaan ini yang generik.

Kategori 2. Pertanyaan dukungan dan informasi

Untuk jenis ini, API tidak menyediakan conversational_text_response langsung secara default, tetapi Anda memiliki opsi untuk mengarahkan ke link atau resource yang tepat.

  • ORDER_SUPPORT:
    • Tindakan default: Tidak ada conversational_text_response yang diberikan. Antarmuka web Anda harus menampilkan beberapa pesan standar, link yang relevan, atau mengalihkan kueri ke API dukungan khusus atau saluran layanan pelanggan Anda sendiri.
  • DEALS_AND_COUPONS:
    • Tindakan default: Tidak ada conversational_text_response yang diberikan. Antarmuka web Anda harus menampilkan beberapa pesan standar, link yang relevan, atau mengalihkan kueri ke sistem promosi atau penawaran Anda.
  • STORE_RELEVANT:
    • Tindakan default: Tidak ada conversational_text_response yang diberikan. Antarmuka web Anda harus menampilkan beberapa pesan standar, link yang relevan, atau mengalihkan kueri ke sistem informasi atau pencari lokasi toko Anda sendiri.
  • RETAIL_SUPPORT:
    • Tindakan default: Tidak ada conversational_text_response yang diberikan. Antarmuka web Anda harus menampilkan beberapa pesan standar, link yang relevan, atau mengalihkan kueri ke sistem informasi dan pertanyaan umum Anda sendiri.

Kategori 3. Penelusuran kata kunci yang tidak memerlukan jawaban LLM

  • SIMPLE_PRODUCT_SEARCH:
    • Tidak ada respons teks percakapan yang dihasilkan.
    • Tindakan: Respons API selalu menampilkan satu kueri refined_search. Kueri yang dipersempit ini berfungsi sebagai istilah penelusuran yang disarankan. Lakukan panggilan langsung ke Search API inti (SearchService.Search) dan ambil hasil produk yang relevan menggunakan salah satu kueri asli atau kueri refined_search. refined_search.query mungkin tidak langsung berasal dari input pengguna akhir saat ini, tetapi juga dapat berasal dari konteks histori chat, seperti jika pengguna akhir sebelumnya menyempurnakan gaun pesta menjadi gaun merah, kueri yang disempurnakan dapat menjadi gaun pesta merah.
      • Untuk antarmuka percakapan (seperti chatbot): Sangat direkomendasikan untuk menggunakan refined_search.query yang disediakan oleh API. Dalam alur percakapan, kueri bahasa alami seperti "dapatkah Anda membantu saya menemukan pisang" dioptimalkan secara otomatis oleh API menjadi istilah penelusuran produk yang tepat ("pisang"), sehingga menghasilkan hasil produk yang lebih relevan.
      • Untuk pengalaman penelusuran inti (seperti halaman hasil penelusuran): Anda memiliki fleksibilitas untuk menggunakan refined_search.query dari API atau kueri asli yang diberikan oleh pengguna akhir, karena kueri asli kemungkinan besar sudah merupakan istilah penelusuran produk yang tepat. Pilih opsi yang paling sesuai dengan antarmuka web dan strategi tampilan hasil penelusuran Anda.
    • Opsi pengalaman pengguna: Percakapan tidak perlu diakhiri untuk kueri SIMPLE_PRODUCT_SEARCH. Pengguna Anda dapat melanjutkan percakapan dengan meneruskan conversation_id dalam permintaan berikutnya.
      • Opsi A: Mengakhiri antarmuka web percakapan: Banyak retailer memilih untuk mengalihkan pengguna Anda ke halaman hasil penelusuran standar setelah SIMPLE_PRODUCT_SEARCH terdeteksi, sehingga menutup jendela chat. Dalam skenario ini, jika pengguna akhir kemudian memasukkan kueri baru ke dalam kotak penelusuran standar tanpa conversation_id sebelumnya, kueri tersebut akan dianggap sebagai percakapan baru yang terpisah, dan conversation_id baru akan dikeluarkan.
      • Opsi B: Lanjutkan antarmuka web percakapan: Retailer dapat memilih untuk tetap membuka jendela chat. Tindakan ini memungkinkan pengguna Anda kembali ke mode percakapan. Keputusan untuk menerapkan Opsi A atau B sepenuhnya bergantung pada pengalaman pengguna pilihan retailer.

    Untuk mengatribusikan kueri penelusuran secara akurat ke interaksi percakapan dan menggunakan kemampuan analisis lengkap dalam Vertex AI Search untuk commerce, pemberian tag pada peristiwa yang tepat sangat penting:

    1. Mengambil conversation_id. Saat Anda melakukan panggilan API conversationalSearch, ConversationalSearchResponse.conversation_id akan ditampilkan.
    2. Beri tag pada peristiwa pengguna. Jika respons percakapan menghasilkan kueri penelusuran, seperti jika sistem Anda otomatis menjalankan penelusuran berdasarkan kueri yang disempurnakan untuk SIMPLE_PRODUCT_SEARCH, Anda harus memberi tag pada peristiwa pengguna penelusuran berikutnya (UserEvent) dengan conversation_id yang sama yang diterima di ConversationalSearchResponse.

Dengan memberi tag UserEvent.conversation_id dengan benar, analisis Anda dapat secara akurat mengatribusikan kueri penelusuran ke interaksi percakapan sebelumnya, sehingga memberikan insight berharga tentang perilaku dan jalur konversi pengguna Anda.

Kategori 4. Kueri LLM yang mencari jawaban

Untuk jenis kueri ini, API menghasilkan conversational_text_response (jawaban LLM) dan mungkin juga memberikan satu atau beberapa kueri refined_search. Percakapan tidak berakhir, dan pengguna akhir dapat melanjutkannya.

  • PRODUCT_DETAILS:
    • Tindakan: conversational_text_response memberikan detail produk yang diminta. Sistem Anda harus menampilkan informasi ini dengan jelas kepada pengguna.
    • Respons juga mencakup refined_search (satu atau beberapa kueri penelusuran yang disarankan, diurutkan dan diberi peringkat) yang harus digunakan untuk mengambil hasil penelusuran menggunakan Search API inti.
  • PRODUCT_COMPARISON:
    • Tindakan: conversational_text_response memberikan perbandingan produk yang ditentukan. Sistem Anda harus menampilkan informasi ini dengan jelas kepada pengguna.
    • Respons mencakup refined_search (satu atau beberapa kueri penelusuran yang disarankan, diurutkan dan diberi peringkat) yang harus digunakan untuk mengambil hasil penelusuran menggunakan Search API inti.
  • BEST_PRODUCT:
    • Tindakan: conversational_text_response memberikan rekomendasi atau informasi tentang produk yang paling cocok dengan kueri. Sistem Anda akan menampilkan informasi ini.
    • Respons mencakup refined_search (satu atau beberapa kueri penelusuran yang disarankan, diurutkan dan diberi peringkat) yang harus digunakan untuk mengambil hasil penelusuran menggunakan Search API inti.

Kategori 5. Penyempurnaan intent

  • INTENT_REFINEMENT:
    • Tindakan: Respons mencakup conversational_text_response, followup_question, dan refined_search (satu atau beberapa kueri penelusuran yang disarankan). Urutan tampilan yang direkomendasikan adalah sebagai berikut:
      1. conversational_text_response
      2. refined_search saran: Saran ini diurutkan dan diberi peringkat, jadi penting untuk menampilkannya dalam urutan yang sama dengan respons.
      3. Followup_question
    • Respons mencakup refined_search (satu atau beberapa kueri penelusuran yang disarankan, diurutkan dan diberi peringkat) yang harus digunakan untuk mengambil hasil penelusuran menggunakan Search API inti.
    • Untuk interaksi berikutnya, kirim jawaban pengguna Anda bersama dengan conversation_id.

Menampilkan kueri yang disarankan untuk produk

Berikut cara mengonfigurasi Google Penelusuran untuk menampilkan pertanyaan dan saran produk di agen Conversational Commerce.

Saat Conversational API menampilkan kueri refinedSearch, kueri ini memberikan peluang yang sangat baik untuk memandu pengguna akhir menuju produk yang relevan. Hal ini sangat berguna untuk Kategori 4 (kueri pencarian jawaban LLM) dan Kategori 5 (INTENT_REFINEMENT).

Rekomendasi

  • Tampilkan: Sajikan N (1-3, menunggu pengujian tentang jumlah ideal untuk antarmuka web Anda) refinedSearch kueri teratas kepada pengguna Anda.
  • Mekanisme: Kueri yang disarankan ini harus dijalankan melalui Search API inti (SearchService.Search) di latar belakang atau saat interaksi pengguna.
  • Presentasi: Tampilkan hasil sebagai carousel interaktif atau kartu yang dapat diklik, sehingga pengguna dapat menjelajahi kategori produk terkait atau item tertentu. Hal ini memberikan nilai langsung dan membantu menjembatani kesenjangan antara interaksi percakapan dan penemuan produk.

Permintaan Search API:

Kueri lanjutan

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "Decorations",
  "visitorId": "test"
}

Peristiwa yang akan dikirim ke Vertex AI Search untuk commerce

Penting untuk mengatribusikan kueri penelusuran secara akurat ke interaksi percakapan dan menggunakan kemampuan analisis lengkap dalam Vertex AI Search untuk commerce menggunakan pemberian tag peristiwa yang tepat:

  1. Mengambil conversation_id. Saat Anda melakukan panggilan API conversationalSearch, ConversationalSearchResponse.conversation_id akan ditampilkan.
  2. Beri tag pada peristiwa pengguna. Jika respons percakapan mengarah ke kueri penelusuran, seperti dengan menampilkan saran refined_search yang kemudian diklik oleh pengguna akhir, atau jika sistem Anda otomatis menjalankan penelusuran berdasarkan kueri yang disempurnakan, Anda harus memberi tag pada peristiwa pengguna penelusuran berikutnya (UserEvent) dengan conversation_id yang sama yang diterima di ConversationalSearchResponse.

Dengan memberi tag UserEvent.conversation_id dengan benar, analisis Anda dapat secara akurat mengatribusikan kueri penelusuran ke interaksi percakapan sebelumnya, sehingga memberikan insight berharga tentang perilaku pengguna dan jalur konversi.

Lanjutkan percakapan

Bagian ini menjelaskan cara sesi agen Conversational Commerce dipertahankan oleh Conversational API dan berlanjut di langkah terakhir ini.

Conversational API menggunakan conversation_id untuk mengelola percakapan yang sedang berlangsung. Untuk memastikan konsistensi antara jawaban LLM dan hasil penelusuran, permintaan Conversational API berikutnya harus menyertakan SearchParams yang mencerminkan konfigurasi panggilan Search API inti.

Penanganan sesi

  • Mulai percakapan baru:
    • Deskripsi: Untuk memulai percakapan baru, klien menghilangkan conversationId dari permintaan API.
    • Kapan harus memulai percakapan baru: Klien ingin memulai percakapan baru — sehingga mendapatkan conversationId baru dari respons API — dalam beberapa skenario umum pengalaman pengguna:
      • Tab atau sesi baru: Saat pelanggan membuka situs Anda di tab browser baru atau memulai sesi yang benar-benar baru.
      • Kueri asli baru: Dalam beberapa desain UX, jika pelanggan memasukkan kueri baru yang tidak terkait, Anda dapat memilih untuk memulai ulang alur percakapan untuk memastikan konteks yang paling relevan.
      • Tombol mulai ulang percakapan: Jika antarmuka web Anda menyediakan tombol Mulai percakapan baru atau Reset percakapan, mengklik tombol ini akan memicu sesi percakapan baru.
    • Integrasi API percakapan: Respons API mencakup conversationId baru yang digunakan untuk permintaan berikutnya.
  • Lanjutkan Percakapan:
    • Deskripsi: Conversational API menampilkan conversation_id sebagai bagian dari respons API. ID ini harus dikirim dalam permintaan lanjutan untuk melanjutkan percakapan yang sama. Hal ini membantu memastikan bahwa agen Conversational Commerce merespons kueri pengguna Anda berdasarkan histori percakapan dalam sesi tersebut, yang mencakup query pengguna akhir, conversational_text_response, dan followup_question.
    • Integrasi API percakapan: Klien meneruskan conversation_id dari respons sebelumnya di ConversationalSearchRequest.
  • Pastikan konsistensi hasil penelusuran:
    • Deskripsi: Untuk membantu memastikan jawaban LLM konsisten dengan hasil penelusuran yang ditampilkan kepada pengguna Anda, klien harus menggunakan searchParams dalam permintaan Conversational API. Parameter penelusuran ini harus memiliki konfigurasi yang sama, seperti filter, urutan pengurutan) dengan panggilan Search API yang dilakukan untuk mengambil hasil produk.
    • Integrasi API percakapan: Objek searchParams dalam ConversationalSearchRequest harus diisi secara identik dengan SearchRequest yang digunakan untuk penelusuran produk inti.

Mengirim permintaan ke Vertex AI Search untuk commerce

Anda dapat mengambil conversation_id dari penyimpanan sesi. Permintaan harus menyertakan query pelanggan baru, yang mungkin berupa balasan atas pertanyaan dari respons sebelumnya. Permintaan juga harus menyertakan refined_search.query terbaru dari respons sebelumnya jika pengguna akhir bertindak berdasarkan kueri yang disempurnakan. Jika tidak, kueri tersebut harus menyertakan kueri yang sama sekali baru dan tidak terkait, serta conversationId. Jangan lupa untuk selalu menyertakan searchParams.

  • Skenario 1: Kotak penelusuran tunggal dan percakapan persisten: Jika antarmuka penelusuran Anda hanya memiliki satu kotak penelusuran utama atau jendela percakapan persisten, Anda tidak akan mereset conversationId, meskipun pengguna akhir mengetik kueri baru yang tampaknya tidak terkait. Sistem menggunakan histori percakapan yang ada (terkait dengan conversationId) untuk memberikan respons yang relevan secara kontekstual.
  • Skenario 2: Jendela percakapan dan jendela kueri terpisah: Jika antarmuka penelusuran Anda menampilkan jendela chat percakapan yang berbeda dan kolom kueri penelusuran standar yang terpisah (seperti kotak penelusuran di seluruh situs), memasukkan kueri baru ke kolom penelusuran standar dapat secara implisit menandakan niat untuk memulai penelusuran baru yang tidak terkait, sehingga berpotensi menyebabkan conversationId direset untuk tindakan penelusuran tertentu tersebut. Namun, di dalam jendela percakapan khusus, conversationId harus selalu dipertahankan untuk kesinambungan.

Pada akhirnya, keputusan tentang kapan harus menggunakan kembali versus mereset conversationId adalah pilihan desain untuk mengoptimalkan pengalaman percakapan bagi pelanggan Anda.

Metode dan endpoint HTTP (sama seperti kueri awal)

POST https://retail.googleapis.com/v2alpha/{placement=projects/*/locations/*/catalogs/*/placements/*}:conversationalSearch

Permintaan API percakapan:

Kueri lanjutan

{
  "query": "A birthday party", // New query continuing the conversation from the previous turn
  "placement": "projects/799252947591/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "test", // Or your actual visitor_id
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", // conversation_id from previous response
  "searchParams": {
    "filter": "categories:(\"Birthday Party Supplies\")"
  }
}

Respons API percakapan:

Respons lanjutan

{
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "Great! For a birthday party, you might be interested in specific themes or age-group appropriate items.",
  "followupQuestion": {
    "followupQuestion": "What's the age group or theme?"
  },
  "refinedSearch": [
    { "query": "Birthday party decorations" },
    { "query": "Birthday party supplies" }
  ],
  "state": "SUCCEEDED"
}

Contoh pengguna akhir yang terus menerima pertanyaan:

  • Pertanyaan pengguna: Bantu saya merencanakan pesta.
  • Jawaban sistem: Pesta seperti apa yang Anda rencanakan?
  • Balasan pengguna: Pesta ulang tahun.

Yang harus dilakukan retailer dengan respons

Cara merender kolom mirip dengan respons awal, tetapi perhatikan perubahan yang mencerminkan percakapan yang berlanjut:

  • refined_search: Kolom ini berisi kueri yang diperbarui yang menggabungkan input terbaru pengguna akhir. Anda harus memperbarui konsol klien untuk kueri saat ini dengan tepat (seperti menampilkan kueri yang ditampilkan kepada pengguna yang telah berubah dari "dekorasi" menjadi "dekorasi pesta ulang tahun" atau "perlengkapan pesta ulang tahun"). Kueri refined_search dapat digunakan untuk panggilan ke Search API inti (SearchService.Search) atau juga dapat ditampilkan kepada pengguna akhir sebagai saran.
  • conversational_text_response: Menampilkan respons teks buatan AI baru yang relevan dengan giliran terakhir.
  • followup_question: Jika percakapan perlu dilanjutkan untuk penyempurnaan lebih lanjut, followup_question baru akan diberikan.

Peristiwa yang akan dikirim ke Vertex AI Search untuk commerce

Pemberian tag pada peristiwa penting untuk mengatribusikan kueri penelusuran secara akurat ke interaksi percakapan dan menggunakan kemampuan analisis di Vertex AI Search untuk commerce.

Ada dua langkah dalam proses pemberian tag pada peristiwa:

  1. Mengambil conversation_id. Saat Anda melakukan panggilan API conversationalSearch, ConversationalSearchResponse.conversation_id akan ditampilkan.
  2. Beri tag pada peristiwa pengguna. Jika respons percakapan menghasilkan kueri penelusuran, seperti dengan menampilkan saran refined_search, atau jika sistem Anda otomatis menjalankan penelusuran berdasarkan kueri yang disempurnakan, Anda harus memberi tag pada peristiwa pengguna penelusuran berikutnya (UserEvent) dengan conversation_id yang sama yang diterima di ConversationalSearchResponse.

Dengan memberi tag UserEvent.conversation_id dengan benar, analisis Anda dapat secara akurat mengatribusikan kueri penelusuran ke interaksi percakapan sebelumnya, sehingga memberikan insight berharga tentang perilaku pengguna akhir dan jalur konversi.

Mengintegrasikan agen dengan pemfilteran produk percakapan

Panduan ini menguraikan cara berintegrasi dengan Conversational API dan pemfilteran produk percakapan untuk memberikan pengalaman belanja yang didukung AI. Jika conversationalFilteringSpec.mode disetel ke ENABLED, sistem Anda dapat langsung bertransisi antara interaksi percakapan terbuka dan pemfilteran produk terpandu, sehingga menawarkan perjalanan pengguna yang sangat canggih.

Memahami interaksi

Jika agen commerce percakapan dan pemfilteran produk percakapan diaktifkan, sistem akan memanfaatkan keunggulan masing-masing. Agen Conversational Commerce menangani pertanyaan umum, memberikan respons buatan AI, dan menyempurnakan maksud awal, sementara pemfilteran produk percakapan memandu pengguna memilih atribut produk tertentu menggunakan model interaksi berbasis chip atau kartu yang disederhanakan.

Titik interaksi dan potensi transisi antara kedua mode ini terjadi saat klasifikasi Conversational Commerce API mengarah ke penelusuran berorientasi produk, khususnya SIMPLE_PRODUCT_SEARCH. Pada tahap ini, API dapat memberikan kueri penelusuran langsung atau, jika maksud pengguna dapat lebih disempurnakan, API akan memicu alur pemfilteran terpandu melalui pemfilteran produk percakapan.

Prinsip utama integrasi ini adalah bahwa semua input teks bebas ditangani oleh Conversational Commerce API, sedangkan klik pada jawaban yang disarankan yang muncul sebagai chip ditangani oleh pemfilteran produk percakapan.

Mengirim kueri pengguna

Contoh input pengguna: Bantu saya merencanakan pesta

Untuk mengaktifkan agen conversational commerce dan pemfilteran produk percakapan, pastikan ConversationalSearchRequest Anda menyertakan konfigurasi ini:

Permintaan Conversational Commerce API — Kueri awal

{
  "query": "Help me plan a party",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
  "visitorId": "your_visitor_id",
  "conversationId": "", // Leave empty for the first query, or populate for ongoing conversation
  "searchParams": {
    // IMPORTANT: These search parameters should mirror the configuration
    // of your Commerce Search API calls to ensure consistency.
    "filter": "categories:(\"Party Supplies\" OR \"Decorations\" OR \"Food & Drink\")"
  },
  "userInfo": {
    // Optional: User information for enhanced personalization
  },
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED" // Crucial for enabling product filtering
  }
}

Konfigurasi utamanya adalah:

  • Conversational_filtering_mode: ENABLED: Menetapkan kolom ini ke ENABLED di conversationalFilteringSpec memberi tahu API bahwa sistem Anda dapat menangani pemfilteran produk percakapan, sehingga API dapat memberikan respons khusus pemfilteran yang relevan.

Respons awal: Penyempurnaan maksud

Kolom userQueryTypes tetap menjadi pusat untuk memahami maksud pengguna. Untuk kueri awal yang luas seperti Bantu saya merencanakan pesta, API kemungkinan akan mengklasifikasikannya sebagai INTENT_REFINEMENT jika penelusuran produk yang lebih spesifik tidak langsung jelas.

Respons dari Google

Respons API Conversational Commerce — Kueri awal

{
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "To plan a party, you'll need decorations, snacks, party supplies, drinks, and a cake. You can find a wide variety of decorations, snacks, and drinks. For party supplies, you can find everything from plates and cups to balloons and streamers. And for cake, you can choose from a variety of flavors and sizes.",
  "followupQuestion": {
    "followupQuestion": "What kind of party are you planning?"
  },
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "Decorations" },
    { "query": "Snacks" },
    { "query": "Party Supplies" },
    { "query": "Drinks" },
    { "query": "Cake" }
  ],
  "state": "SUCCEEDED"
}

Tindakan

  1. Tampilkan conversationalTextResponse.
  2. Menampilkan refinedSearch saran seperti chip yang dapat diklik untuk Dekorasi, Camilan. Atau, panggil Commerce Search API secara paralel menggunakan kueri refined_search untuk menampilkan hasil produk yang relevan, seperti untuk Dekorasi, Camilan sebagai carousel, bersama dengan pertukaran percakapan.
  3. Tampilkan followupQuestion: Pesta seperti apa yang Anda rencanakan?
  4. Mengizinkan input pengguna bentuk bebas untuk melanjutkan percakapan.

Pemberian tag dan analisis peristiwa

Untuk memastikan analisis dan atribusi yang akurat untuk interaksi percakapan awal:

  • Mengambil conversation_id. Ambil conversation_id dari ConversationalSearchResponse. ID ini sangat penting untuk menautkan semua tindakan berikutnya ke sesi percakapan tertentu ini.
  • Beri tag pada peristiwa pengguna. Jika respons percakapan menghasilkan kueri penelusuran, seperti sistem Anda yang otomatis menjalankan penelusuran berdasarkan kueri refined_search, atau jika pengguna mengklik saran refined_search, Anda harus memberi tag pada peristiwa pengguna penelusuran berikutnya (UserEvent) dengan conversation_id yang sama.

Kueri lanjutan

Saat pengguna merespons followupQuestion, percakapan akan lebih baik.

Contoh input pengguna: Pesta ulang tahun

Penyempurnaan maksud | Cuplikan kode

Permintaan Conversational Commerce API — Kueri lanjutan

{
  "query": "A birthday party", // New query continuing the conversation from the previous turn
  "placement": "projects/799252947591/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "test", // Or your actual visitor_id
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", // conversation_id from previous response
  "searchParams": {},
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED"
  }
}

Respons Conversational Commerce API — Kueri lanjutan

{
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "Great! For a birthday party, you might be interested in specific themes or age-group appropriate items.",
  "followupQuestion": {
    "followupQuestion": "What's the age group or theme?"
  },
  "refinedSearch": [
    { "query": "Birthday party decorations" },
    { "query": "Birthday party supplies" }
  ],
  "state": "SUCCEEDED"
}

Tindakan

  1. Mirip dengan respons awal, perbarui antarmuka web dengan saran conversationalTextResponse, refinedSearch, dan followupQuestion baru.
  2. Lanjutkan alur percakapan, minta detail lebih lanjut.

Pemberian tag dan analisis peristiwa

Saat pengguna melanjutkan percakapan:

  • Mengambil conversation_id. Pastikan conversation_id dari ConversationalSearchResponse sebelumnya diteruskan di ConversationalSearchRequest saat ini.
  • Beri tag pada peristiwa pengguna. Jika respons percakapan menghasilkan kueri penelusuran baru, seperti karena pengguna mengklik saran refined_search atau sistem Anda melakukan panggilan penelusuran paralel, beri tag pada peristiwa pengguna penelusuran berikutnya (UserEvent) dengan conversation_id yang sama. Hal ini membantu melacak perjalanan percakapan multi-giliran.

Transisi ke pemfilteran produk percakapan

Saat percakapan menjadi lebih spesifik, sistem dapat mengklasifikasikan maksud sebagai SIMPLE_PRODUCT_SEARCH, dan jika sesuai, memicu pemfilteran produk percakapan.

Contoh input pengguna: Tema putri

Permintaan Conversational Commerce API — Kueri lanjutan

{
  "query": "Princess theme",
  "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "your_visitor_id",
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "searchParams": {},
  "userInfo": {},
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED"
  }
}

Jika kueri diklasifikasikan sebagai SIMPLE_PRODUCT_SEARCH, ada dua kemungkinan respons API, bergantung pada apakah Pemfilteran Produk Percakapan dipicu atau tidak. Perbedaan utamanya terletak pada keberadaan dan konten kolom conversationalFilteringResult.

Hasil 1: Pemfilteran dipicu

Hal ini terjadi saat kueri cukup inti untuk disempurnakan lebih lanjut berdasarkan atribut produk. Respons mencakup conversationalFilteringResult, yang harus diprioritaskan oleh antarmuka web Anda.

Respons Conversational Commerce API — Transisi ke pemfilteran produk: 

{
  "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"],
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "princess birthday decorations" }
  ],
  "conversationalFilteringResult": {
    "followupQuestion": "What specific type of princess decoration are you looking for?",
    "suggestedAnswers": [
      { "answer": "Balloons", "query": "princess birthday balloons" },
      { "answer": "Streamers", "query": "princess birthday streamers" },
      { "answer": "Tablecloths", "query": "princess birthday tablecloths" }
    ]
  },
  "state": "SUCCEEDED"
}

Tindakan

Kueri kini telah diklasifikasikan sebagai SIMPLE_PRODUCT_SEARCH. Dalam hal ini, pemfilteran produk percakapan akan dipicu. Namun, hal ini mungkin tidak memicu pemfilteran produk percakapan.

  • Prioritaskan antarmuka web pemfilteran produk percakapan:Jika conversationalFilteringResult diisi, hal ini menandakan bahwa Anda telah memasuki mode pemfilteran produk. Antarmuka web Anda harus menekankan followupQuestion, yang muncul di antarmuka pengguna seperti Jenis dekorasi putri seperti apa yang Anda cari?, dan suggestedAnswers, seperti tombol yang dapat diklik untuk Balon, Pita, Taplak Meja.
  • Menampilkan hasil produk: Segera panggil Retail Search API menggunakan refined_search.query (dekorasi ulang tahun putri) untuk menampilkan hasil produk awal bersama opsi pemfilteran.
  • Praktik pengalaman pengguna yang direkomendasikan: Harus ada satu kolom input teks bebas yang persisten untuk seluruh pengalaman. Panel ini akan tetap aktif setiap saat, termasuk selama alur pemfilteran produk percakapan. Saat conversationalFilteringResult aktif dan Anda menampilkan saran jawaban sebagai chip yang dapat diklik, pengguna memiliki dua opsi yang jelas:
    • Lanjutkan alur pemfilteran dengan mengklik jawaban yang disarankan.
    • Mulai giliran percakapan baru dengan mengetik kueri baru ke dalam kolom teks yang aktif. Input baru ini selalu memicu panggilan baru ke Conversational Commerce API, sehingga mengakhiri alur pemfilteran saat ini.

Hasil 2: Tidak ada pemfilteran yang dipicu

Jika kueri sudah cukup spesifik atau tidak dapat difilter lebih lanjut, respons tidak menyertakan kolom conversationalFilteringResult. Dalam hal ini, Anda harus melanjutkan dengan penelusuran standar.

Tindakan

  • Perlakukan interaksi sebagai akhir alur percakapan dan gunakan kueri refined_search untuk memanggil Retail Search API dan menampilkan halaman hasil produk standar.

Pemberian tag dan analisis peristiwa

Saat percakapan beralih ke pemfilteran produk:

  • Mengambil conversation_id. Terus menggunakan conversation_id yang sama.
  • Beri tag pada peristiwa pengguna. Jika transisi mengarah ke penelusuran langsung, beri tag UserEvent tersebut dengan conversation_id. Yang penting, saat pengguna berinteraksi dengan suggestedAnswers, seperti saat pengguna akhir mengklik Balon, tindakan ini juga harus memicu UserEvent, seperti peristiwa filter atau peristiwa search baru, yang diberi tag dengan conversation_id yang sama. Hal ini memungkinkan atribusi tindakan pemfilteran dalam alur percakapan.

Melanjutkan pemfilteran produk percakapan

Saat pengguna memilih suggestedAnswer, kirim ConversationalSearchRequest baru.

Contoh input pengguna (Mengklik jawaban yang disarankan): Balon

Penelusuran produk sederhana | Cuplikan kode

Permintaan Conversational Commerce API — Lanjutkan pemfilteran 

{
  "query": "Balloons", // The selected answer
  "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "your_visitor_id",
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", // Maintain conversation ID
  "searchParams": {},
  "userInfo": {},
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED"
  }
}

Respons Conversational Commerce API — Lanjutkan pemfilteran 

{
  "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"],
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "princess birthday balloons" }
  ],
  "state": "SUCCEEDED"
}

Tindakan

API merespons dengan kueri SIMPLE_PRODUCT_SEARCH, tetapi tanpa kolom conversationalFilteringResult, yang menunjukkan bahwa alur pemfilteran terpandu telah selesai.

  • Gunakan kueri refinedSearch akhir (balon ulang tahun putri) untuk melakukan panggilan langsung ke Retail Search API.
  • Tampilkan hasil produk akhir kepada pengguna. Pada tahap ini, percakapan dapat berakhir, atau pengguna dapat memasukkan kueri baru untuk memulai giliran baru.

Pemberian tag dan analisis peristiwa

Untuk setiap langkah dalam proses pemfilteran produk:

  • Mengambil conversation_id. Selalu gunakan conversation_id yang sama untuk semua permintaan dalam sesi pemfilteran.
  • Beri tag pada peristiwa pengguna. Setiap interaksi pengguna dengan suggestedAnswer seperti klik, harus memicu UserEvent yang relevan seperti peristiwa filter atau peristiwa search baru jika kueri baru dibuat. UserEvent ini harus diberi tag dengan conversation_id untuk melacak perjalanan pemfilteran secara akurat dan dampaknya terhadap konversi.

Rekomendasi antarmuka pengguna dan pilihan desain

Interaksi antara agen Conversational Commerce dan pemfilteran produk percakapan menawarkan fleksibilitas yang signifikan. Berikut beberapa pertimbangan UX utama untuk menciptakan pengalaman yang lancar dan intuitif:

  • Kotak input tunggal: Hanya boleh ada satu kotak input teks bebas untuk seluruh pengalaman. Tidak ada kolom input khusus yang terpisah untuk Pemfilteran Produk Percakapan. Hal ini menyederhanakan antarmuka pengguna dan menjaga konsistensi interaksi.
  • Transisi yang lancar: Desain antarmuka web Anda untuk membuat transisi antara respons percakapan, kueri yang disarankan, dan opsi pemfilteran terasa alami dan intuitif.
  • Panduan yang jelas: Gunakan isyarat visual seperti gaya tombol yang berbeda untuk jawaban yang disarankan, bukan input umum, dan petunjuk yang jelas untuk memandu pengguna berinteraksi di setiap tahap.
  • Menyeimbangkan kontrol: Pengguna harus selalu merasa dapat mengontrol arah percakapan.
    • Pemfilteran vs. bentuk bebas: Kolom input teks bebas tunggal tetap aktif setiap saat. Hal ini memberi pengguna pilihan yang konstan: mereka dapat mengklik saran jawaban untuk terus menyempurnakan penelusuran atau mengetik kueri baru ke dalam kolom teks untuk memulai giliran percakapan baru. Desain ini memastikan bahwa meskipun selama alur pemfilteran, pengguna dapat beralih ke topik lain jika kebutuhannya berubah.
    • Opsi reset: Berikan opsi Mulai percakapan baru atau Reset filter yang jelas untuk memungkinkan pengguna memulai ulang proses penelusuran atau pemfilteran mereka.

  • Persistensi visual: Bahkan saat bertransisi ke pemfilteran produk, mempertahankan histori percakapan dalam jendela chat, seperti menampilkan pertanyaan dan jawaban sebelumnya, dapat meningkatkan konteks dan pengalaman pengguna.

Pertimbangan dan praktik terbaik tambahan

Pertimbangan dan praktik terbaik tambahan harus dipertimbangkan saat menerapkan antarmuka agen Conversational Commerce Anda:

  • Konsistensi ID pengunjung: Membantu memastikan bahwa visitor_id unik dikirim secara konsisten dengan setiap permintaan untuk pengguna akhir tertentu. Hal ini sangat penting untuk personalisasi dan pelatihan model yang akurat. ID ini idealnya tetap konsisten untuk pengguna akhir di seluruh sesi dan status login atau logout.
  • Pengelolaan cabang: Meskipun default_branch umum, pastikan Anda menggunakan ID cabang yang benar jika katalog produk Anda disusun dengan beberapa cabang.
  • Interaksi Search API: Untuk SIMPLE_PRODUCT_SEARCH dan kasus apa pun saat refined_search diberikan, jangan lupa untuk melakukan panggilan terpisah ke Search API inti (SearchService.Search) menggunakan query dari kolom refined_search atau kueri asli untuk mendapatkan listingan produk yang sebenarnya. Conversational API terutama berfokus pada pengalaman percakapan dan pemahaman maksud pengguna, bukan langsung menampilkan hasil produk.
  • Desain antarmuka pengguna: Desain antarmuka web Anda untuk menampilkan opsi conversational_text_response, followup_question, dan refined_search dengan jelas secara intuitif untuk memandu pengguna Anda.

Langkah berikutnya

Untuk referensi dukungan tambahan, lihat FAQ fitur percakapan.