مواصلة البناء باستخدام عملية تسليم من جهة العميل أو خادم

بعد أن تعلمت الأساسيات، يمكنك تحسين الإجراء الخاص بك وتخصيصه باستخدام الطرق الخاصة بلوحة الرسم. يمكنك اختيار تطوير الإجراء الخاص بك باستخدام نموذج تنفيذ العميل أو نموذج التنفيذ من جهة الخادم عند إنشاء مشروع "المهام". لمزيد من المعلومات حول هذه الخيارات، يُرجى الاطّلاع على تفعيل "لوحة الرسم التفاعلية".

إذا حددت خيار نموذج تنفيذ العميل، يمكنك استخدام ما يلي في الإجراء الخاص بك:

إذا حددت خيار نموذج تنفيذ الخادم، فيمكنك استخدام ما يلي في الإجراء الخاص بك:

لا يُنصح باستخدام بعض واجهات برمجة تطبيقات لوحة الرسم التفاعلية مع نموذج تنفيذ محدّد. يُظهر الجدول التالي واجهات برمجة التطبيقات المفعّلة عند تحديد خيار تنفيذ العميل، وما إذا كان استخدام واجهات برمجة التطبيقات هذه مقترحًا أو لا يُنصح باستخدامها لكل نموذج:

اسم واجهة برمجة التطبيقات هل متوافق مع نموذج تنفيذ الخادم؟ هل تتوفّر هذه الميزة في نموذج تنفيذ العملاء؟
sendTextQuery() نعم متوافق ولكن لا يُنصح به (راجِع sendtextQuery() لمزيد من المعلومات)
outputTts() نعم نعم
triggerScene() لا نعم
createIntentHandler(), expect(), clearExpectations(), prompt() لا نعم
createNumberSlot(),createTextSlot, createConfirmationSlot, createOptionsSlot() لا نعم
setHomeParam(), getHomeParam(), setUserParam(), getUserParam() لا نعم

تشرح الأقسام التالية كيفية تنفيذ واجهات برمجة التطبيقات (APIs) لنماذج التنفيذ من جهة الخادم والخادم في "إجراء لوحة الرسم التفاعلي".

الإنشاء من خلال التنفيذ من جهة العميل

يمكنك تنفيذ واجهات برمجة تطبيقات لوحة الرسم التفاعلية التالية في منطق تطبيق الويب:

outputTts()

تسمح لك واجهة برمجة التطبيقات هذه بتحويل النص إلى كلام من أحد الأجهزة بدون إرسال طلب ثابت من "أداة إنشاء الإجراءات" أو طلب ردّ تلقائي على الويب. إذا لم يكن هناك أي منطق من جهة الخادم مرتبطًا بتقنية TTS، يمكنك استخدام outputTts() من جهة العميل لتخطّي الرحلة إلى الخادم وتقديم رد أسرع للمستخدمين.

يمكن لميزة outputTts()من جهة العميل مقاطعة ميزة "تحويل النص إلى كلام" من جهة الخادم أو إلغاؤها. يمكنك تجنُّب مقاطعة تقنية "تحويل النص إلى كلام" من جهة الخادم من خلال اتّخاذ الاحتياطات التالية:

  • تجنَّب طلب "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);

في المثال السابق، يتم إرسال العلامتين اللتين مخصصتان لردك إلى تطبيق الويب باستخدام تقنية TTS.

معالجة تنفيذ النية لدى العميل

في نموذج تنفيذ الخادم لـ "لوحة الرسم التفاعلية"، يجب معالجة جميع الأغراض من خلال ردّ تلقائي على الويب، ما يزيد من وقت الاستجابة في الإجراء. بدلاً من طلب الردّ التلقائي على الويب، يمكنك معالجة تنفيذ الأهداف داخل تطبيق الويب.

للتعامل مع الأهداف من جهة العميل، يمكنك استخدام واجهات برمجة التطبيقات التالية:

  • createIntentHandler(): طريقة تسمح لك بتعريف معالِجات الأهداف في رمز تطبيق الويب للأهداف المخصّصة المحدّدة في "أداة إنشاء الإجراءات".
  • expect(): طريقة تفعّل/تسجِّل معالِج الغرض بحيث يتمكّن المستخدم من مطابقة الغرض.
  • clearExpectations(): طريقة توضّح التوقعات لجميع الأغراض المفعّلة حاليًا بحيث لا يمكن مطابقة الأغراض، حتى إذا قال المستخدم عبارة تتطابق مع الغرض.
  • deleteHandler(): طريقة توقِف معالِجات الأهداف الفردية حتى لا يمكن مطابقة هذه الأغراض.

باستخدام واجهات برمجة التطبيقات هذه، يمكنك تفعيل الأغراض أو إيقافها بشكل انتقائي لحالات مختلفة من إجراء لوحة الرسم التفاعلية. وعليك استخدام العلامة expect() في معالِجات الأهداف لتفعيل هذه الأغراض.

تفعيل معالِجات الأهداف

تفعيل معالِج الأهداف عبارة عن عملية من خطوتَين. أولاً، يجب تحديد الهدف في "أداة إنشاء الإجراءات" بعد ذلك، للمطابقة بين الغرض، عليك استدعاء expect() على معالج الأهداف.

لضبط معالج أهداف وتنشيطه من جهة العميل، اتّبِع الخطوات التالية:

  1. افتح مشروعك في وحدة تحكّم الإجراءات وأضِف هدف مخصّص حسب النية بالشراء.
  2. اختَر نعم في الحقل هل هذا هدف عالمي؟

  3. اضبط هدفك وانقر على حفظ.

  4. حدّد المعالج للهدف في منطق تطبيق الويب، كما هو موضّح في المقتطف التالي:

    /**
    * 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!`);
      });
    
  5. استدعِ الطريقة expect() لتسجيل معالج الغرض، كما هو موضّح في المقتطف التالي:

    /**
    * 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);
    

إيقاف معالِجات الأهداف

بعد تعريف معالج النية، يمكنك تفعيل الهدف أو إيقافه حسب الحاجة إلى الإجراء الخاص بك. عند استدعاء الدالة expect() لتفعيل هدف، يتم عرض كائن باستخدام طريقة deleteHandler() التي يمكنك استخدامها لإيقاف المعالج الذي تم إنشاؤه حديثًا. ويستمر تعريف معالج الغرض حتى إذا لم يكن الغرض نشطًا حاليًا، بحيث يمكنك إعادة تفعيل الغرض عند الحاجة.

لإيقاف معالج أهداف، يمكنك استدعاء deleteHandler() في معالج الأهداف، كما هو موضّح في المقتطف التالي:

    /**
    * 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() لإعادة إضافة معالج أهداف غير مفعَّل، كما هو موضّح في المقتطف التالي:

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

لإيقاف عناصر intent بشكل مجمّع، يمكنك استخدام طريقة clearExpectations() التي تعمل على إيقاف جميع عناصر intent المفعّلة حاليًا. يوضِّح المقتطف التالي كيفية توضيح التوقعات لجميع معالِجات الأهداف:

interactiveCanvas.clearExpectations();

مقبض ملء خانة العميل

بدلاً من إضافة ملء الخانة إلى مشهد ضمن "أداة إنشاء الإجراءات"، يمكنك التعامل مع ملء الخانة مباشرةً في تطبيق الويب.

للتعامل مع ملء الفتحة من جهة العميل، يجب أولاً إنشاء خانة باستخدام إحدى واجهات برمجة التطبيقات التالية:

  • createNumberSlot(callback, hints): طريقة تسمح لك بتحديد خانة أرقام في رمز تطبيق الويب يتم استخدامه لمطالبة المستخدم برقم.
  • createTextSlot(callback, hints): طريقة تسمح لك بتحديد شريحة نصية في رمز تطبيق الويب. يتم استخدامها لمطالبة المستخدم بكلمة ما.
  • createConfirmationSlot(callback, hints): طريقة تسمح لك بتحديد خانة تأكيد في رمز تطبيق الويب يتم استخدامه لمطالبة المستخدم بالتأكيد (نعم/لا).
  • createOptionsSlot(options, callback, hints): طريقة تسمح لك بتحديد خانة خيارات في رمز تطبيق الويب يتم استخدامه لمطالبة المستخدم بالاختيار من قائمة الخيارات المحددة مسبقًا.

عند إنشاء خانة، يمكنك اختياريًا تحديد triggerHints، وهي كلمات رئيسية تحسِّن نظام فهم اللغات الطبيعية (NLU) لتنفيذ الإجراء الخاص بك. يجب أن تكون هذه الكلمات الرئيسية كلمات قصيرة قد يقولها المستخدم عند ملء خانة. على سبيل المثال، قد تكون الكلمة الرئيسية triggerHints الخاصة بخانة رقمية هي years. عندما يردّ مستخدم على سؤال حول عمره في المحادثة والإجابة "أنا أبلغ من العمر ثلاثين عامًا"، سيُدرك الإجراء الخاص بك أنّ المستخدم يملأ الخانة بشكل مناسب.

بعد إنشاء خانة، يمكنك توجيه المستخدم لإنشاء خانة باستخدام واجهة برمجة التطبيقات prompt:

  • prompt(tts, slot): طريقة تُخرج المستخدم من تقنية "تحويل النص إلى كلام" وتطلب منه ملء خانة متوقعة.

يؤدي استدعاء الرقم prompt() إلى عرض وعد يتضمن حالة وقيمة الخانة المعبأة.

إنشاء خانة رقم

تتيح لك خانة الأرقام مطالبة المستخدم بإدخال رقم أثناء المحادثة. لمزيد من المعلومات حول ملء الخانات، راجِع القسم تعبئة الشرائح في مستندات "أداة إنشاء الإجراءات".

لتوجيه طلب إلى المستخدم بملء خانة أرقام من جهة العميل، يُرجى اتّباع الخطوات التالية:

  1. استدعِ الطريقة createNumberSlot() لإنشاء خانة رقم في منطق تطبيق الويب لديك:

    /**
     * Create number slot.
     */
    const triggerHints = { associatedWords: ['guess number', 'number'] };
    const slot = interactiveCanvas.createNumberSlot(
      number => {
        console.log(`Number guessed: ${number}.`);
      }, triggerHints);
    
    
  2. ويمكنك استدعاء الطريقة prompt() لطلب إدخال الخانة من المستخدم، والتعامل مع قيمة الشريحة من الوعد المعروض، كما هو موضّح في المقتطف التالي:

    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);
        }
      });
    

إنشاء خانة نص

تتيح لك خانة النص مطالبة المستخدم بكلمة ما أثناء المحادثة. لمزيد من المعلومات حول ملء الخانات، راجِع القسم تعبئة الشرائح في مستندات "أداة إنشاء الإجراءات".

لمطالبة المستخدم بملء خانة نصية من جهة العميل، اتّبِع الخطوات التالية:

  1. استدعِ طريقة createTextSlot() لإنشاء خانة نص في منطق تطبيق الويب لديك:

    /**
     * Create text slot.
     */
    const triggerHints = { associatedWords: ['favorite color', 'color'] };
    const slot = interactiveCanvas.createTextSlot(
      text => {
        console.log(`Favorite color: ${text}.`);
      }, triggerHints);
    
    
  2. ويمكنك استدعاء الطريقة prompt() لطلب إدخال الخانة من المستخدم، والتعامل مع قيمة الشريحة من الوعد المعروض، كما هو موضّح في المقتطف التالي:

    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);
        }
      });
    

إنشاء خانة تأكيد

تتيح لك خانة التأكيد مطالبة المستخدم بالتأكيد (يمكن للمستخدم الرد بـ "نعم" أو "لا" لملء الخانة). لمزيد من المعلومات حول ملء الخانات، راجِع القسم تعبئة الشرائح في مستندات "أداة إنشاء الإجراءات".

لمطالبة المستخدم بملء خانة تأكيد من جانب العميل، اتّبِع الخطوات التالية:

  1. استدعِ طريقة createConfirmationSlot() لإنشاء خانة تأكيد في منطق تطبيق الويب لديك:

    /**
     * Create confirmation slot (boolean).
     */
    const triggerHints = { associatedWords: ['user confirmation', 'confirmation'] };
    const slot = interactiveCanvas.createConfirmationSlot(
      yesOrNo => {
        console.log(`Confirmation: ${yesOrNo}`);
      }, triggerHints);
    
    
  2. ويمكنك استدعاء الطريقة prompt() لطلب إدخال الخانة من المستخدم، والتعامل مع قيمة الشريحة من الوعد المعروض، كما هو موضّح في المقتطف التالي:

    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);
        }
      });
    

إنشاء خانة خيارات

تتيح لك خانة الخيارات مطالبة المستخدم بالاختيار من قائمة خيارات محدّدة مسبقًا. لمزيد من المعلومات حول ملء الخانات، راجِع القسم تعبئة الشرائح في مستندات "أداة إنشاء الإجراءات".

لمطالبة المستخدم بملء خانة خيارات من جهة العميل، اتبع الخطوات التالية:

  1. استدعِ طريقة 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);
    
    
  2. ويمكنك استدعاء الطريقة prompt() لطلب إدخال الخانة من المستخدم، والتعامل مع قيمة الشريحة من الوعد المعروض، كما هو موضّح في المقتطف التالي:

    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() الانتقال إلى مشهد آخر في "إجراء لوحة الرسم التفاعلي" من خلال عملية التنفيذ من جهة العميل. باستخدام triggerScene()، يمكنك أيضًا التبديل من التنفيذ من جهة العميل إلى التنفيذ من جهة الخادم عندما يحتاج المستخدم إلى الوصول إلى مشهد نظام في "أداة إنشاء الإجراءات" الذي يتطلّب ردًّا تلقائيًا على الويب. على سبيل المثال، يمكنك الاتصال بـ 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.");
})

مساحة تخزين الصفحة الرئيسية والمستخدم على البرنامج

بدلاً من استخدام الرد التلقائي على الويب للحصول على قيم مساحة تخزين المنزل وسعة التخزين وضبطها، يمكنك استدعاء واجهات برمجة التطبيقات من جهة العميل للتعامل مع مساحة تخزين المنزل ومساحة تخزين المستخدم في تطبيق الويب. ويمكن لتطبيق الويب بعد ذلك استخدام هذه القيم المخزَّنة في جلسات متعدّدة (على سبيل المثال، في الطلبات والشروط)، ويمكنه الوصول إلى القيم لأسرة معيّنة أو مستخدم معيّن عند الحاجة. يمكن أن يؤدي استخدام واجهات برمجة التطبيقات هذه إلى تقليل وقت الاستجابة في "إجراء لوحة الرسم التفاعلية" لأنك لم تعد بحاجة إلى طلب رد تلقائي على الويب للحصول على قيم مساحة التخزين وضبطها.

تتبع مساحة تخزين الصفحة الرئيسية والمستخدم في تطبيق الويب المبادئ العامة نفسها مثل التخزين في الرد التلقائي على الويب. لمزيد من المعلومات حول مساحة التخزين في المنزل ومساحة التخزين التابعة للمستخدم، يمكنك الاطّلاع على مستندات التخزين في المنزل ومساحة تخزين المستخدم.

مساحة تخزين منزلية من جهة العميل

تسمح لك مساحة التخزين في المنزل بتخزين قيم للمستخدمين في المنزل استنادًا إلى الرسم البياني للمنزل، وتتم مشاركة هذه القيم على مستوى جميع جلسات المنزل. على سبيل المثال، إذا لعب المستخدم إحدى ألعاب "لوحة الرسم التفاعلية" في المنزل، فيمكن تخزين نتيجة اللعبة في تخزين منزلي، ويمكن لأفراد الأسرة الآخرين مواصلة اللعب بالنتيجة المخزَّنة.

لتفعيل الإجراء الخاص بك لإتاحة مساحة التخزين في المنزل، يُرجى اتّباع الخطوات التالية:

  1. في وحدة تحكُّم الإجراءات، انتقِل إلى نشر > معلومات الدليل > معلومات إضافية.
  2. ضَع علامة في المربّع نعم بجانب السؤال هل تُستخدَم إجراءاتك في مساحة التخزين المنزلية؟

لكتابة قيمة للتخزين المنزلي في تطبيق الويب، يمكنك استدعاء الطريقة 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);
      }
  );

لمحو جميع مساحات التخزين المنزلية الحالية، يمكنك استدعاء الطريقة 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() بإرسال بيانات الحالة من تطبيق الويب Interactive Canvas إلى عملية التنفيذ، وتُعلم "مساعد Google" بأنّ تطبيق الويب قد عدّل حالته. يرسل تطبيق الويب حالته المعدّلة ككائن JSON.

ولا يؤدي الاتصال بالرقم setCanvasState() إلى تفعيل هدف. بعد استدعاء setCanvasState()، إذا تم استدعاء sendTextQuery() أو تطابق طلب بحث المستخدم مع هدف في المحادثة، تصبح البيانات التي تم ضبطها باستخدام setCanvasState() في دور المحادثة السابقة متاحة في المراحل اللاحقة من المحادثة.

في المقتطف التالي، يستخدم تطبيق الويب setCanvasState() لضبط بيانات حالة لوحة الرسم:

JavaScript

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

الإشارة إلى حالة لوحة الرسم من الردّ التلقائي على الويب

يمكنك الإشارة إلى قيم حالة لوحة الرسم المخزّنة في رمز التنفيذ. للإشارة إلى القيمة، استخدِم بنية conv.context.canvas.state.KEY، حيث يكون KEY هو المفتاح المعطى عند ضبط قيمة حالة لوحة الرسم.

على سبيل المثال، إذا سبق لك تخزين قيمة أعلى نتيجة لإحدى الألعاب في حالة لوحة الرسم كمَعلمة score، أشِر إلى هذه القيمة باستخدام conv.context.canvas.state.score للوصول إلى تلك القيمة في عملية التنفيذ:

Node.js

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

حالة لوحة الرسم المرجعية في الطلبات

يمكنك الإشارة إلى قيم حالة لوحة الرسم المخزّنة في طلب. للإشارة إلى القيمة، استخدِم بنية $canvas.state.KEY، حيث يكون KEY هو المفتاح المعطى عند ضبط قيمة حالة لوحة الرسم.

على سبيل المثال، إذا سبق لك تخزين قيمة أعلى نتيجة لإحدى الألعاب في حالة لوحة الرسم كمَعلمة score، أشِر إلى هذه القيمة باستخدام $canvas.state.score للوصول إلى تلك القيمة في طلب:

تنسيق JSON

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

حالة لوحة الرسم المرجعية ضمن الشروط

يمكنك أيضًا الإشارة إلى قيم حالة لوحة الرسم المخزنة في الشروط. للإشارة إلى القيمة، استخدم بناء الجملة canvas.state.KEY، حيث يكون KEY هو المفتاح المعطى عند تعيين قيمة حالة لوحة الرسم.

على سبيل المثال، إذا سبق لك تخزين قيمة أعلى نتيجة للعبة في حالة لوحة الرسم على أنّها المعلَمة score، وأردت مقارنتها بالقيمة 999 في شرط معيّن، يمكنك الإشارة إلى القيمة المخزّنة في شرطك باستخدام canvas.state.score. يبدو تعبير الشرط كما يلي:

بنية الشرط

canvas.state.score >= 999
    

sendTextQuery()

ترسل الطريقة sendTextQuery() طلبات بحث نصية إلى "إجراء المحادثة" لمطابقة هدف معيّن آليًا. يستخدم هذا النموذج sendTextQuery() لإعادة تشغيل لعبة الدوران المثلث عندما ينقر المستخدم على زر. عندما ينقر المستخدم على زر "إعادة تشغيل اللعبة"، يرسل sendTextQuery() طلب بحث نصيًا يطابق هدف Restart game ويعرض وعدًا. ينتج عن هذا الوعد SUCCESS في حال تم تفعيل الغرض و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;
},
…
    

إنشاء باستخدام التنفيذ من جهة الخادم

يمكنك تنفيذ واجهات برمجة تطبيقات لوحة الرسم التفاعلية التالية في الرد التلقائي على الويب:

تفعيل وضع ملء الشاشة

تتضمّن تطبيقات الويب "لوحة الرسم التفاعلية" تلقائيًا عنوانًا في أعلى الشاشة يحمل اسم الإجراء الخاص بك. يمكنك استخدام enableFullScreen لإزالة العنوان واستبداله برمز نخب مؤقت يظهر على شاشة التحميل، ما يتيح للمستخدم توفير تجربة في وضع ملء الشاشة أثناء التفاعل مع الإجراء الخاص بك. تعرض رسالة الإشعار السريع الاسم المعروض للإجراء، واسم مطوّر البرامج، وتعليمات الخروج من الإجراء، ويتغير لون اللون المنبعث بناءً على ما يختاره المستخدم كمظهر على جهازه.

الشكل 1. رسالة نخب على شاشة التحميل لتنفيذ إجراء.

إذا كان المستخدم يتفاعل مع الإجراء الخاص بك بشكل متكرر، ستتوقف رسالة الإشعار السريع عن الظهور مؤقتًا على شاشة التحميل. وإذا لم يتفاعل المستخدم مع الإجراء الخاص بك لفترة من الوقت، ستظهر رسالة نخب الجمهور مرة أخرى عند تشغيل الإجراء.

يمكنك تفعيل وضع ملء الشاشة في الرد التلقائي على الويب أو في طلب ثابت في "أداة إنشاء الإجراءات".

لتفعيل وضع ملء الشاشة في الرد التلقائي على الويب، اتّبِع الخطوة التالية:

  1. اضبط الحقل 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);
    

لتفعيل وضع ملء الشاشة في طلب ثابت في "أداة إنشاء الإجراءات"، اتّبِع الخطوات التالية:

  1. افتح مشروعك في وحدة تحكُّم "المهام".
  2. انقر على تطوير في شريط التنقّل وافتح الطلب الذي يتضمّن أول canvas استجابة.
  3. اضبط enable_full_screen على true، كما هو موضَّح في المقتطف التالي:

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

continueTtsDuringTouch

بشكل افتراضي، عندما ينقر المستخدم على الشاشة أثناء استخدام إجراء لوحة الرسم التفاعلية، يتوقف تشغيل تقنية TTS. يمكنك تفعيل تقنية TTS لمتابعة التشغيل عندما يلمس المستخدمون الشاشة باستخدام continueTtsDuringTouch. لا يمكن تفعيل هذا السلوك أو إيقافه في الجلسة نفسها.

يمكنك تنفيذ هذا السلوك في الرد التلقائي على الويب أو في طلب ثابت في "أداة إنشاء الإجراءات".

لتفعيل تقنية 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 بعد أن ينقر المستخدم على الشاشة في أمر ثابت في "أداة إنشاء الإجراءات"، يُرجى اتّباع الخطوات التالية:

  1. افتح مشروعك في وحدة تحكُّم "المهام".
  2. النقر على تطوير في شريط التنقّل وفتح رسالة المطالبة التي تتضمّن أول استجابة canvas
  3. اضبط continue_tts_during_touch على true، كما هو موضَّح في المقتطف التالي:

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