หากต้องการส่งต่อข้อมูลไปยังเว็บแอป คุณต้องส่งการตอบกลับ Canvas
จากตรรกะแบบการสนทนา การตอบกลับ Canvas
สามารถทำอย่างใดอย่างหนึ่งต่อไปนี้
- แสดงผลเว็บแอปแบบเต็มหน้าจอในอุปกรณ์ของผู้ใช้
- ส่งข้อมูลเพื่ออัปเดตเว็บแอป
ส่วนต่อไปนี้อธิบายวิธีส่งคืนคำตอบของ Canvas สำหรับแต่ละสถานการณ์
เปิดใช้ Interactive Canvas
คุณต้องกำหนดค่าการดำเนินการของคุณด้วยวิธีการที่เฉพาะเจาะจงเพื่อใช้ Canvas แบบอินเทอร์แอกทีฟ
การสร้าง Action ที่ใช้ Interactive Canvas ต้องมีการกำหนดค่าเพิ่มเติมในคอนโซล Actions (และการแก้ไขไฟล์ settings.yaml
สำหรับ Actions SDK นั้น) ดูขั้นตอนทั้งหมดสำหรับการสร้างและการกำหนดค่า Canvas แบบอินเทอร์แอกทีฟด้วย Actions SDK ได้ที่สร้างโปรเจ็กต์
เมื่อใช้ Actions Builder ให้ทำตามขั้นตอนเพิ่มเติมต่อไปนี้เพื่อเปิดใช้ Interactive Canvas
- หากไม่ได้เลือกการ์ดเกมบนหน้าจอคุณต้องการสร้างการดำเนินการประเภทใด ให้คลิกทำให้ใช้งานได้ในการนำทางด้านบน ในส่วนข้อมูลเพิ่มเติม ให้เลือกหมวดหมู่เกมและความสนุก คลิกบันทึก
- คลิกพัฒนาในการนำทางด้านบนของคอนโซล Actions
- คลิก Interactive Canvas ในการนำทางด้านซ้าย
- ในส่วน คุณต้องการให้การดำเนินการของคุณใช้ Interactive Canvas หรือไม่ ให้เลือกรายการใดรายการหนึ่งต่อไปนี้
- เปิดใช้ Interactive Canvas ที่มี Fulfillment เว็บฮุคของเซิร์ฟเวอร์ ตัวเลือกนี้ต้องใช้เว็บฮุคเพื่อเข้าถึงฟีเจอร์บางอย่าง และมักจะใช้
onUpdate()
เพื่อส่งข้อมูลไปยังเว็บแอป เมื่อเปิดใช้แล้ว ระบบจะจัดการการจับคู่ Intent ในฉากและคุณสามารถเลือกเรียกใช้เว็บฮุคก่อนเปลี่ยนไปดูฉากอื่นหรือสิ้นสุดการสนทนาได้ - เปิดใช้ Interactive Canvas ที่มี Fulfillment ของไคลเอ็นต์ ตัวเลือกนี้ช่วยให้คุณย้ายตรรกะ Fulfillment เว็บฮุคไปยังเว็บแอปได้ และจำกัดการเรียกใช้เว็บฮุคไว้ที่ฟีเจอร์การสนทนาที่จำเป็นต้องใช้เท่านั้น เช่น การลิงก์บัญชี เมื่อเปิดใช้ คุณจะใช้
expect()
เพื่อลงทะเบียนเครื่องจัดการ Intent ในฝั่งไคลเอ็นต์ได้
- เปิดใช้ Interactive Canvas ที่มี Fulfillment เว็บฮุคของเซิร์ฟเวอร์ ตัวเลือกนี้ต้องใช้เว็บฮุคเพื่อเข้าถึงฟีเจอร์บางอย่าง และมักจะใช้
- ไม่บังคับ: ป้อน URL ของเว็บแอปลงในช่องตั้งค่า URL ของเว็บแอปเริ่มต้น การดำเนินการนี้จะเพิ่มการตอบสนอง
Canvas
เริ่มต้นพร้อมช่อง URL ไปยังการเรียกใช้หลัก - คลิกบันทึก
เมื่อใช้ Actions SDK ให้ทำตามขั้นตอนเพิ่มเติมต่อไปนี้เพื่อเปิดใช้ Interactive Canvas
- ตั้งค่าช่อง
category
ในไฟล์settings.yaml
เป็นGAMES_AND_TRIVIA
เพื่ออธิบายและช่วยให้ผู้ใช้ค้นพบการดำเนินการของคุณได้ดีที่สุด - ตั้งค่าช่อง
usesInteractiveCanvas
ในไฟล์settings.yaml
เป็นtrue
ตรวจสอบความสามารถของพื้นผิว
เฟรมเวิร์ก Interactive Canvas ทำงานในอุปกรณ์ Assistant ที่มีอินเทอร์เฟซแบบภาพเท่านั้น การดำเนินการของคุณจึงต้องตรวจสอบINTERACTIVE_CANVAS
ความสามารถในอุปกรณ์ของผู้ใช้ เมื่อกำหนดพรอมต์ใน Actions Builder คุณจะระบุรายการความสามารถของอุปกรณ์ในช่อง selector
ของออบเจ็กต์ candidates
ได้ ตัวเลือกพรอมต์จะเลือกข้อความแจ้งที่เหมาะกับความสามารถของอุปกรณ์ของผู้ใช้มากที่สุด
หากต้องการให้มีการตอบสนองด้วย Canvas
ตรรกะของการดำเนินการของคุณควรมีลักษณะดังต่อไปนี้
- ตรวจสอบว่าอุปกรณ์ของผู้ใช้รองรับความสามารถ
INTERACTIVE_CANVAS
หากใช่ ให้ส่งการตอบกลับCanvas
ให้แก่ผู้ใช้ - หากความสามารถของ Interactive Canvas ไม่พร้อมใช้งาน โปรดตรวจสอบว่าอุปกรณ์ของผู้ใช้รองรับความสามารถ
RICH_RESPONSE
หรือไม่ หากใช่ ให้ส่งการตอบกลับที่สมบูรณ์ให้ผู้ใช้แทน - หากไม่สามารถตอบกลับด้วยริชมีเดียได้ ให้ส่งคำตอบง่ายๆ ให้แก่ผู้ใช้
ข้อมูลโค้ดต่อไปนี้จะแสดงการตอบสนองที่เหมาะสมตามความสามารถของอุปกรณ์ของผู้ใช้
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.'); }
แสดงผลเว็บแอป
การดำเนินการที่ใช้ Interactive Canvas จะมีเว็บแอปที่มีภาพที่กำหนดเองซึ่งคุณส่งให้ผู้ใช้เป็นคำตอบ เมื่อเว็บแอปแสดงผลแล้ว ผู้ใช้จะยังคงโต้ตอบกับแอปผ่านเสียง ข้อความ หรือแตะ จนกว่าการสนทนาจะสิ้นสุดลง
การตอบกลับ Canvas
แรกของคุณต้องมี URL ของเว็บแอป ซึ่งการตอบกลับ Canvas
ประเภทนี้จะบอกให้ Google Assistant แสดงผลเว็บแอปตามที่อยู่นั้นในอุปกรณ์ของผู้ใช้ โดยปกติแล้ว คุณจะส่งการตอบกลับ Canvas
แรกทันทีหลังจากผู้ใช้เรียกใช้การดำเนินการของคุณ เมื่อเว็บแอปโหลดขึ้น ไลบรารี Interactive Canvas จะโหลดขึ้น และเว็บแอปจะลงทะเบียนเครื่องจัดการโค้ดเรียกกลับด้วย Interactive Canvas API
คุณระบุ URL ของเว็บแอปใน Actions Builder ได้ดังที่แสดงในภาพหน้าจอต่อไปนี้
หากสร้างพรอมต์ที่มีการตอบกลับ Canvas
หลังจากระบุ URL ของเว็บแอปแล้ว Actions Builder จะเติมช่อง URL ของการตอบกลับ Canvas
โดยอัตโนมัติ สำหรับข้อมูลเพิ่มเติมเกี่ยวกับการตั้งค่า URL ของเว็บแอปในคอนโซล ให้ดูที่ส่วนเปิดใช้ Canvas แบบอินเทอร์แอกทีฟ
ข้อมูลโค้ดต่อไปนี้แสดงวิธีสร้างการตอบสนองของ Canvas
ที่แสดงผลเว็บแอปทั้งใน Actions Builder และเว็บฮุค
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" } } }
ส่งข้อมูลเพื่ออัปเดตเว็บแอป
หลังจากส่งการตอบกลับ Canvas
ครั้งแรกแล้ว คุณจะใช้การตอบกลับ Canvas
เพิ่มเติมเพื่อให้อัปเดตกับ data
ได้ ซึ่งตรรกะที่กำหนดเองของเว็บแอปจะใช้เพื่อทำการเปลี่ยนแปลงเว็บแอป เมื่อส่งการตอบกลับ Canvas
ซึ่งส่งผ่านข้อมูลไปยังเว็บแอป จะเกิดขั้นตอนต่อไปนี้
- เมื่อจับคู่ Intent ภายในโหมด ระบบจะเรียกเหตุการณ์ให้แสดง และการตอบสนอง
Canvas
ที่มีช่องdata
ที่มีเพย์โหลด JSON จะถูกส่งกลับมาเป็นการตอบสนอง - ระบบจะส่งช่อง
data
ไปยังโค้ดเรียกกลับonUpdate
และใช้เพื่ออัปเดตเว็บแอป การดำเนินการแบบการสนทนาจะส่งการตอบกลับ
Canvas
ใหม่และให้ข้อมูลในช่องdata
เพื่อส่งข้อมูลอัปเดตใหม่หรือโหลดสถานะใหม่ได้
คุณส่งข้อมูลไปยังเว็บแอปได้ 2 วิธี ดังนี้
- ด้วย Actions Builder Actions Builder จะป้อนข้อมูลช่อง
data
โดยอัตโนมัติในการตอบกลับCanvas
พร้อมข้อมูลเมตาที่จําเป็นในการอัปเดตเว็บแอป - มีเว็บฮุค หากมีเว็บฮุค คุณกำหนดค่าเพย์โหลดข้อมูลที่กำหนดเองเพื่ออัปเดตเว็บแอปในการตอบกลับจาก
Canvas
ได้
ส่วนต่อไปนี้อธิบายวิธีส่งข้อมูลผ่าน Actions Builder และเว็บฮุค
ใช้ Actions Builder เพื่อส่งข้อมูล
เมื่อใช้ Actions Builder คุณไม่จำเป็นต้องกำหนดเว็บฮุคเพื่อจัดการข้อมูลเมตาที่ส่งไปยังเว็บแอป แต่เมื่อคุณกำหนดค่าตัวแฮนเดิล Intent ใน UI ของ Actions Builder คุณจะใส่การตอบกลับ Canvas
ได้ ระบบจะป้อนข้อมูลในช่อง data
โดยอัตโนมัติพร้อมด้วยข้อมูลเมตาที่จำเป็นเพื่ออัปเดตเว็บแอป เช่น ชื่อ Intent, พารามิเตอร์ที่บันทึกจากอินพุตของผู้ใช้ และโหมดปัจจุบัน
ตัวอย่างเช่น เครื่องจัดการ Intent Guess
ต่อไปนี้บ่งชี้ว่าคุณต้องการรวมการตอบกลับ Canvas
YAML
candidates: - canvas: send_state_data_to_canvas_app: true
JSON
{ "candidates": [ { "canvas": { "send_state_data_to_canvas_app": true } } ] }
คุณจะเพิ่มข้อมูลโค้ดต่อไปนี้ลงในเครื่องจัดการ Intent เพื่อส่งข้อความ TTS หรือไม่ก็ได้
...
- first_simple:
variants:
- speech: Optional message.
Actions Builder จะขยายการตอบกลับ Canvas
ที่มีข้อมูลเมตาโดยอัตโนมัติเพื่ออัปเดตเว็บแอปดังที่แสดงในข้อมูลโค้ดต่อไปนี้ ในกรณีนี้ ผู้ใช้เดาตัวอักษร "a" ในเกมเดาคำ
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 } } ] }
คำตอบนี้จะอัปเดตเว็บแอปด้วยคำตอบของผู้ใช้ แล้วเปลี่ยนไปเป็นฉากที่เหมาะสม
ใช้เว็บฮุคเพื่อส่งข้อมูล
คุณกำหนดค่าช่อง data
ของการตอบกลับ Canvas
ในเว็บฮุคด้วยตนเองด้วยข้อมูลสถานะที่จำเป็นเพื่ออัปเดตเว็บแอปได้ เราแนะนำให้ใช้วิธีนี้ในกรณีที่คุณต้องรวมเพย์โหลด data
ที่กำหนดเองในการตอบกลับ Canvas
แทนการส่งผ่านข้อมูลเมตาทั่วไปที่จำเป็นสำหรับการอัปเดตเว็บแอปเท่านั้น
ข้อมูลโค้ดต่อไปนี้แสดงวิธีส่งข้อมูลในการตอบกลับด้วย Canvas
ในเว็บฮุค
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": "" } } }
หลักเกณฑ์และข้อจำกัด
โปรดคำนึงถึงหลักเกณฑ์และข้อจำกัดต่อไปนี้สำหรับคำตอบ Canvas
เมื่อสร้างการดำเนินการ
- เครื่องจัดการเว็บฮุคแต่ละรายการใน Fulfillment ต้องมี
Canvas
หากการตอบสนองของเว็บฮุคไม่รวมCanvas
ระบบจะปิดเว็บแอป - คุณเพียงต้องใส่ URL ของเว็บแอปในการตอบกลับ
Canvas
แรกที่คุณส่งให้ผู้ใช้ - URL การตอบสนองของ
Canvas
ควรถูกต้องและโปรโตคอลต้องเป็น https - การตอบกลับ
Canvas
ต้องมีขนาดไม่เกิน 50 KB