พรอมต์สำหรับภาพพิมพ์แคนวาส

หากต้องการส่งต่อข้อมูลไปยังเว็บแอป คุณต้องส่งการตอบกลับ Canvas จากตรรกะแบบการสนทนา การตอบกลับ Canvas สามารถทำอย่างใดอย่างหนึ่งต่อไปนี้

• แสดงผลเว็บแอปแบบเต็มหน้าจอในอุปกรณ์ของผู้ใช้
• ส่งข้อมูลเพื่ออัปเดตเว็บแอป

ส่วนต่อไปนี้อธิบายวิธีส่งคืนคำตอบของ Canvas สำหรับแต่ละสถานการณ์

เปิดใช้ Interactive Canvas

คุณต้องกำหนดค่าการดำเนินการของคุณด้วยวิธีการที่เฉพาะเจาะจงเพื่อใช้ Canvas แบบอินเทอร์แอกทีฟ การสร้าง Action ที่ใช้ Interactive Canvas ต้องมีการกำหนดค่าเพิ่มเติมในคอนโซล Actions (และการแก้ไขไฟล์ settings.yaml สำหรับ Actions SDK นั้น) ดูขั้นตอนทั้งหมดสำหรับการสร้างและการกำหนดค่า Canvas แบบอินเทอร์แอกทีฟด้วย Actions SDK ได้ที่สร้างโปรเจ็กต์

เมื่อใช้ Actions Builder ให้ทำตามขั้นตอนเพิ่มเติมต่อไปนี้เพื่อเปิดใช้ Interactive Canvas

1. หากไม่ได้เลือกการ์ดเกมบนหน้าจอคุณต้องการสร้างการดำเนินการประเภทใด ให้คลิกทำให้ใช้งานได้ในการนำทางด้านบน ในส่วนข้อมูลเพิ่มเติม ให้เลือกหมวดหมู่เกมและความสนุก คลิกบันทึก
2. คลิกพัฒนาในการนำทางด้านบนของคอนโซล Actions
3. คลิก Interactive Canvas ในการนำทางด้านซ้าย
4. ในส่วน คุณต้องการให้การดำเนินการของคุณใช้ Interactive Canvas หรือไม่ ให้เลือกรายการใดรายการหนึ่งต่อไปนี้
   • เปิดใช้ Interactive Canvas ที่มี Fulfillment เว็บฮุคของเซิร์ฟเวอร์ ตัวเลือกนี้ต้องใช้เว็บฮุคเพื่อเข้าถึงฟีเจอร์บางอย่าง และมักจะใช้ onUpdate() เพื่อส่งข้อมูลไปยังเว็บแอป เมื่อเปิดใช้แล้ว ระบบจะจัดการการจับคู่ Intent ในฉากและคุณสามารถเลือกเรียกใช้เว็บฮุคก่อนเปลี่ยนไปดูฉากอื่นหรือสิ้นสุดการสนทนาได้
   • เปิดใช้ Interactive Canvas ที่มี Fulfillment ของไคลเอ็นต์ ตัวเลือกนี้ช่วยให้คุณย้ายตรรกะ Fulfillment เว็บฮุคไปยังเว็บแอปได้ และจำกัดการเรียกใช้เว็บฮุคไว้ที่ฟีเจอร์การสนทนาที่จำเป็นต้องใช้เท่านั้น เช่น การลิงก์บัญชี เมื่อเปิดใช้ คุณจะใช้ expect() เพื่อลงทะเบียนเครื่องจัดการ Intent ในฝั่งไคลเอ็นต์ได้
5. ไม่บังคับ: ป้อน URL ของเว็บแอปลงในช่องตั้งค่า URL ของเว็บแอปเริ่มต้น การดำเนินการนี้จะเพิ่มการตอบสนอง Canvas เริ่มต้นพร้อมช่อง URL ไปยังการเรียกใช้หลัก
6. คลิกบันทึก

เมื่อใช้ Actions SDK ให้ทำตามขั้นตอนเพิ่มเติมต่อไปนี้เพื่อเปิดใช้ Interactive Canvas

1. ตั้งค่าช่อง category ในไฟล์ settings.yaml เป็น GAMES_AND_TRIVIA เพื่ออธิบายและช่วยให้ผู้ใช้ค้นพบการดำเนินการของคุณได้ดีที่สุด
2. ตั้งค่าช่อง usesInteractiveCanvas ในไฟล์ settings.yaml เป็น true

ตรวจสอบความสามารถของพื้นผิว

เฟรมเวิร์ก Interactive Canvas ทำงานในอุปกรณ์ Assistant ที่มีอินเทอร์เฟซแบบภาพเท่านั้น การดำเนินการของคุณจึงต้องตรวจสอบINTERACTIVE_CANVAS ความสามารถในอุปกรณ์ของผู้ใช้ เมื่อกำหนดพรอมต์ใน Actions Builder คุณจะระบุรายการความสามารถของอุปกรณ์ในช่อง selector ของออบเจ็กต์ candidates ได้ ตัวเลือกพรอมต์จะเลือกข้อความแจ้งที่เหมาะกับความสามารถของอุปกรณ์ของผู้ใช้มากที่สุด

หากต้องการให้มีการตอบสนองด้วย Canvas ตรรกะของการดำเนินการของคุณควรมีลักษณะดังต่อไปนี้

1. ตรวจสอบว่าอุปกรณ์ของผู้ใช้รองรับความสามารถ INTERACTIVE_CANVAS หากใช่ ให้ส่งการตอบกลับ Canvas ให้แก่ผู้ใช้
2. หากความสามารถของ Interactive Canvas ไม่พร้อมใช้งาน โปรดตรวจสอบว่าอุปกรณ์ของผู้ใช้รองรับความสามารถ RICH_RESPONSE หรือไม่ หากใช่ ให้ส่งการตอบกลับที่สมบูรณ์ให้ผู้ใช้แทน
3. หากไม่สามารถตอบกลับด้วยริชมีเดียได้ ให้ส่งคำตอบง่ายๆ ให้แก่ผู้ใช้

ข้อมูลโค้ดต่อไปนี้จะแสดงการตอบสนองที่เหมาะสมตามความสามารถของอุปกรณ์ของผู้ใช้

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 แบบอินเทอร์แอกทีฟ

หมายเหตุ: การระบุ URL ของเว็บแอปใน Actions Builder จะไม่สร้างช่อง 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 ซึ่งส่งผ่านข้อมูลไปยังเว็บแอป จะเกิดขั้นตอนต่อไปนี้

1. เมื่อจับคู่ Intent ภายในโหมด ระบบจะเรียกเหตุการณ์ให้แสดง และการตอบสนอง Canvas ที่มีช่อง data ที่มีเพย์โหลด JSON จะถูกส่งกลับมาเป็นการตอบสนอง
2. ระบบจะส่งช่อง data ไปยังโค้ดเรียกกลับ onUpdate และใช้เพื่ออัปเดตเว็บแอป

3. การดำเนินการแบบการสนทนาจะส่งการตอบกลับ Canvas ใหม่และให้ข้อมูลในช่อง data เพื่อส่งข้อมูลอัปเดตใหม่หรือโหลดสถานะใหม่ได้

   หมายเหตุ: หากค่าในช่อง url เปลี่ยนไปในการตอบสนองของการดำเนินการตามคำสั่งซื้อที่ตามมา เว็บแอปจะโหลดซ้ำ หากระบุค่าเดียวกันสำหรับ url หรือถ้ามีการยกเว้น url เป็นส่วนหนึ่งของการตอบกลับในภายหลัง ระบบจะเก็บเว็บแอปที่มีอยู่ไว้ในอุปกรณ์

คุณส่งข้อมูลไปยังเว็บแอปได้ 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