لإرسال المعلومات إلى تطبيق الويب، يجب إرسال ردّ Canvas
.
من منطق المحادثة. يمكن لاستجابة Canvas
تنفيذ أي مما يلي:
- عرض تطبيق الويب بملء الشاشة على جهاز المستخدم
- نقل البيانات لتحديث تطبيق الويب
توضح الأقسام التالية كيفية عرض رد لوحة رسم لكل السيناريو.
تفعيل ميزة "لوحة الرسم التفاعلية"
يجب تهيئة الإجراء الخاص بك بطريقة معينة لاستخدام لوحة الرسم التفاعلية.
يتطلب إنشاء إجراء يستخدم لوحة الرسم التفاعلية
الضبط في وحدة تحكُّم المهام (وبالنسبة إلى حزمة تطوير البرامج للإجراءات، قد يتم إجراء تعديلات على
ملف settings.yaml
). للاطلاع على الإجراء الكامل لإنشاء
تهيئة إجراء لوحة رسم تفاعلي باستخدام حزمة تطوير برامج المهام، راجع
أنشئ مشروعًا.
عند استخدام "أداة إنشاء المهام"، اتّبِع هذه الخطوات الإضافية لتفعيل ميزة "أداة إنشاء المهام التفاعلية". لوحة الرسم:
- إذا لم تختَر بطاقة اللعبة في القسم ما نوع الإجراء؟ التي تريد إنشاءها؟ انقر على نشر في شريط التنقل العلوي. ضِمن معلومات إضافية، اختَر الألعاب المرح". انقر على حفظ.
- انقر على تطوير في شريط التنقّل العلوي في وحدة تحكّم "المهام".
- انقر على لوحة الرسم التفاعلية في شريط التنقل الأيمن.
- ضمن هل تريد أن يستخدم الإجراء "لوحة الرسم التفاعلية"، اختَر أحد
ما يلي:
- تفعيل لوحة الرسم التفاعلية مع تنفيذ الرد التلقائي على الويب للخادم. هذا الخيار
يعتمد على الرد التلقائي على الويب للوصول إلى ميزات معينة، ويستخدم بشكل متكرر
onUpdate()
لتمرير البيانات إلى تطبيق الويب. عند تفعيل هذه الميزة، تكون مطابقات الأهداف يتم التعامل معها في مشاهد، ويمكنك اختيار طلب الرد التلقائي على الويب قبل الانتقال إلى مشهد آخر أو إنهاء المحادثة. - تفعيل ميزة "لوحة الرسم التفاعلية" التفاعلية مع عملية تنفيذ العميل ويسمح هذا الخيار
نقل منطق تنفيذ الرد التلقائي على الويب إلى تطبيق الويب، وتقييد
فإن الرد التلقائي على الويب يستدعي فقط ميزات المحادثة التي تتطلبها،
مثل ربط الحسابات عند تفعيل هذا الإعداد، يمكنك استخدام
expect()
لإجراء ما يلي: تسجيل معالجات الأهداف من جانب العميل.
- تفعيل لوحة الرسم التفاعلية مع تنفيذ الرد التلقائي على الويب للخادم. هذا الخيار
يعتمد على الرد التلقائي على الويب للوصول إلى ميزات معينة، ويستخدم بشكل متكرر
- اختياري: أدخِل عنوان URL لتطبيق الويب في الحقل ضبط عنوان URL لتطبيق الويب التلقائي.
. يؤدي هذا الإجراء إلى إضافة استجابة
Canvas
تلقائية مع حقل عنوان URL إلى استدعاؤك الرئيسي. - انقر على حفظ.
عند استخدام حزمة تطوير برامج المهام، اتّبِع هذه الخطوات الإضافية لتفعيل ميزة "الإعلانات التفاعلية" لوحة الرسم:
- اضبط الحقل
category
في ملفsettings.yaml
علىGAMES_AND_TRIVIA
. لتقديم أفضل وصف ومساعدة المستخدمين على اكتشاف الإجراء الخاص بك. - اضبط الحقل
usesInteractiveCanvas
في ملفsettings.yaml
علىtrue
.
التحقّق من سعة الأسطح
لا يتم تشغيل إطار عمل "لوحة الرسم التفاعلية" إلا على الأجهزة المزوّدة بخدمة "مساعد Google".
واجهة مرئية، لذلك يحتاج الإجراء إلى التحقق من INTERACTIVE_CANVAS
الإمكانات على جهاز المستخدم. عند تعريف الطلبات في "أداة إنشاء المهام"،
يمكنك تحديد قائمة بإمكانيات الجهاز في الحقل selector
من
كائن candidates
. تختار أداة اختيار الطلب المرشّح الأكثر طلبًا
تناسب قدرة جهاز المستخدم.
لعرض ردّ Canvas
، يجب اتّباع الإجراءات المنطقية في الإجراء التالي:
- تحقَّق من أنّ جهاز المستخدم يتوافق مع ميزة
INTERACTIVE_CANVAS
. في حال حذف يمكنه إرسال ردّ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.'); }
عرض تطبيق الويب
يتضمن الإجراء الذي يستخدم لوحة الرسم التفاعلية تطبيق ويب به والعناصر المرئية التي ترسلها إلى المستخدمين كرد. بمجرد عرض تطبيق الويب، يحتاج المستخدمون مواصلة التفاعل معها من خلال الصوت أو النص أو اللمس حتى انتهت المحادثة.
يجب أن يحتوي أول ردّ Canvas
على عنوان URL لتطبيق الويب. هذا النوع من
ردّ Canvas
يطلب من "مساعد Google" عرض تطبيق الويب على ذلك العنوان
على جهاز المستخدم. يتم إرسال أول Canvas
رد في العادة
مباشرةً بعد استدعاء المستخدم للإجراء. عند تحميل تطبيق الويب،
يتم تحميل مكتبة لوحة الرسم التفاعلية، ويسجِّل تطبيق الويب معالِج معاودة الاتصال
باستخدام واجهة برمجة تطبيقات Canvas التفاعلية.
ويمكنك تحديد عنوان URL لتطبيق الويب في "أداة إنشاء المهام"، كما هو موضّح في القسم لقطة الشاشة التالية:
إذا أنشأت طلبًا يتضمّن ردّ Canvas
بعد تحديد
عنوان URL لتطبيق الويب، تملأ أداة إنشاء الإجراءات حقل عنوان URL لاستجابة Canvas
تلقائيًا. لمزيد من المعلومات،
معلومات حول إعداد عنوان URL لتطبيق الويب في وحدة التحكم، راجع
قسم تفعيل لوحة الرسم التفاعلية.
توضِّح المقتطفات التالية كيفية إنشاء استجابات Canvas
يتم عرضها
تطبيق الويب في كل من "أداة إنشاء المهام" والردّ التلقائي على الويب:
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
صالح
البيانات إلى تطبيق الويب، تحدث الخطوات التالية:
- عندما تتم مطابقة الهدف ضمن مشهد، يؤدي ذلك إلى بدء حدث وعرض استجابة
Canvas
. بعد ذلك، يتم إرسال الحقل الذي يحتوي على الحقلdata
مع حمولة JSON كاستجابة. - يتم تمرير الحقل
data
إلى معاودة الاتصالonUpdate
واستخدامه لتعديل تطبيق الويب. يمكن للإجراء الحواري إرسال رد
Canvas
جديد وتوفير المعلومات في الحقلdata
لإرسال تحديثات جديدة أو تحميل حالات جديدة.
يمكنك تمرير البيانات إلى تطبيق الويب بطريقتين:
- باستخدام "أداة إنشاء المهام". تملأ أداة إنشاء الإجراءات الحقل
data
تلقائيًا في استجابةCanvas
مع البيانات الوصفية اللازمة لتحديث تطبيق الويب. - باستخدام ردّ تلقائي على الويب. إذا كان لديك ردّ تلقائي على الويب، يمكنك ضبط بيانات مخصّصة.
لتحديث تطبيق الويب في استجابة
Canvas
.
توضّح الأقسام التالية كيفية تمرير البيانات من خلال "أداة إنشاء المهام" الرد التلقائي على الويب.
استخدام "أداة إنشاء المهام" لتمرير البيانات
باستخدام "أداة إنشاء المهام"، لا تحتاج إلى تحديد ردّ تلقائي على الويب لإدارة البيانات الوصفية.
التي يتم إرسالها إلى تطبيق الويب. بدلاً من ذلك، عند تهيئة معالج intent في
واجهة مستخدم "أداة إنشاء المهام"، يمكنك تضمين ردّ Canvas
. حاسمة
تتم تعبئة حقل data
تلقائيًا بالبيانات الوصفية اللازمة لتعديلها.
لتطبيق الويب، مثل اسم الغرض، وأي معلمات تم الحصول عليها من إدخالات المستخدم،
والمشهد الحالي.
على سبيل المثال، يشير معالج النية 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.
تعمل "أداة إنشاء المهام" تلقائيًا على توسيع نطاق استجابة 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
.
عند إنشاء الإجراء:
- يجب أن يحتوي كل معالِج للردّ التلقائي على الويب في التنفيذ على
Canvas
. إذا كان الرد التلقائي على الويب لا يتضمّن الردّCanvas
، سيتم إغلاق تطبيق الويب. - ما عليك سوى تضمين عنوان URL لتطبيق الويب في أول استجابة
Canvas
. ترسلها إلى المستخدم. - يجب أن يكون عنوان URL للاستجابة
Canvas
صالحًا وأن يكون بروتوكوله هو https. - يجب أن يكون حجم استجابة
Canvas
50 كيلوبايت أو أصغر.