عمليات معاودة الاتصال

يمكنك تنفيذ عمليات الاستدعاء التالية في مهمة لوحة الرسم التفاعلية:

onUpdate()

تعمل ميزة onUpdate()"معاودة الاتصال" على تمرير بيانات من الرد التلقائي على الويب إلى تطبيق الويب لتعديل تطبيق الويب بشكلٍ مناسب. يجب عدم استخدام معاودة الاتصال هذه إلا مع نموذج التنفيذ من جهة الخادم لتطوير "لوحة الرسم التفاعلية".

للحصول على مزيد من المعلومات حول "onUpdate()"، يُرجى الاطّلاع على مقالة تمرير البيانات لتحديث تطبيق الويب.

onTtsMark()

يتم استدعاء استدعاء onTtsMark() عندما تتم قراءة علامات <mark> المخصّصة المضمّنة في لغة ترميز تركيب الكلام (SSML) على ردك أثناء القراءة أثناء تشغيل ميزة "تحويل النص إلى كلام" (TTS). يمكنك استخدام onTtsMark() في كل من نماذج تطوير التنفيذ من جهة الخادم ومن جهة العميل.

في المقتطفات التالية، يتزامن onTtsMark() مع الصورة المتحركة لتطبيق الويب مع مخرجات TTS المقابلة. عندما يقول الإجراء للمستخدم: "عذرًا، لقد فقدت"، يكتب تطبيق الويب الكلمة الصحيحة ويعرض الحروف للمستخدم.

ملاحظة: لا تعمل النقاط الزمنية في الوقت الحالي مع علامة SSML <break>.

في المثال التالي، يتضمّن معالج الرد التلقائي على الويب revealWord علامة مخصّصة في الردّ على المستخدم عند فقدان اللعبة:

JavaScript

…
app.handle('revealWord', conv => {
  conv.add(new Simple(`<speak>Sorry, you lost.<mark name="REVEAL_WORD"/> The word is ${conv.session.params.word}.</speak>`));
  conv.add(new Canvas());
});
…
    

بعد ذلك، يسجِّل مقتطف الرمز التالي استدعاء onTtsMark()، ويتحقّق من اسم العلامة، وينفّذ دالة revealCorrectWord() التي تحدّث تطبيق الويب:

JavaScript

…
setCallbacks() {
    // declare Assistant Canvas Action callbacks
    const callbacks = {
        onTtsMark(markName) {
            if (markName === 'REVEAL_WORD') {
                // display the correct word to the user
                that.revealCorrectWord();
            }
        },
    }
    callbacks.onUpdate.bind(this);
}
…
    

onInputStatusChanged()

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

يتم إعلامك من خلال معاودة الاتصال onInputStatusChanged() عندما تتغير حالة الإدخال في "إجراء لوحة الرسم التفاعلية". تشير تغييرات حالة الإدخال إلى الحالات التي يفتح فيها الميكروفون ويغلقه أو عندما يعالج "مساعد Google" طلبًا معيّنًا. يمكن أن تؤدي الأحداث التالية إلى تغيير حالة الإدخال:

• المستخدم الذي يتحدث إلى الإجراء الخاص بك
• المستخدم الذي يُدخل النص على تطبيق "بحث Google" لأجهزة Android (AGSA)
• تطبيق الويب الذي يستخدم sendTextQuery() API لإرسال طلب بحث نصي إلى الإجراء
• الإجراء المتعلّق بالكتابة في مساحة التخزين المنزلية وأحداث أخرى في "مساعد Google"

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

تعرض واجهة برمجة التطبيقات هذه الحالات التالية:

• يشير الرمز LISTENING إلى أن الميكروفون مفتوح.
• IDLE: يشير إلى أن الميكروفون مغلق.
• PROCESSING: يشير إلى أنّ "مساعد Google" ينفّذ حاليًا طلب بحث وأنّ الميكروفون مغلق.

وتُبلغ واجهة برمجة التطبيقات عن حالة الإدخال في الإجراء الخاص بك كلما تغيّرت الحالة.

في حين أنه من الممكن حدوث أي انتقال بين الحالات، فإن التدفقات التالية شائعة:

• IDLE>LISTENING>PROCESSING>IDLE - يقول المستخدم طلب بحث، تتم معالجة طلب البحث، ويتم إغلاق الميكروفون.
• IDLE>PROCESSING>IDLE - يستخدم تطبيق الويب sendTextQuery() API لإرسال طلب بحث نصي إلى الإجراء.
• IDLE>LISTENING>IDLE - يفتح المستخدم الميكروفون بدون قول طلب بحث.

لاستخدام هذه الميزة في الإجراء الخاص بك، أضِف onInputStatusChanged() إلى رمز تطبيق الويب، كما هو موضّح في المقتطف التالي:

onInputStatusChanged(inputStatus) {
   console.log("The new input status is: ", inputStatus);
}

تمرّر استدعاء onInputStatusChanged() معلَمة تعداد واحدة، inputStatus. يمكنك التحقّق من هذه القيمة للاطّلاع على حالة الإدخال الحالي. يمكن أن يكون inputStatus LISTENING أو PROCESSING أو IDLE.

أضِف بعد ذلك onInputStatusChanged() إلى الكائن callbacks لتسجيله، كما هو موضّح في المقتطف التالي:

 /**
  * Register all callbacks used by the Interactive Canvas Action
  * executed during game creation time.
  */
 setCallbacks() {
   const that = this;
   // Declare the Interactive Canvas action callbacks.
   const callbacks = {
     onUpdate(data) {
       console.log('Received data', data);
     },
     onInputStatusChanged(inputStatus) {
       console.log("The new input status is: ", inputStatus);
     },
   };
   // Called by the Interactive Canvas web app once web app has loaded to
   // register callbacks.
   this.canvas.ready(callbacks);
 }
}