เราเลิกใช้งานการดําเนินการแบบบทสนทนาไปเมื่อวันที่ 13 มิถุนายน 2023 โปรดดูข้อมูลเพิ่มเติมที่หัวข้อการหยุดให้บริการการดําเนินการด้านการสนทนา

หน้านี้ได้รับการแปลโดย Cloud Translation API

สร้างต่อไปโดยดําเนินการตามฝั่งไคลเอ็นต์หรือเซิร์ฟเวอร์

หลังจากได้เรียนรู้พื้นฐานการใช้งานแล้ว คุณสามารถเพิ่มประสิทธิภาพและปรับแต่งการดำเนินการของคุณด้วยวิธีการเฉพาะสำหรับ Canvas คุณเลือกพัฒนาการดำเนินการด้วยโมเดล Fulfillment ของไคลเอ็นต์หรือโมเดล Fulfillment ฝั่งเซิร์ฟเวอร์ได้เมื่อสร้างโปรเจ็กต์ Actions ดูข้อมูลเพิ่มเติมเกี่ยวกับตัวเลือกเหล่านี้ได้ที่เปิดใช้ Canvas แบบอินเทอร์แอกทีฟ

หากเลือกตัวเลือกโมเดล Fulfillment ของไคลเอ็นต์ คุณจะใช้ข้อมูลต่อไปนี้ในการดําเนินการได้

API ทั้งหมดแสดงอยู่ในสร้างด้วย Fulfillment ฝั่งไคลเอ็นต์
API ทั้งหมดแสดงอยู่ในสร้างด้วย Fulfillment ฝั่งเซิร์ฟเวอร์

หมายเหตุ: สําหรับ Fulfillment ฝั่งไคลเอ็นต์ เราขอแนะนำให้เรียกใช้เว็บฮุคสำหรับฟีเจอร์ที่ไม่ใช่ Canvas ที่จำเป็นต้องใช้เท่านั้น เช่น การลิงก์บัญชี
โค้ดเรียกกลับของ onTtsMark()

หากเลือกตัวเลือกโมเดล Fulfillment ของเซิร์ฟเวอร์ คุณจะใช้รายการต่อไปนี้ในการดําเนินการได้

API ทั้งหมดแสดงอยู่ในสร้างด้วย Fulfillment ฝั่งเซิร์ฟเวอร์
การติดต่อกลับ

เราไม่แนะนำให้ใช้ Interactive Canvas API บางรายการกับโมเดล Fulfillment ที่เฉพาะเจาะจง ตารางต่อไปนี้แสดง API ที่เปิดใช้เมื่อคุณเลือกตัวเลือก Fulfillment ของไคลเอ็นต์ และระบุว่าแต่ละโมเดลมีการแนะนำหรือไม่แนะนำ API เหล่านี้หรือไม่

คำเตือน: API ที่แสดงในตารางต่อไปนี้อยู่ในการแสดงตัวอย่างสำหรับนักพัฒนาซอฟต์แวร์ คุณทดสอบเหตุการณ์ดังกล่าวได้ในเครื่องจำลอง แต่อย่าใช้การดำเนินการที่ใช้ฟีเจอร์ใดๆ เหล่านี้กับเวอร์ชันอัลฟ่า เบต้า หรือเวอร์ชันที่ใช้งานจริง การดำเนินการที่ทำให้ใช้งานโดยใช้ ฟีเจอร์เหล่านี้จะไม่ทำงานในอุปกรณ์ของผู้ใช้ปลายทาง

ชื่อ API	รองรับในโมเดล Fulfillment เซิร์ฟเวอร์ไหม	รองรับในโมเดล Fulfillment ของไคลเอ็นต์ไหม
`sendTextQuery()`	มี	รองรับแต่ไม่แนะนำ (ดูข้อมูลเพิ่มเติมที่ sendtextQuery())
`outputTts()`	มี	มี
`triggerScene()`	ไม่ได้	ใช่
`createIntentHandler(), expect(), clearExpectations(), prompt()`	ไม่ได้	ใช่
`createNumberSlot(),createTextSlot, createConfirmationSlot, createOptionsSlot()`	ไม่ได้	ใช่
`setHomeParam(), getHomeParam(), setUserParam(), getUserParam()`	ไม่ได้	มี

ส่วนต่อไปนี้อธิบายวิธีใช้งาน API สำหรับโมเดล Fulfillment ฝั่งไคลเอ็นต์และฝั่งเซิร์ฟเวอร์ใน Canvas Action แบบอินเทอร์แอกทีฟ

สร้างโดยมี Fulfillment ฝั่งไคลเอ็นต์

คุณสามารถใช้ Interactive Canvas API ต่อไปนี้ในตรรกะของเว็บแอปได้

`outputTts()`

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

API นี้ให้คุณอ่านออกเสียงข้อความ (TTS) จากอุปกรณ์ได้โดยไม่ต้องส่งข้อความแจ้งแบบคงที่จาก Actions Builder หรือเรียกใช้เว็บฮุค หากไม่ต้องใช้ตรรกะฝั่งเซิร์ฟเวอร์ที่เชื่อมโยงกับ TTS คุณใช้ outputTts() จากฝั่งไคลเอ็นต์เพื่อข้ามการเดินทางไปยังเซิร์ฟเวอร์ของคุณและให้การตอบสนองกับผู้ใช้ที่เร็วขึ้นได้

ฝั่งไคลเอ็นต์outputTts()จะขัดจังหวะหรือยกเลิก TTS ฝั่งเซิร์ฟเวอร์ได้ คุณหลีกเลี่ยงการรบกวนการทำงานของ TTS ฝั่งเซิร์ฟเวอร์ได้โดยข้อควรระวังต่อไปนี้

หลีกเลี่ยงการเรียกใช้ outputTts() เมื่อเริ่มเซสชัน แต่ให้ใช้ TTS ฝั่งเซิร์ฟเวอร์ในการเริ่มสนทนาครั้งแรกของการดำเนินการของคุณแทน
หลีกเลี่ยงการโทรหา outputTts() ติดต่อกันโดยที่ผู้ใช้ไม่ได้ดำเนินการในระหว่างนั้น

ข้อมูลโค้ดต่อไปนี้แสดงวิธีใช้ outputTts() เพื่อเอาต์พุต TTS จากฝั่งไคลเอ็นต์

interactiveCanvas.outputTts(
      '<speak>This is an example response.</speak>', true);

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

interactiveCanvas.outputTts(
      '<speak>Speak as <mark name="number" /> number <break time="700ms"/>' +
      '<say-as interpret-as="cardinal">12345</say-as> <break time="300ms"/> ' +
      'Speak as <mark name="digits" /> digits <break time="700ms"/>' +
      '<say-as interpret-as="characters">12345</say-as></speak>', true);

ในตัวอย่างก่อนหน้านี้ เครื่องหมาย 2 ตัว ซึ่งปรับแต่งคำตอบจะส่งไปยังเว็บแอปที่มี TTS ด้วย

จัดการ Fulfillment Intent บนไคลเอ็นต์

ในโมเดล Fulfillment เซิร์ฟเวอร์สำหรับ Interactive Canvas เว็บฮุคจัดการ Intent ทั้งหมด ซึ่งจะเพิ่มเวลาในการตอบสนองในการดำเนินการ คุณจัดการ Fulfillment ของ Intent ภายในเว็บแอปได้แทนการเรียกใช้เว็บฮุค

คุณใช้ API ต่อไปนี้ได้เพื่อจัดการ Intent ฝั่งไคลเอ็นต์

createIntentHandler(): เมธอดที่ให้คุณกำหนดตัวแฮนเดิล Intent ในโค้ดเว็บแอปสำหรับ Intent ที่กำหนดเองที่กำหนดไว้ใน Actions Builder
expect(): เมธอดที่เปิดใช้งาน/ลงทะเบียนตัวแฮนเดิล Intent เพื่อให้ผู้ใช้ตรงกับ Intent
clearExpectations(): เมธอดที่ล้างความคาดหวังสำหรับ Intent ที่เปิดใช้งานในปัจจุบันทั้งหมด เพื่อไม่ให้จับคู่ Intent แม้ว่าผู้ใช้จะพูดว่าคำพูดที่ตรงกับความตั้งใจก็ตาม
deleteHandler(): วิธีการที่ปิดใช้ตัวแฮนเดิล Intent แต่ละตัวเพื่อให้จับคู่ Intent ไม่ได้

API เหล่านี้จะช่วยให้คุณเลือกเปิดหรือปิด Intent สำหรับสถานะต่างๆ ของ Interactive Canvas Action ได้ คุณต้องใช้ expect() ในเครื่องจัดการ Intent เพื่อเปิดใช้งาน Intent เหล่านั้น

เปิดใช้งานเครื่องจัดการ Intent

การเปิดใช้งานเครื่องจัดการ Intent เป็นกระบวนการที่มี 2 ขั้นตอน ก่อนอื่นคุณต้องกำหนด Intent ใน Actions Builder ต่อไปเพื่อให้ Intent จับคู่ได้ คุณต้องเรียกใช้ expect() บนตัวแฮนเดิล Intent

หากต้องการกำหนดค่าและเปิดใช้งานเครื่องจัดการ Intent ในฝั่งไคลเอ็นต์ ให้ทำตามขั้นตอนต่อไปนี้

เปิดโปรเจ็กต์ในคอนโซลการดำเนินการและเพิ่มความตั้งใจที่กำหนดเอง
เลือกใช่สำหรับนี่เป็นความตั้งใจทั่วโลกใช่ไหม

หมายเหตุ: Intent ที่คุณสร้างใน Actions Builder ที่ทริกเกอร์จากฝั่งไคลเอ็นต์ต้องมีการกําหนดค่าเป็น Intent ส่วนกลาง
กำหนดค่า Intent แล้วคลิกบันทึก

กำหนดเครื่องจัดการสำหรับ Intent ในตรรกะของเว็บแอป ดังที่แสดงในข้อมูลโค้ดต่อไปนี้

/**
* Define handler for intent.
*/
const bookTableIntent = interactiveCanvas.createIntentHandler('reserveTable',
  matchedIntent => {
    console.log("Intent match handler to reserve a table was triggered!");
  });

/**
* Define handler for intent with an argument.
*/
const bookTableIntent = interactiveCanvas.createIntentHandler('reserveTable',
  matchedIntent => {
    const numberOfPeople = matchedIntent.getIntentArg('numberOfPeople');
    console.log(`Intent match handler to reserve a table for ${number of people} was triggered!`);
  });

เรียกเมธอด expect() เพื่อลงทะเบียนเครื่องจัดการ Intent ตามที่แสดงในข้อมูลโค้ดต่อไปนี้

/**
* Define handler for intent and expect() it.
*/
const bookTableIntent = interactiveCanvas.createIntentHandler('reserveTable',
  matchedIntent => {
    console.log("Intent match handler to reserve a table was triggered!");
  });
var handler = interactiveCanvas.expect(bookTableIntent);

ปิดใช้เครื่องจัดการ Intent

หลังจากกำหนดตัวแฮนเดิล Intent แล้ว คุณจะเปิดหรือปิดใช้งาน Intent ที่จำเป็นสำหรับการดำเนินการได้ เมื่อเรียกใช้ expect() เพื่อเปิดใช้งาน Intent ระบบจะแสดงผลออบเจ็กต์ที่มีเมธอด deleteHandler() ซึ่งคุณจะใช้ปิดใช้เครื่องจัดการที่สร้างขึ้นใหม่ได้ คำจำกัดความของตัวแฮนเดิล Intent จะยังคงอยู่แม้ว่า Intent จะไม่ได้ทำงานอยู่ คุณจึงเปิดใช้งาน Intent ได้อีกครั้งเมื่อต้องการ

หากต้องการปิดใช้เครื่องจัดการ Intent ให้เรียกใช้ deleteHandler() บนตัวแฮนเดิล Intent ดังที่แสดงในข้อมูลโค้ดต่อไปนี้

    /**
    * Define handler for intent and expect() it.
    */
    const bookTableIntent = interactiveCanvas.createIntentHandler('reserveTable',
      matchedIntent => {
        console.log("Intent match handler to reserve a table was triggered!");
      });
    var handler = interactiveCanvas.expect(bookTableIntent);
    
    // Delete the handler for `bookTableIntent`.
    handler.deleteHandler();

คุณเรียกใช้ expect() เพื่อเพิ่มตัวแฮนเดิล Intent ที่ปิดใช้อยู่อีกครั้งได้ ดังที่แสดงในข้อมูลโค้ดต่อไปนี้

    // Re-add the `bookTableIntent` handler.
    handler = interactiveCanvas.expect(bookTableIntent);

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

interactiveCanvas.clearExpectations();

จัดการการเติมช่องบนไคลเอ็นต์

แทนที่จะเพิ่มช่องลงในฉากภายใน Actions Builder คุณจะจัดการการเติมช่องโฆษณาในเว็บแอปได้โดยตรง

หากต้องการจัดการการเติมช่องโฆษณาในฝั่งไคลเอ็นต์ คุณต้องสร้างช่องโฆษณาโดยใช้ API อย่างใดอย่างหนึ่งต่อไปนี้ก่อน

createNumberSlot(callback, hints): วิธีที่ให้คุณกำหนดช่องตัวเลขในโค้ดเว็บแอป ใช้เพื่อแจ้งให้ผู้ใช้ป้อนหมายเลข
createTextSlot(callback, hints): วิธีที่ให้คุณกำหนดช่องข้อความในโค้ดของเว็บแอป ใช้เพื่อแสดงข้อความแจ้งให้ผู้ใช้ทราบ
createConfirmationSlot(callback, hints): วิธีการที่ให้คุณกำหนดช่องการยืนยันในโค้ดของเว็บแอป ใช้เพื่อแจ้งให้ผู้ใช้ยืนยัน (ใช่/ไม่ใช่)
createOptionsSlot(options, callback, hints): วิธีที่ให้คุณกำหนดช่องตัวเลือกในโค้ดเว็บแอป ใช้เพื่อแจ้งให้ผู้ใช้ เลือกจากรายการตัวเลือกที่กำหนดไว้ล่วงหน้า

เมื่อสร้างช่องโฆษณา คุณจะกำหนด triggerHints หรือไม่ก็ได้ ซึ่งเป็นคีย์เวิร์ดที่ปรับปรุงระบบการทำความเข้าใจภาษาธรรมชาติ (NLU) สำหรับการดำเนินการ คีย์เวิร์ดเหล่านี้ควรเป็นคำสั้นๆ ที่ผู้ใช้อาจพูดเมื่อจะใส่ช่องโฆษณา เช่น คีย์เวิร์ด triggerHints สำหรับช่องตัวเลขอาจเป็น years เมื่อผู้ใช้ตอบคำถามเกี่ยวกับอายุในการสนทนาด้วยคำตอบว่า "ฉันอายุ 30 ปี" การดำเนินการของคุณมีแนวโน้มที่จะรับรู้ได้ว่าผู้ใช้กรอกข้อมูลในช่องอย่างเหมาะสม

หลังจากสร้างสล็อตแล้ว คุณอาจแจ้งผู้ใช้สำหรับสล็อตนั้นได้โดยใช้ prompt API ดังนี้

prompt(tts, slot): เมธอดที่จะแสดงผล TTS ให้กับผู้ใช้โดยแจ้งให้มีการเติมโฆษณาในช่องที่คาดไว้

การเรียกใช้ prompt() จะแสดงผลสัญญาพร้อมสถานะและค่าของช่องโฆษณา

สร้างช่องตัวเลข

ช่องตัวเลขช่วยให้คุณแจ้งเตือนผู้ใช้ให้ใส่หมายเลขในระหว่างการสนทนาได้ สำหรับข้อมูลเพิ่มเติมเกี่ยวกับการเติมช่องโฆษณา โปรดดูส่วนการเติมช่องโฆษณาในเอกสารประกอบ Actions Builder

หากต้องการแจ้งให้ผู้ใช้กรอกช่องตัวเลขในฝั่งไคลเอ็นต์ ให้ทำตามขั้นตอนต่อไปนี้

เรียกใช้เมธอด createNumberSlot() เพื่อสร้างช่องตัวเลขในตรรกะของเว็บแอป ดังนี้

/**
 * Create number slot.
 */
const triggerHints = { associatedWords: ['guess number', 'number'] };
const slot = interactiveCanvas.createNumberSlot(
  number => {
    console.log(`Number guessed: ${number}.`);
  }, triggerHints);

เรียกใช้เมธอด prompt() เพื่อแสดงข้อความแจ้งผู้ใช้สำหรับช่องโฆษณา และจัดการค่าช่องโฆษณาจาก Promise ที่แสดงผลตามที่แสดงในข้อมูลโค้ดต่อไปนี้

const promptPromise = interactiveCanvas.prompt(
  { text: 'What number am I thinking of between 1 and 10?' }, slot);

promptPromise.then(
  answer => {
    if (answer.status == interactiveCanvas.AnswerStatus.ANSWERED) {
      // answer === {value: 5, status: ANSWERED}
      // Do something with answer.value
    } else {
      console.error('Promise returned unsuccessful status ' + answer.status);
    }
  });

สร้างช่องข้อความ

ช่องข้อความให้คุณแสดงข้อความแจ้งให้ผู้ใช้ทราบระหว่างการสนทนาได้ สำหรับข้อมูลเพิ่มเติมเกี่ยวกับการเติมช่องโฆษณา โปรดดูส่วนการเติมช่องโฆษณาในเอกสารประกอบ Actions Builder

หากต้องการแจ้งให้ผู้ใช้เติมช่องข้อความในฝั่งไคลเอ็นต์ ให้ทำตามขั้นตอนต่อไปนี้

เรียกใช้เมธอด createTextSlot() เพื่อสร้างช่องข้อความในตรรกะของเว็บแอป ดังนี้

/**
 * Create text slot.
 */
const triggerHints = { associatedWords: ['favorite color', 'color'] };
const slot = interactiveCanvas.createTextSlot(
  text => {
    console.log(`Favorite color: ${text}.`);
  }, triggerHints);

const promptPromise = interactiveCanvas.prompt(
  { text: 'What is your favorite color?' }, slot);

promptPromise.then(
  answer => {
    if (answer.status == interactiveCanvas.AnswerStatus.ANSWERED) {
      // answer === {value: "red", status: ANSWERED}
      // Do something with answer.value
    } else {
      console.error('Promise returned unsuccessful status ' + answer.status);
    }
  });

สร้างช่วงเวลายืนยัน

ช่องยืนยันจะให้คุณส่งข้อความแจ้งให้ผู้ใช้ยืนยัน (ผู้ใช้ตอบกลับว่า "ใช่" หรือ "ไม่" เพื่อเติมช่องได้) สำหรับข้อมูลเพิ่มเติมเกี่ยวกับการเติมช่องโฆษณา โปรดดูส่วนการเติมช่องโฆษณาในเอกสารประกอบ Actions Builder

หากต้องการแจ้งให้ผู้ใช้เติมช่องยืนยันในฝั่งไคลเอ็นต์ ให้ทำตามขั้นตอนต่อไปนี้

เรียกเมธอด createConfirmationSlot() เพื่อสร้างช่องการยืนยันในตรรกะของเว็บแอป ดังนี้

/**
 * Create confirmation slot (boolean).
 */
const triggerHints = { associatedWords: ['user confirmation', 'confirmation'] };
const slot = interactiveCanvas.createConfirmationSlot(
  yesOrNo => {
    console.log(`Confirmation: ${yesOrNo}`);
  }, triggerHints);

const promptPromise = interactiveCanvas.prompt(
  { text: 'Do you agree to the Terms of Service?' }, slot);

promptPromise.then(
  answer => {
    if (answer.status == interactiveCanvas.AnswerStatus.ANSWERED) {
      // answer === {value: true, status: ANSWERED}
      // Do something with answer.value
    } else {
      console.error('Promise returned unsuccessful status ' + answer.status);
    }
  });

สร้างช่องตัวเลือก

ช่องตัวเลือกให้คุณแสดงข้อความแจ้งให้ผู้ใช้เลือกจากรายการตัวเลือกที่กำหนดไว้ล่วงหน้า สำหรับข้อมูลเพิ่มเติมเกี่ยวกับการเติมช่องโฆษณา โปรดดูส่วนการเติมช่องโฆษณาในเอกสารประกอบ Actions Builder

หากต้องการแจ้งให้ผู้ใช้เติมช่องตัวเลือกในฝั่งไคลเอ็นต์ ให้ทำตามขั้นตอนต่อไปนี้

เรียกเมธอด createOptionsSlot() เพื่อสร้างช่องตัวเลือกในตรรกะของเว็บแอป ดังนี้

/**
 * Create options slot (list selection).
 */
const triggerHints = { associatedWords: ['select fruit', 'choose fruit'] };
// Define selectable options
const options = [{
  key: 'apple',
  synonyms: ['apple', 'large apple', 'gala apple'],
}, {
  key: 'banana',
  synonyms: ['banana', 'green banana', 'plantain'],
}];
const slot = interactiveCanvas.createOptionsSlot(
  options,
  selectedOption => {
    console.log(`You have selected ${selectedOption} as your fruit.`);
  }, triggerHints);

const promptPromise = interactiveCanvas.prompt(
  { text: 'Would you like a banana or an apple?' }, slot);

promptPromise.then(
  answer => {
    if (answer.status == interactiveCanvas.AnswerStatus.ANSWERED) {
      // answer === {value: 'apple', status: ANSWERED}
      // Do something with answer.value
    } else {
      console.error('Promise returned unsuccessful status ' + answer.status);
    }
  });

`triggerScene()`

triggerScene() API ช่วยให้คุณเปลี่ยนไปใช้ฉากอื่นใน Interactive Canvas Action จาก Fulfillment ฝั่งไคลเอ็นต์ได้ เมื่อใช้ triggerScene() คุณยังเปลี่ยนจาก Fulfillment ฝั่งไคลเอ็นต์ไปเป็น Fulfillment ฝั่งเซิร์ฟเวอร์ได้เมื่อผู้ใช้ต้องการเข้าถึงโหมดของระบบใน Actions Builder ที่จำเป็นต้องใช้เว็บฮุค ตัวอย่างเช่น คุณสามารถเรียกใช้ triggerScene() เมื่อผู้ใช้ต้องลิงก์บัญชีหรือรับการแจ้งเตือน จากนั้นคุณจะเปลี่ยนจากโหมดนั้นไปใช้การดำเนินการฝั่งไคลเอ็นต์ได้ด้วยข้อความแจ้ง Canvas

ข้อมูลโค้ดต่อไปนี้แสดงวิธีนำ triggerScene() ไปใช้ในการดำเนินการของคุณ

interactiveCanvas.triggerScene('SceneName').then((status) => {
  console.log("sent the request to trigger scene.");
}).catch(e => {
  console.log("Failed to trigger a scene.");
})

พื้นที่เก็บข้อมูลในหน้าแรกและของผู้ใช้บนไคลเอ็นต์

คุณสามารถเรียกใช้ API ฝั่งไคลเอ็นต์ให้จัดการพื้นที่เก็บข้อมูลภายในบ้านและของผู้ใช้ในเว็บแอปแทนการใช้เว็บฮุคเพื่อรับและกําหนดค่าพื้นที่เก็บข้อมูลในบ้านและของผู้ใช้ได้ จากนั้นเว็บแอปจะใช้ค่าที่จัดเก็บไว้เหล่านี้ในหลายๆ เซสชัน (เช่น ในข้อความแจ้งและเงื่อนไข) และสามารถเข้าถึงค่าของครอบครัวหรือผู้ใช้ที่เฉพาะเจาะจงได้เมื่อจำเป็น การใช้ API เหล่านี้จะช่วยลดเวลาในการตอบสนองใน Interactive Canvas การดำเนินการของคุณได้เนื่องจากคุณไม่จำเป็นต้องเรียกเว็บฮุคเพื่อรับและตั้งค่าพื้นที่เก็บข้อมูลอีกต่อไป

พื้นที่เก็บข้อมูลบนหน้าแรกและของผู้ใช้ในเว็บแอปจะใช้หลักการทั่วไปเดียวกันกับพื้นที่เก็บข้อมูลในเว็บฮุค ดูข้อมูลเพิ่มเติมเกี่ยวกับพื้นที่เก็บข้อมูลในบ้านและพื้นที่เก็บข้อมูลของผู้ใช้ได้ที่เอกสารประกอบสำหรับพื้นที่เก็บข้อมูลในบ้านและพื้นที่เก็บข้อมูลของผู้ใช้

พื้นที่เก็บข้อมูลในบ้านฝั่งไคลเอ็นต์

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

หากต้องการเปิดใช้การดำเนินการเพื่อรองรับพื้นที่เก็บข้อมูลในบ้าน ให้ทำตามขั้นตอนต่อไปนี้

ในคอนโซล Actions ให้ไปที่ ทำให้ใช้งานได้ > ข้อมูลไดเรกทอรี > ข้อมูลเพิ่มเติม
เลือกช่องใช่ในหัวข้อการดำเนินการของคุณใช้พื้นที่เก็บข้อมูลในบ้านไหม

หากต้องการเขียนค่าไปยังพื้นที่เก็บข้อมูล Home ในเว็บแอป ให้เรียกใช้เมธอด setHomeParam() ดังที่แสดงในข้อมูลโค้ดต่อไปนี้

interactiveCanvas.setHomeParam('familySize',  10).then(
      result => {
        console.log('Set home param success');
      },
      fail => {
        console.error(err);
      });

หากต้องการอ่านค่าจากพื้นที่เก็บข้อมูลที่บ้านในเว็บแอป ให้เรียกใช้เมธอด getHomeParam() ดังที่แสดงในข้อมูลโค้ดต่อไปนี้

interactiveCanvas.getHomeParam('familySize').then(
      value => {
        console.log(JSON.stringify(result));
      },
      err => {
        console.error(err);
      }
  );

หากต้องการล้างพื้นที่เก็บข้อมูล Home ที่มีอยู่ทั้งหมด ให้เรียกใช้เมธอด resetHomeParam() ดังที่แสดงในข้อมูลโค้ดต่อไปนี้

interactiveCanvas.resetHomeParam();

พื้นที่เก็บข้อมูลผู้ใช้ฝั่งไคลเอ็นต์

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

หากต้องการเขียนค่าลงในพื้นที่เก็บข้อมูลของผู้ใช้ในเว็บแอป ให้เรียกใช้เมธอด setUserParam() ดังที่แสดงในข้อมูลโค้ดต่อไปนี้

interactiveCanvas.setUserParam('color',  'blue').then(
      result => {
        console.log('Set user param success');
      },
      err => {
        console.error(err);
      });

หากต้องการอ่านค่าจากพื้นที่เก็บข้อมูลของผู้ใช้ในเว็บแอป ให้เรียกใช้เมธอด getUserParam() ดังที่แสดงในข้อมูลโค้ดต่อไปนี้

interactiveCanvas.getUserParam('color').then(
      value => {
        console.log(JSON.stringify(result));
      },
      err => {
        console.error(err);
      }
  );

หากต้องการล้างพื้นที่เก็บข้อมูลของผู้ใช้ที่มีอยู่ทั้งหมด ให้เรียกใช้เมธอด resetUserParam() ดังที่แสดงในข้อมูลโค้ดต่อไปนี้

interactiveCanvas.resetUserParam();

`setCanvasState()`

เมธอด setCanvasState() ช่วยให้คุณส่งข้อมูลสถานะจากเว็บแอป Canvas แบบอินเทอร์แอกทีฟไปยัง Fulfillment ได้และแจ้ง Assistant ว่าเว็บแอปได้อัปเดตสถานะแล้ว เว็บแอปจะส่งสถานะที่อัปเดตเป็นออบเจ็กต์ JSON

การเรียกใช้ setCanvasState() จะไม่เรียกใช้ Intent หลังจากเรียกใช้ setCanvasState() หากมีการเรียกใช้ sendTextQuery() หรือคำค้นหาของผู้ใช้ตรงกับความตั้งใจในการสนทนา ข้อมูลที่ตั้งค่าไว้ด้วย setCanvasState() ในบทสนทนาก่อนหน้าจะพร้อมใช้งานเมื่อกลับเข้าสู่การสนทนา

ในข้อมูลโค้ดต่อไปนี้ เว็บแอปใช้ setCanvasState() เพื่อตั้งค่าข้อมูลสถานะ Canvas

JavaScript

this.action.canvas.setCanvasState({ score: 150 })

อ้างอิงสถานะ Canvas จากเว็บฮุค

คุณจะอ้างอิงค่าสถานะ Canvas ที่จัดเก็บไว้ได้ในรหัสการดำเนินการตามคำสั่งซื้อ หากต้องการอ้างอิงค่า ให้ใช้ไวยากรณ์ conv.context.canvas.state.KEY โดย KEY คือคีย์ที่ให้ไว้เมื่อตั้งค่าสถานะ Canvas

เช่น หากก่อนหน้านี้คุณได้เก็บค่าคะแนนสูงสุดสําหรับเกมในสถานะของ Canvas เป็นพารามิเตอร์ score ให้อ้างอิงค่านั้นโดยใช้ conv.context.canvas.state.score เพื่อเข้าถึงค่าดังกล่าวในการดำเนินการตามรูปแบบต่อไปนี้

Node.js

app.handle('webhook-name', conv => {
    console.log(conv.context.canvas.state.score);
})

อ้างอิงสถานะ Canvas ภายในข้อความแจ้ง

คุณจะอ้างอิงค่าสถานะ Canvas ที่เก็บไว้ในพรอมต์ได้ หากต้องการอ้างอิงค่า ให้ใช้ไวยากรณ์ $canvas.state.KEY โดย KEY คือคีย์ที่ให้ไว้เมื่อตั้งค่าสถานะ Canvas

เช่น หากก่อนหน้านี้คุณเคยเก็บค่าคะแนนสูงสุดสําหรับเกมในสถานะของ Canvas เป็นพารามิเตอร์ score ให้อ้างอิงค่านั้นโดยใช้ $canvas.state.score เพื่อเข้าถึงค่านั้นในข้อความแจ้ง

JSON

{
  "candidates": [{
    "first_simple": {
      "variants": [{
        "speech": "Your high score is $canvas.state.score."
      }]
    }
  }]
}

อ้างอิงสถานะ Canvas ภายในเงื่อนไข

นอกจากนี้ คุณยังอ้างอิงค่าสถานะ Canvas ที่จัดเก็บไว้ได้ในเงื่อนไข หากต้องการอ้างอิงค่า ให้ใช้ไวยากรณ์ canvas.state.KEY โดยที่ KEY คือคีย์ที่ให้ไว้เมื่อตั้งค่าสถานะ Canvas

เช่น หากก่อนหน้านี้คุณจัดเก็บค่าคะแนนสูงสุดสำหรับเกมในสถานะของ Canvas เป็นพารามิเตอร์ score และต้องการเปรียบเทียบกับค่า 999 ในเงื่อนไข คุณก็อ้างอิงค่าที่เก็บไว้ในเงื่อนไขได้โดยใช้ canvas.state.score นิพจน์เงื่อนไขจะมีลักษณะดังนี้

ไวยากรณ์ของเงื่อนไข

canvas.state.score >= 999

`sendTextQuery()`

เมธอด sendTextQuery() จะส่งการค้นหาข้อความไปยังการดำเนินการแบบการสนทนาเพื่อจับคู่ Intent แบบเป็นโปรแกรม ตัวอย่างนี้ใช้ sendTextQuery() เพื่อเริ่มเกมสามเหลี่ยมหมุนใหม่เมื่อผู้ใช้คลิกปุ่ม เมื่อผู้ใช้คลิกปุ่ม "เริ่มเกมใหม่" sendTextQuery() จะส่งการค้นหาข้อความที่ตรงกับความตั้งใจ Restart game และแสดงผลคำมั่นสัญญา สัญญานี้ส่งผลให้เกิด SUCCESS หากเรียกใช้ Intent และแสดง BLOCKED หากไม่ได้ ข้อมูลโค้ดต่อไปนี้ตรงกับเจตนาและจัดการกรณีสำเร็จและไม่สำเร็จของคำมั่นสัญญา

JavaScript

…
/**
* Handle game restarts
*/
async handleRestartGame() {
    console.log(`Request in flight`);
    this.button.texture = this.button.textureButtonDisabled;
    this.sprite.spin = false;
    const res = await this.action.canvas.sendTextQuery('Restart game');
    if (res.toUpperCase() !== 'SUCCESS') {
        console.log(`Request in flight: ${res}`);
        return;
    }
    console.log(`Request in flight: ${res}`);
    this.button.texture = this.button.textureButtonDisabled;
    this.sprite.spin = false;
}
…

หากคำมั่นสัญญาให้ผลลัพธ์เป็น SUCCESS เครื่องจัดการเว็บฮุค Restart game จะส่งการตอบสนอง Canvas ไปยังเว็บแอปของคุณ

JavaScript

…
app.handle('restart', conv => {
  conv.add(new Canvas({
    data: {
      command: 'RESTART_GAME'
    }
  }));
});
…

การตอบกลับ Canvas นี้จะทริกเกอร์โค้ดเรียกกลับ onUpdate() ซึ่งจะเรียกใช้โค้ดในข้อมูลโค้ด RESTART_GAME ด้านล่าง

JavaScript

…
RESTART_GAME: (data) => {
    this.scene.button.texture = this.scene.button.textureButton;
    this.scene.sprite.spin = true;
    this.scene.sprite.tint = 0x00FF00; // green
    this.scene.sprite.rotation = 0;
},
…

สร้างด้วย Fulfillment ฝั่งเซิร์ฟเวอร์

คุณใช้ Interactive Canvas API ต่อไปนี้ในเว็บฮุคได้

เปิดใช้โหมดเต็มหน้าจอ

โดยค่าเริ่มต้น เว็บแอป Canvas แบบอินเทอร์แอกทีฟจะมีส่วนหัวที่ด้านบนของหน้าจอพร้อมชื่อการดำเนินการของคุณ คุณใช้ enableFullScreen เพื่อนำส่วนหัวออกและแทนที่ด้วยข้อความโทสต์ชั่วคราวที่ปรากฏในหน้าจอการโหลดได้ ซึ่งช่วยให้ผู้ใช้ได้รับประสบการณ์แบบเต็มหน้าจอขณะโต้ตอบกับการดำเนินการของคุณ ข้อความโทสต์จะแสดงชื่อที่แสดงของการดำเนินการ ชื่อนักพัฒนาซอฟต์แวร์ และวิธีการออกจากการดำเนินการ และสีของข้อความโทสต์จะเปลี่ยนแปลงไปตามสิ่งที่ผู้ใช้เลือกให้เป็นธีมในอุปกรณ์

**รูปที่ 1** ข้อความโทสต์บนหน้าจอการโหลดสำหรับการดำเนินการ

หากผู้ใช้โต้ตอบกับการดำเนินการของคุณบ่อยๆ ข้อความโทสต์จะหยุดปรากฏขึ้นชั่วคราวในหน้าจอการโหลด หากผู้ใช้ไม่ได้มีส่วนร่วมกับการดำเนินการมาสักระยะหนึ่ง ข้อความโทสต์จะปรากฏขึ้นอีกครั้งเมื่อผู้ใช้เปิดการดำเนินการ

คุณสามารถเปิดใช้โหมดเต็มหน้าจอในเว็บฮุคหรือในข้อความแจ้งแบบคงที่ใน Actions Builder

หากต้องการเปิดใช้โหมดเต็มหน้าจอในเว็บฮุค ให้ทำตามขั้นตอนต่อไปนี้

ตั้งค่าช่อง enableFullScreen เป็น true ในการตอบกลับ canvas แรกที่เว็บฮุคแสดงผลในเซสชัน ข้อมูลโค้ดต่อไปนี้เป็นตัวอย่างการใช้งานโดยใช้ไลบรารีของไคลเอ็นต์ Node.js
```
 const { conversation, Canvas } = require('@assistant/conversation');
 const functions = require('firebase-functions');

 const app = conversation();

 app.handle('invocation_fullscreen', conv => {
   conv.add(new Canvas(
     {
       url: 'https://example-url.com',
       enableFullScreen: true
     }));
 });

 exports.ActionsOnGoogleFulfillment = functions.https.onRequest(app);
```

หากต้องการเปิดใช้โหมดเต็มหน้าจอในข้อความแจ้งแบบคงที่ใน Actions Builder ให้ทำตามขั้นตอนต่อไปนี้

เปิดโปรเจ็กต์ในคอนโซลการดำเนินการ
คลิกพัฒนาในแถบนำทางแล้วเปิดข้อความแจ้งที่มีการตอบกลับจาก canvas แรก

ตั้งค่า enable_full_screen เป็น true ตามที่แสดงในตัวอย่างต่อไปนี้

 {
  "candidates": [
    {
      "canvas": {
        "url": "https://example-url.com",
        "enable_full_screen": true
      }
    }
  ]
}

`continueTtsDuringTouch`

โดยค่าเริ่มต้น เมื่อผู้ใช้แตะหน้าจอขณะใช้ Canvas แบบอินเทอร์แอกทีฟ การทำงาน TTS จะหยุดเล่น คุณสามารถเปิดใช้งาน TTS เพื่อให้สามารถเล่นต่อได้ เมื่อผู้ใช้แตะหน้าจอด้วย continueTtsDuringTouch คุณจะเปิดและปิดใช้ลักษณะการทำงานนี้ในเซสชันเดียวกันไม่ได้

คุณสามารถใช้ลักษณะการทำงานนี้ในเว็บฮุคหรือในข้อความแจ้งแบบคงที่ใน Actions Builder

หากต้องการเปิดใช้ TTS เพื่อดำเนินการต่อหลังจากที่ผู้ใช้แตะหน้าจอในเว็บฮุค ให้ทำตามขั้นตอนต่อไปนี้

ตั้งค่าช่อง continueTtsDuringTouch เป็น true ในการตอบกลับ canvas แรกที่เว็บฮุคแสดงผลในเซสชัน ข้อมูลโค้ดต่อไปนี้เป็นตัวอย่างการใช้งานโดยใช้ไลบรารีของไคลเอ็นต์ Node.js
```
const { conversation, Canvas } = require('@assisant/conversation');
const functions = require('firebase-functions');

const app = conversation();

app.handle('intent-name', conv => {
  conv.add(new Canvas(
    {
      url: 'https://example-url.com',
      continueTtsDuringTouch: true
    }));
});

exports.ActionsOnGoogleFulfillment = functions.https.onRequest(app);
```

หากต้องการเปิดใช้ TTS เพื่อดำเนินการต่อหลังจากที่ผู้ใช้แตะหน้าจอในข้อความแจ้งแบบคงที่ในเครื่องมือสร้างการดำเนินการ ให้ทำตามขั้นตอนต่อไปนี้

เปิดโปรเจ็กต์ในคอนโซลการดำเนินการ
คลิกพัฒนาในแถบนำทางแล้วเปิดพรอมต์ที่มีการตอบกลับ canvas รายการแรก

ตั้งค่า continue_tts_during_touch เป็น true ตามที่แสดงในตัวอย่างต่อไปนี้

  {
   "candidates": [
     {
       "canvas": {
         "url": "https://example-url.com",
         "continue_tts_during_touch": true
       }
     }
   ]
 }