Widget web adalah klien berbasis web yang dapat Anda gunakan di aplikasi web dan seluler agar pengguna dapat berinteraksi dengan aplikasi agen Anda menggunakan chat atau suara. Panduan ini memberikan ringkasan dan petunjuk penyiapan.
Saat dibuka, widget dapat ditampilkan sebagai jendela dialog mengambang di sudut kanan bawah, sebagai panel di samping konten utama, atau dibuka dalam mode dialog yang diperluas untuk percakapan yang lebih fokus.
Batasan
Saat ini, respons konten multimedia hanya mendukung bahasa Inggris.
Menyiapkan widget web
Untuk menyematkan widget di situs Anda:
- Klik Deploy di bagian atas pembuat agen.
- Klik Buat Channel atau Channel baru.
- Pilih jenis saluran Widget web.
- Masukkan nama untuk channel Anda.
- Pilih atau buat versi aplikasi agen.
- Konfigurasi preferensi lainnya, seperti tema warna dan jenis pengalaman (chat, panggilan, atau campuran).
- Klik Buat channel untuk membuat kode deployment.
- Tambahkan kode deployment ke HTML situs Anda.
- Siapkan autentikasi untuk pengguna akhir Anda. Widget akan menampilkan peringatan jika Anda menggunakan kode sematan yang tidak diubah tanpa mengonfigurasi autentikasi. Untuk mengetahui detail tentang opsi dan penyiapan, lihat bagian Mengonfigurasi autentikasi.
Menyematkan widget di situs Anda
Untuk menambahkan widget ke situs Anda, Anda harus menambahkan cuplikan HTML berikut.
Cuplikan di bawah menyertakan skrip yang diperlukan untuk reCAPTCHA. Jika reCAPTCHA digunakan di widget, notifikasi akan ditampilkan di bagian bawah widget yang menunjukkan bahwa situs dilindungi oleh Google dan bahwa Kebijakan Privasi serta Persyaratan Layanan Google berlaku. Anda juga dapat menyembunyikan badge RECAPTCHA.
Untuk mendukung tata letak responsif, Anda juga dapat memuat
chat-messenger-layout.css secara opsional.
File chat-messenger-layout.css digunakan untuk gaya responsif
dan untuk menggeser messenger masuk dan keluar dari tampilan
saat menggunakan render-mode="slide-in" atau render-mode="slide-over".
Karena menata gaya body,
hal ini dapat memengaruhi situs Anda.
Oleh karena itu, Anda dapat memilih untuk tidak memuat chat-messenger-layout.css,
atau Anda dapat menyalin isinya dan mengintegrasikannya ke CSS Anda sendiri.
Untuk performa terbaik dan memastikan tata letak responsif, ikuti penempatan berikut:
Di bagian <header>:
<header>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<script defer src="https://www.gstatic.com/ces-console/fast/chat-messenger/prod/v1/chat-messenger.js"></script>
<!-- Chat Messenger CSS -->
<link rel="stylesheet" href="https://www.gstatic.com/ces-console/fast/chat-messenger/prod/v1/themes/chat-messenger-default.css">
<!-- Optional responsive styling -->
<!-- <link rel="stylesheet" href="https://www.gstatic.com/ces-console/fast/chat-messenger/prod/v1/themes/chat-messenger-layout.css"> -->
<!-- CSS customization -->
<style>
chat-messenger {
z-index: 999;
position: fixed;
<!-- Your CSS customization goes here if needed -->
}
</style>
</header>
Di bagian <body>:
<body>
<!-- Your website's main content goes here -->
<script>
window.addEventListener("chat-messenger-loaded", () => {
chatSdk.registerContext(
chatSdk.prebuilts.ces.createContext({
deploymentName: "projects/YOUR_PROJECT_ID/locations/YOUR_REGION/apps/YOUR_APP_ID/deployments/YOUR_DEPLOYMENT_ID",
tokenBroker: {
enableTokenBroker: true,
// If you enabled reCAPTCHA for the token broker, set enableRecaptcha to true.
// enableRecaptcha: true,
},
}),
);
});
</script>
<!-- Messenger component -->
<chat-messenger
language-code="en"
max-query-length="-1">
<chat-messenger-chat-bubble
chat-title="${your-chat-title}">
</chat-messenger-chat-bubble>
</chat-messenger>
<!-- Page content continues -->
</body>
Pertimbangan keamanan
Saat menyematkan widget sebagai elemen kustom
(<chat-messenger>)
langsung ke situs Anda,
widget berjalan di
shadow DOM
di halaman host Anda.
Secara default, tidak menerapkan sandboxing ketat (seperti iframe).
Karena widget membagikan asal jendela dengan aplikasi Anda:
- Akses Penyimpanan Bersama:
Setiap skrip yang berjalan dalam komponen kustom widget
memiliki akses ke
window.sessionStoragedanwindow.localStoragehalaman host. Hal ini mencakup token autentikasi atau data sesi sensitif yang disimpan oleh widget itu sendiri. - Cross-Site Scripting (XSS): Jika kode komponen kustom atau payload Konten Multimedia Anda berisi input yang tidak disanitasi, kode tersebut dapat dieksploitasi untuk mengeksekusi JavaScript arbitrer dalam konteks aplikasi utama Anda.
Untuk menjaga keamanan aplikasi dan data pengguna Anda, Anda harus:
- Membersihkan Kode Kustom: Pastikan semua JavaScript dan HTML kustom yang digunakan dalam komponen atau payload kustom dibersihkan secara menyeluruh.
- Validasi Input: Perlakukan semua data yang diteruskan ke widget dari sumber eksternal (termasuk respons Agen) sebagai tidak tepercaya.
- Isolasi Handle: Jika persyaratan keamanan Anda mewajibkan isolasi ketat antara widget chat dan data aplikasi Anda, Anda harus menerapkan sandbox sendiri (misalnya, membungkus komponen widget dalam container yang Anda kontrol dan isolasi).
Mengonfigurasi pengalihan ke agen manusia
Sebelum mengonfigurasi widget, pastikan resource yang diperlukan telah dibuat dan deployment WebChat Proxy telah selesai.
- Siapkan nomor eskalasi.
- Buat resource
PhoneNumber
untuk project Anda.
- Gunakan Profil Percakapan yang valid dan dikonfigurasi untuk aplikasi agen.
- Kaitkan Profil Percakapan dengan PhoneNumber agar sistem dapat menangani eskalasi dari manusia.
- Ikuti petunjuk untuk menyiapkan WebChat Proxy.
- Buat resource
PhoneNumber
untuk project Anda.
Konfigurasi Klien Webchat:
Tetapkan atribut dari WebChat Proxy untuk mengaktifkan fitur penerusan langsung. Contoh cuplikan kode:
<chat-messenger service='{"name":"ces","deployment-id":"projects/YOUR_PROJECT_ID/locations/YOUR_REGION/apps/YOUR_APP_ID/deployments/YOUR_DEPLOYMENT_ID"}' liveHandoff="true" escalationNumber="projects/YOUR_PROJECT_ID/locations/global/phoneNumbers/YOUR_PHONE_NUMBER_ID" url-allowlist="*" > </chat-messenger>
Penyesuaian HTML
Anda dapat menyesuaikan berbagai aspek tampilan dan perilaku dialog chat.
Elemen HTML chat-messenger dan chat-messenger-container
memiliki atribut berikut:
| Atribut | Atribusi komponen | Nilai (opsional) | Efek |
|---|---|---|---|
| pelanggan | chat-messenger | Nama layanan yang diperlukan untuk layanan backend yang terhubung. | |
| url-allowlist | chat-messenger | * | (daftar domain gambar yang dipisahkan koma |
| logging-level | chat-messenger | DEBUG | <OMIT> |
| enable-audio-input-only | chat-messenger-container | Mode hanya suara | |
| start-with-recording | chat-messenger-container | Memerlukan mode Khusus suara. Mode khusus suara dimulai saat penampung chat-messenger dirender | |
| enable-audio-input | chat-messenger-container | Menambahkan tombol untuk mengizinkan chat multimodal | |
| enable-file-upload | chat-messenger-container | Mengaktifkan upload gambar | |
| bot-writing-image | chat-messenger-container | string | URL gambar yang dirender selama bot "berpikir" |
| chat-title-icon | chat-messenger-container | string | URL gambar yang ditampilkan di bagian atas chat (Gambar merek) |
| chat-title | chat-messenger-container | string | Teks untuk judul chat |
| render-mode | chat-messenger | string ("slide-in" atau "slide-over") | Mode rendering dialog chat relatif terhadap halaman lainnya. Opsinya adalah "slide-over" atau "slide-in". Jika tidak ditentukan, penentuan posisi dapat ditentukan oleh klien. Gaya diperlukan untuk mendukung mode render. chat-messenger-layout.css dapat digunakan sebagai dasar pengukuran. |
Penyesuaian CSS
Penyesuaian tampilan widget ditangani melalui sistem token CSS. Dengan mengubah token ini, Anda dapat memastikan antarmuka chat terasa konsisten dengan merek Anda sekaligus menjaga integritas tata letak dan aksesibilitas.
Token Warna
Token ini menentukan palet warna untuk permukaan widget, elemen interaktif, teks, dan status.
| Properti | Deskripsi | Tema Terang Default | Tema Gelap Default |
|---|---|---|---|
| Container / Platform | |||
| --chat-messenger-color--surface | Warna latar belakang utama untuk area isi dan footer chat. | #F8FAFD | #1B1B1B |
| --chat-messenger-color--surface-container | Warna latar belakang untuk penampung widget (misalnya, kartu produk dan carousel) yang berada di dalam chat. | #FFFFFF | #131314 |
| --chat-messenger-color--surface-container-high | Latar belakang dengan penekanan tinggi untuk elemen dalam widget (misalnya, kolom input) | #F0F4F9 | #1E1F20 |
| Merek / Aksen | |||
| --chat-messenger-color--primary | Warna merek utama yang digunakan untuk pengisian penekanan tinggi dan tombol utama. | #303030 | #E3E3E3 |
| --chat-messenger-color--primary-container | Warna latar belakang yang menarik untuk komponen utama seperti balon pesan pengguna. | #E9EEF6 | #282A2C |
| --chat-messenger-color--secondary | Warna untuk elemen interaktif sekunder, seperti tombol "Kirim" atau tombol tonal. | #DDE3EA | #333537 |
| Teks & Ikon | |||
| --chat-messenger-color--on-surface | Warna primer untuk teks dan ikon yang ditampilkan dengan latar belakang permukaan standar. | #1F1F1F | #E3E3E3 |
| --chat-messenger-color--on-surface-variant | Warna dengan penekanan lebih rendah untuk teks sekunder dan ikon dekoratif. | #444746 | #C4C7C5 |
| --chat-messenger-color--on-primary | Warna untuk teks dan ikon yang ditempatkan di atas latar belakang merek utama. | #F2F2F2 | #303030 |
| --chat-messenger-color--on-primary-container | Warna untuk teks dan ikon yang ditempatkan di atas latar belakang primary-container. | #1F1F1F | #E3E3E3 |
| --chat-messenger-color--on-secondary | Warna untuk teks dan ikon yang ditempatkan di atas latar belakang merek sekunder. | #444746 | #C4C7C5 |
| Negara bagian | |||
| --chat-messenger-color--state-layer-on-surface | Overlay transparan yang digunakan untuk menunjukkan status mengarahkan kursor atau pemilihan pada permukaan standar. Pengisian untuk komponen yang dinonaktifkan. | #1F1F1F 8% | #E3E3E3 8% |
| --chat-messenger-color--state-layer-on-primary | Overlay transparan yang digunakan untuk status interaksi di atas elemen berwarna primer. | #FFFFFF 8% | #062E6F 8% |
| --chat-messenger-color--state-layer-on-secondary | Overlay transparan yang digunakan untuk status interaksi di atas elemen berwarna sekunder. | #1F1F1F 8% | #E3E3E3 8% |
| --chat-messenger-color--state-on-surface-mute | Warna untuk teks dan ikon yang dinonaktifkan. | #444746 (38%) | #C4C7C5 (38%) |
| Utilitas | |||
| --chat-messenger-color--outline | Warna untuk batas umum, pemisah, dan garis batas dekoratif. | #C4C7C5 | #444746 |
| --chat-messenger-color--outline-variant | Warna untuk batas halus (misalnya, frame luar widget) | #747775 pada 16% | #8E918F pada 16% |
| --chat-messenger-color--outline-active | Warna batas untuk kolom input dan dropdown saat difokuskan atau aktif. | #747775 | #8E918F |
| --chat-messenger-color--error | Warna yang menarik perhatian terhadap platform untuk pengisian, ikon, dan teks, yang menunjukkan urgensi. | #B3261E | #F2B8B5 |
| --chat-messenger-color--error-container | Warna pengisi latar belakang untuk banner error atau penampung peringatan interaktif. | #F9DEDC | #8C1D18 |
| --chat-messenger-color--on-error-container | Teks dan ikon ditempatkan di latar belakang error-container. | #8C1D18 | #F9DEDC |
| --chat-messenger-color--link | Warna yang digunakan untuk hyperlink yang dapat diklik dalam pesan atau deskripsi. | #0B57D0 | #A8C7FA |
Token Bentuk & Ketinggian
Token ini mengontrol radius sudut dan kedalaman visual (bayangan) komponen chat.
| Properti | Deskripsi | Default |
|---|---|---|
| --chat-messenger-shape--corner-value-small | Radius sudut untuk elemen bertingkat kecil dalam widget (misalnya, thumbnail gambar produk) | 8px |
| --chat-messenger-shape--corner-value-medium | Radius sudut untuk elemen bertingkat dalam widget (misalnya, kolom input, gambar) | 16px |
| --chat-messenger-shape--corner-value-large | Radius sudut untuk penampung bertingkat dalam widget (misalnya, kartu carousel, kartu tindakan cepat) | 20px |
| --chat-messenger-shape--corner-value-extra-large | Radius sudut untuk jendela chat utama dan penampung widget. | 28px |
| --chat-messenger-shape--corner-fully-rounded | Digunakan untuk tombol dan elemen interaktif berbentuk pil untuk memastikan ujung yang sepenuhnya melingkar. | 100px |
| --chat-messenger-elevation | Box-shadow diterapkan ke elemen mengambang dan komponen chat utama. | 0 1px 2px 0 rgba(0,0,0,0.3), 0 2px 6px 2px rgba(0,0,0,0.15) |
Token Tipografi
Token ini menentukan jenis huruf dan skala spesifik (ukuran, ketebalan, jarak) yang digunakan di seluruh antarmuka.
| Properti | Maksud Penggunaan | Default |
|---|---|---|
| --chat-messenger-font-family | Jenis font utama | Google Sans |
| Title large | Header yang terlihat jelas | |
| --chat-messenger-typescale--title-large-font-size | 18px | |
| --chat-messenger-typescale--title-large-font-weight | 400 | |
| --chat-messenger-typescale--title-large-line-height | 24px | |
| --chat-messenger-typescale--title-large-letter-spacing | 0 | |
| Media judul | Header bagian dalam widget. | |
| --chat-messenger-typescale--title-medium-font-size | 16px | |
| --chat-messenger-typescale--title-medium-font-weight | 500 | |
| --chat-messenger-typescale--title-medium-line-height | 24px | |
| --chat-messenger-typescale--title-medium-letter-spacing | 0 | |
| Title small | ||
| --chat-messenger-typescale--title-small-font-size | Sub-header atau judul dalam kartu yang lebih kecil. | 14px |
| --chat-messenger-typescale--title-small-font-weight | 500 | |
| --chat-messenger-typescale--title-small-line-height | 20px | |
| --chat-messenger-typescale--title-small-letter-spacing | 0 | |
| Body large | Deskripsi panjang. | |
| --chat-messenger-typescale--body-large-font-size | 16px | |
| --chat-messenger-typescale--body-large-font-weight | 400 | |
| --chat-messenger-typescale--body-large-line-height | 24px | |
| --chat-messenger-typescale--body-large-letter-spacing | 0 | |
| Body medium | Teks UI standar | |
| --chat-messenger-typescale--body-medium-font-size | 14px | |
| --chat-messenger-typescale--body-medium-font-weight | 400 | |
| --chat-messenger-typescale--body-medium-line-height | 20px | |
| --chat-messenger-typescale--body-medium-letter-spacing | 0 | |
| Body small | Deskripsi dan metadata sekunder. | |
| --chat-messenger-typescale--body-small-font-size | 12px | |
| --chat-messenger-typescale--body-small-font-weight | 400 | |
| --chat-messenger-typescale--body-small-line-height | 16px | |
| --chat-messenger-typescale--body-small-letter-spacing | 0,1 | |
| Label besar | Teks dalam tombol dan chip tindakan utama. | |
| --chat-messenger-typescale--label-large-font-size | 14px | |
| --chat-messenger-typescale--label-large-font-weight | 500 | |
| --chat-messenger-typescale--label-large-line-height | 20px | |
| --chat-messenger-typescale--label-large-letter-spacing | 0 | |
| Label media | Teks tombol sekunder dan label kolom | |
| --chat-messenger-typescale--label-medium-font-size | 12px | |
| --chat-messenger-typescale--label-medium-font-weight | 500 | |
| --chat-messenger-typescale--label-medium-line-height | 16px | |
| --chat-messenger-typescale--label-medium-letter-spacing | 0,1 | |
| Label kecil | Label mikro dan teks badge | |
| --chat-messenger-typescale--label-small-font-size | 11px | |
| --chat-messenger-typescale--label-small-font-weight | 500 | |
| --chat-messenger-typescale--label-small-line-height | 16px | |
| --chat-messenger-typescale--label-small-letter-spacing | 0,1 |
Token Spasi
Token ini mempertahankan kepadatan tata letak yang konsisten, menentukan margin, padding, dan celah di antara elemen.
| Properti | Default |
|---|---|
| --chat-messenger-spacing--half | 4px |
| --chat-messenger-spacing--one | 8px |
| --chat-messenger-spacing--one-and-half | 12px |
| --chat-messenger-spacing--two | 16px |
| --chat-messenger-spacing--two-and-half | 20px |
| --chat-messenger-spacing--three | 24px |
| --chat-messenger-spacing--three-and-half | 28px |
| --chat-messenger-spacing--four | 32px |
Peristiwa JavaScript
Messenger memicu berbagai peristiwa yang dapat Anda buat
pemroses peristiwanya.
Target peristiwa untuk peristiwa ini adalah elemen chat-messenger.
Untuk menambahkan pemroses peristiwa untuk elemen chat-messenger,
tambahkan kode JavaScript berikut,
dengan event-type adalah salah satu nama peristiwa yang dijelaskan di bagian ini
const chatMessenger = document.querySelector('chat-messenger');
chatMessenger.addEventListener('event-type', function (event) {
// Handle event
...
});
Jenis peristiwa berikut didukung:
chat-messenger-loaded: Peristiwa ini dipicu saat elemenchat-messengerdimuat dan diinisialisasi sepenuhnya.chat-messenger-closechat-messenger-error: Peristiwa ini terjadi saat agen CES mengirim kode status error. Struktur peristiwa akan terlihat seperti berikuteventId= `chat-messenger-error-v2` event.details { message: string; code: number | undefined; status: number | string; }df-update-cart-count: Peristiwa ini terjadi saat "Tambahkan ke keranjang", "Sesuaikan jumlah item", "Hapus item" terjadi di elemen konten multimediaproduct_carousel,product_detail,product_comparison. Struktur peristiwa akan terlihat seperti berikut{ "detail": { "count": <cart_item_count>, } }
Fungsi JavaScript
Elemen chat-messenger menyediakan
fungsi
yang dapat Anda panggil untuk memengaruhi perilakunya.
renderCustomEvent
Fungsi ini merender pesan teks, seolah-olah berasal dari aplikasi agen sebagai respons teks.
Contoh:
const chatMessenger = document.querySelector('chat-messenger');
chatMessenger.renderCustomText('Custom text');
renderCustomCard
Fungsi ini merender kartu kustom, seolah-olah berasal dari aplikasi agen sebagai pesan respons multimedia. Format respons payload kustom ditentukan di bagian Pesan respons multimedia.
Contoh:
const chatMessenger = document.querySelector('chat-messenger');
const payload = [
{
"type": "info",
"title": "Info item title",
"subtitle": "Info item subtitle",
"image": {
"src": {
"rawUrl": "https://example.com/images/logo.png"
}
},
"actionLink": "https://example.com"
}];
chatMessenger.renderCustomCard(payload);
Mengonfigurasi autentikasi
Semua permintaan API yang dibuat oleh widget web ke layanan backend Google harus diautentikasi. Hal ini dilakukan menggunakan token akses OAuth 2.0 berumur pendek.
Identitas yang terkait dengan token ini, baik itu pengguna akhir maupun akun layanan, harus memiliki izin IAM yang diperlukan untuk berinteraksi dengan agen.
Subbagian lainnya menjelaskan cara Anda dapat menyiapkan autentikasi.
Menyiapkan broker token
Broker token adalah layanan web yang berjalan di project Google Cloud Anda dan membuat token akses atas nama akun layanan yang Anda miliki. Widget web dapat otomatis memanggil URL untuk broker token Anda di awal percakapan untuk mendapatkan token baru yang akan digunakan saat berkomunikasi dengan CX Agent Studio API.
Anda dapat menyiapkan broker token dengan dua cara: dihosting Google atau dihosting sendiri.
Dihosting Google
Gunakan broker token yang disediakan oleh Google untuk mengizinkan akses publik ke widget chat Anda:
- Saat membuat konfigurasi widget dan deployment, aktifkan akses publik, dan secara opsional aktifkan pemeriksaan origin dan reCAPTCHA (direkomendasikan untuk mencegah spoofing dan penyalahgunaan).
- Widget chat akan meminta token cakupan sesi dari broker token yang disediakan Google dan menggunakannya untuk sesi chat.
Dihosting sendiri
Ikuti langkah-langkah berikut untuk menyiapkan broker token yang dihosting sendiri:
- Buat akun layanan di project Anda dan berikan peran Customer Engagement Suite Client untuk akun layanan tersebut.
- Deploy fungsi Cloud Run Functions dengan kode contoh broker token yang kami berikan.
Lihat petunjuk langkah demi langkah yang mendetail di repositori open source.
Menyiapkan OAuth2
Klien OAuth2 memungkinkan widget web memulai alur autentikasi untuk pengguna akhir. Biasanya, hal ini berarti jendela dialog dibuka, tempat pengguna login ke Akun Google-nya (atau penyedia lainnya) dan widget web menerima token untuk beroperasi atas nama pengguna.
Pilih opsi ini untuk mewajibkan pengguna akhir login sebelum menggunakan agen, dengan kredensial pengguna digunakan untuk mengakses aplikasi agen.
Berikut langkah-langkah utama yang perlu Anda ikuti:
- Di konsol Google Cloud , buka Google Auth Platform, lalu pilih Klien.
- Klik Buat Klien.
- Pilih Web application sebagai jenis klien.
- Masukkan nama untuk klien baru Anda.
- Tambahkan URL situs Anda ke Authorized JavaScript origins dan Authorized Redirect URIs.
- Klik Create dan tunggu 5 menit sebelum melanjutkan.
Setelah mengikuti langkah-langkahnya, Anda akan mendapatkan client ID dalam bentuk:
123456789012-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com
Berikan ini
di atribut oauth-client-id komponen web chat-messenger.
Membangun API autentikasi Anda sendiri
Buat API Anda sendiri untuk menangani autentikasi dan otorisasi pengguna akhir yang menampilkan token akses Google atau JWT yang ditandatangani yang memiliki izin untuk memanggil runSession di aplikasi Anda.
Untuk mengetahui informasi tentang penggunaan CX Agent Studio API, lihat Akses API.