Untuk menyampaikan informasi ke aplikasi web, Anda harus mengirim respons Canvas
dari logika percakapan Anda. Respons Canvas
dapat melakukan salah satu hal berikut:
- Merender aplikasi web layar penuh di perangkat pengguna
- Meneruskan data untuk mengupdate aplikasi web
Bagian berikut menjelaskan cara menampilkan respons Canvas untuk setiap skenario.
Mengaktifkan Canvas Interaktif
Anda harus mengonfigurasi Action dengan cara tertentu untuk menggunakan Canvas Interaktif.
Pembuatan Action yang menggunakan Canvas Interaktif memerlukan konfigurasi
tambahan di konsol Actions (dan, untuk Actions SDK, modifikasi pada
file settings.yaml
Anda). Untuk melihat prosedur lengkap dalam membuat dan
mengonfigurasi Action Canvas Interaktif dengan Actions SDK, lihat
Membuat project.
Saat menggunakan Action Builder, ikuti langkah-langkah tambahan berikut untuk mengaktifkan Canvas Interaktif:
- Jika Anda tidak memilih kartu Game di layar What type of Action do you want to build?, klik Deploy di navigasi atas. Di bagian Informasi Tambahan, pilih kategori Game & hiburan. Klik Simpan.
- Klik Develop di navigasi atas konsol Actions.
- Klik Interactive Canvas di navigasi kiri.
- Di bagian Do you want your Action to use Interactive Canvas?, pilih salah satu
dari opsi berikut:
- Mengaktifkan Canvas Interaktif dengan fulfillment webhook server. Opsi ini
mengandalkan webhook untuk mengakses fitur tertentu, dan sering kali menggunakan
onUpdate()
untuk meneruskan data ke aplikasi web. Jika diaktifkan, kecocokan intent akan ditangani dalam scene, dan Anda dapat memilih untuk memanggil webhook sebelum bertransisi ke scene lain atau mengakhiri percakapan. - Aktifkan Canvas Interaktif dengan fulfillment klien. Opsi ini memungkinkan
Anda memindahkan logika fulfillment webhook ke aplikasi web, dan membatasi
panggilan webhook hanya ke fitur percakapan yang memerlukannya,
seperti penautan akun. Jika diaktifkan, Anda dapat menggunakan
expect()
untuk mendaftarkan pengendali intent di sisi klien.
- Mengaktifkan Canvas Interaktif dengan fulfillment webhook server. Opsi ini
mengandalkan webhook untuk mengakses fitur tertentu, dan sering kali menggunakan
- Opsional: Masukkan URL aplikasi web ke kolom Setel URL aplikasi web default. Tindakan ini akan menambahkan respons
Canvas
default dengan kolom URL ke pemanggilan Utama Anda. - Klik Simpan.
Saat menggunakan Actions SDK, ikuti langkah-langkah tambahan berikut untuk mengaktifkan Kanvas Interaktif:
- Tetapkan kolom
category
di filesettings.yaml
keGAMES_AND_TRIVIA
untuk mendeskripsikan dan membantu pengguna menemukan Action Anda dengan tepat. - Tetapkan kolom
usesInteractiveCanvas
di filesettings.yaml
Anda ketrue
.
Memeriksa kemampuan platform
Framework Canvas Interaktif hanya berjalan di perangkat Asisten yang menyediakan
antarmuka visual, sehingga Action Anda perlu memeriksa
kemampuan INTERACTIVE_CANVAS
di perangkat pengguna. Saat menentukan perintah di Action Builder,
Anda dapat menentukan daftar kemampuan perangkat di kolom selector
dari
objek candidates
. Pemilih perintah memilih kandidat perintah yang paling
sesuai dengan kemampuan perangkat pengguna.
Untuk menampilkan respons Canvas
, logika Action Anda harus melakukan hal berikut:
- Pastikan perangkat pengguna mendukung kemampuan
INTERACTIVE_CANVAS
. Jika ya, kirim responsCanvas
kepada pengguna. - Jika kemampuan Canvas Interaktif tidak tersedia, periksa apakah perangkat pengguna
mendukung kemampuan
RICH_RESPONSE
. Jika ya, kirim pengguna respons kaya sebagai gantinya. - Jika kemampuan respons lengkap tidak tersedia, kirim respons sederhana kepada pengguna.
Cuplikan berikut menampilkan respons yang sesuai berdasarkan kemampuan perangkat pengguna:
YAML
candidates: - selector: surface_capabilities: capabilities: - INTERACTIVE_CANVAS canvas: url: 'https://example.web.app' - selector: surface_capabilities: capabilities: - RICH_RESPONSE content: card: title: Card title text: Card Content image: url: 'https://example.com/image.png' alt: Alt text button: name: Link name open: url: 'https://example.com/' - first_simple: variants: - speech: Example simple response.
JSON
{ "candidates": [ { "selector": { "surface_capabilities": { "capabilities": [ "INTERACTIVE_CANVAS" ] } }, "canvas": { "url": "https://example.web.app" } }, { "selector": { "surface_capabilities": { "capabilities": [ "RICH_RESPONSE" ] } }, "content": { "card": { "title": "Card title", "text": "Card Content", "image": { "url": "https://example.com/image.png", "alt": "Alt text" }, "button": { "name": "Link name", "open": { "url": "https://example.com/" } } } } }, { "first_simple": { "variants": [ { "speech": "Example simple response." } ] } } ] }
Node.js
const supportsRichResponse = conv.device.capabilities.includes("RICH_RESPONSE"); const supportsInteractiveCanvas = conv.device.capabilities.includes("INTERACTIVE_CANVAS"); if (supportsInteractiveCanvas) { // Respond with a Canvas response conv.add(new Canvas({ url: 'https://example.web.app', })); } else if (supportsRichResponse) { // Respond with a rich response conv.add(new Card({ title: 'Card title', image: new Image({ url: 'https://example.com/image.png', alt: 'Alt text', }), button: new Link({ name: 'Link name', open: { url: 'https://example.com/', }, }), })); } else { // Respond with a simple response conv.add('Example simple response.'); }
Render aplikasi web
Action yang menggunakan Canvas Interaktif menyertakan aplikasi web dengan visual yang disesuaikan yang Anda kirim ke pengguna sebagai respons. Setelah aplikasi web dirender, pengguna akan terus berinteraksi dengan aplikasi melalui suara, teks, atau sentuhan hingga percakapan berakhir.
Respons Canvas
pertama Anda harus berisi URL aplikasi web. Jenis
respons Canvas
ini memberi tahu Asisten Google untuk merender aplikasi web di alamat tersebut
di perangkat pengguna. Biasanya, Anda mengirim respons Canvas
pertama
segera setelah pengguna memanggil Action. Saat aplikasi web dimuat, library Canvas Interaktif dimuat, dan aplikasi web mendaftarkan pengendali callback
dengan Interactive Canvas API.
Anda dapat menentukan URL aplikasi web di Action Builder, seperti yang ditunjukkan pada screenshot berikut:
Jika Anda membuat perintah yang menyertakan respons Canvas
setelah menentukan
URL aplikasi web, Action Builder akan otomatis mengisi kolom URL respons Canvas
. Untuk informasi
selengkapnya tentang cara menetapkan URL aplikasi web di konsol, lihat bagian
Mengaktifkan Canvas Interaktif.
Cuplikan berikut menunjukkan cara membuat respons Canvas
yang merender
aplikasi web di Action Builder dan webhook Anda:
YAML
candidates: - first_simple: variants: - speech: >- Welcome! Do you want me to change color or pause spinning? You can also tell me to ask you later. canvas: url: 'https://your-web-app.com'
JSON
{ "candidates": [ { "first_simple": { "variants": [ { "speech": "Welcome! Do you want me to change color or pause spinning? You can also tell me to ask you later." } ] }, "canvas": { "url": "https://your-web-app.com" } } ] }
Node.js
app.handle('welcome', (conv) => { conv.add('Welcome! Do you want me to change color or pause spinning? ' + 'You can also tell me to ask you later.'); conv.add(new Canvas({ url: `https://your-web-app.com`, })); });
JSON
{ "session": { "id": "session_id", "params": {} }, "prompt": { "override": false, "firstSimple": { "speech": "Welcome! Do you want me to change color or pause spinning? You can also tell me to ask you later.", "text": "Welcome! Do you want me to change color or pause spinning? You can also tell me to ask you later." }, "canvas": { "data": [], "suppressMic": false, "url": "https://your-web-app.com" } } }
Meneruskan data untuk mengupdate aplikasi web
Setelah mengirim respons Canvas
awal, Anda dapat menggunakan respons Canvas
tambahan untuk memberikan update ke data
, yang digunakan logika kustom aplikasi web
untuk membuat perubahan pada aplikasi web Anda. Saat Anda mengirim respons Canvas
yang meneruskan
data ke aplikasi web, langkah-langkah berikut akan terjadi:
- Saat dicocokkan dalam scene, intent akan memicu peristiwa, dan respons
Canvas
yang berisi kolomdata
dengan payload JSON akan dikirim kembali sebagai respons. - Kolom
data
diteruskan ke callbackonUpdate
dan digunakan untuk mengupdate aplikasi web. Action Percakapan Anda dapat mengirim respons
Canvas
baru dan memberikan informasi di kolomdata
untuk mengirim update baru atau memuat status baru.
Anda dapat meneruskan data ke aplikasi web dengan dua cara:
- Dengan Action Builder. Action Builder otomatis mengisi kolom
data
di responsCanvas
dengan metadata yang diperlukan untuk memperbarui aplikasi web. - Dengan webhook. Jika memiliki webhook, Anda dapat mengonfigurasi payload data kustom untuk mengupdate aplikasi web di respons
Canvas
.
Bagian berikut menjelaskan cara meneruskan data melalui Action Builder dan melalui webhook.
Menggunakan Action Builder untuk meneruskan data
Dengan Action Builder, Anda tidak perlu menentukan webhook untuk mengelola metadata
yang dikirim ke aplikasi web Anda. Sebagai gantinya, saat mengonfigurasi pengendali intent di
UI Action Builder, Anda dapat menyertakan respons Canvas
. Kolom
data
secara otomatis diisi dengan metadata yang diperlukan untuk mengupdate
aplikasi web Anda, seperti nama intent, parameter apa pun yang diambil dari input pengguna,
dan scene saat ini.
Misalnya, pengendali intent Guess
berikut menunjukkan bahwa Anda ingin menyertakan respons
Canvas
:
YAML
candidates: - canvas: send_state_data_to_canvas_app: true
JSON
{ "candidates": [ { "canvas": { "send_state_data_to_canvas_app": true } } ] }
Secara opsional, Anda dapat menambahkan cuplikan berikut ke pengendali intent untuk mengirim pesan TTS:
...
- first_simple:
variants:
- speech: Optional message.
Action Builder secara otomatis memperluas respons Canvas
dengan metadata untuk
mengupdate aplikasi web, seperti ditunjukkan dalam cuplikan berikut. Dalam hal ini, pengguna
menebak huruf "a" dalam game tebak kata:
YAML
candidates: - canvas: data: - google: intent: params: letter: resolved: a original: a name: guess scene: Game sendStateDataToCanvasApp: true
JSON
{ "candidates": [ { "canvas": { "data": [ { "google": { "intent": { "params": { "letter": { "resolved": "a", "original": "a" } }, "name": "guess" }, "scene": "Game" } } ], "sendStateDataToCanvasApp": true } } ] }
Respons ini memperbarui aplikasi web Anda dengan jawaban pengguna dan bertransisi ke adegan yang sesuai.
Menggunakan webhook untuk meneruskan data
Anda dapat mengonfigurasi kolom data
dari respons Canvas
secara manual di webhook dengan informasi status yang diperlukan untuk mengupdate aplikasi web. Pendekatan ini direkomendasikan jika Anda perlu menyertakan payload data
kustom dalam respons Canvas
, bukan hanya meneruskan metadata standar yang diperlukan untuk mengupdate aplikasi web.
Cuplikan berikut menunjukkan cara meneruskan data dalam respons Canvas
di
webhook Anda:
Node.js
app.handle('start_spin', (conv) => { conv.add(`Ok, I'm spinning. What else?`); conv.add(new Canvas({ data: { command: 'SPIN', spin: true, }, })); });
JSON
{ "session": { "id": "session_id", "params": {} }, "prompt": { "override": false, "firstSimple": { "speech": "Ok, I'm spinning. What else?", "text": "Ok, I'm spinning. What else?" }, "canvas": { "data": { "command": "SPIN", "spin": true }, "suppressMic": false, "url": "" } } }
Panduan dan pembatasan
Perhatikan panduan dan pembatasan berikut untuk respons Canvas
saat membuat Action Anda:
- Setiap pengendali webhook dalam fulfillment Anda harus menyertakan
Canvas
. Jika respons webhook tidak menyertakanCanvas
, aplikasi web Anda akan ditutup. - Anda hanya perlu menyertakan URL aplikasi web dalam respons
Canvas
pertama yang dikirim ke pengguna. - URL respons
Canvas
harus valid dan protokolnya harus https. - Respons
Canvas
harus berukuran 50 KB atau lebih kecil.