لإرسال المعلومات إلى تطبيق الويب، يجب إرسال ردّ Canvas
من منطقك الحواري. يمكن لاستجابة Canvas
تنفيذ أحد الإجراءات التالية:
- عرض تطبيق الويب في وضع ملء الشاشة على جهاز المستخدم
- تمرير البيانات لتحديث تطبيق الويب
تصف الأقسام التالية كيفية عرض استجابة لوحة رسم لكل سيناريو.
تفعيل ميزة "لوحة الرسم التفاعلية"
يجب إعداد الإجراء الخاص بك بطريقة معيّنة لاستخدام "لوحة الرسم التفاعلية".
إنّ إنشاء إجراء يستخدم "لوحة الرسم التفاعلية" يتطلّب ضبطًا
إضافيًا في "وحدة تحكُّم المهام" (وتعديلات ملف settings.yaml
لحزمة "المهام مع مساعد Google"). للاطّلاع على الإجراء الكامل لإنشاء "إجراء لوحة رسم تفاعلي"
وإعداده باستخدام حزمة تطوير البرامج (SDK) للإجراءات، يمكنك الاطّلاع على مقالة
إنشاء مشروع.
عند استخدام أداة إنشاء الإجراءات، اتبع هذه الخطوات الإضافية لتفعيل لوحة الرسم التفاعلية:
- إذا لم تختَر بطاقة اللعبة في شاشة ما نوع الإجراء الذي تريد إنشاءه؟، انقر على نشر في شريط التنقّل العلوي. ضمن معلومات إضافية، اختَر فئة الألعاب والمرح. انقر على حفظ.
- انقر على تطوير في شريط التنقّل العلوي في "وحدة تحكّم المهام".
- انقر على لوحة رسم تفاعلية في شريط التنقل الأيمن.
- ضمن القسم هل تريد أن يستخدم الإجراء الخاص بك "لوحة الرسم التفاعلية"؟، اختَر أحد الخيارات التالية:
- تفعيل "لوحة الرسم التفاعلية" مع تنفيذ الرد التلقائي على الويب للخادم يعتمد هذا الخيار
على الرد التلقائي على الويب للوصول إلى ميزات معيّنة، كما يستخدم بشكلٍ متكرر
onUpdate()
لتمرير البيانات إلى تطبيق الويب. عندما يكون هذا الخيار مفعّلاً، تتم معالجة مطابقات الأهداف في المشاهد، ويمكنك اختيار استدعاء الردّ التلقائي على الويب قبل الانتقال إلى مشهد آخر أو إنهاء المحادثة. - تفعيل "لوحة الرسم التفاعلية" من خلال توفير المتطلبات اللازمة للعميل: يسمح لك هذا الخيار
بنقل منطق تنفيذ الردّ التلقائي على الويب إلى تطبيق الويب، وقصر
طلبات الردّ التلقائي على الويب على ميزات المحادثة التي تتطلّبها فقط،
مثل ربط الحساب. عند تفعيل هذا الإعداد، يمكنك استخدام
expect()
لتسجيل معالِجات الأهداف من جهة العميل.
- تفعيل "لوحة الرسم التفاعلية" مع تنفيذ الرد التلقائي على الويب للخادم يعتمد هذا الخيار
على الرد التلقائي على الويب للوصول إلى ميزات معيّنة، كما يستخدم بشكلٍ متكرر
- اختياري: أدخِل عنوان URL لتطبيق الويب في الحقل ضبط عنوان URL التلقائي لتطبيق الويب. يؤدي هذا الإجراء إلى إضافة ردّ
Canvas
تلقائي مع حقل عنوان URL إلى استدعائك الرئيسي. - انقر على حفظ.
عند استخدام حزمة تطوير البرامج (SDK) للإجراءات، يُرجى اتّباع الخطوات الإضافية التالية لتفعيل لوحة الرسم التفاعلية:
- اضبط الحقل
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
مباشرةً بعد استدعاء المستخدم للإجراء الخاص بك. عند تحميل تطبيق الويب، يتم تحميل مكتبة لوحة الرسم التفاعلية، ويسجّل تطبيق الويب معالج معاودة الاتصال باستخدام واجهة برمجة التطبيقات التفاعلية للوحة الرسم.
يمكنك تحديد عنوان 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
.
توضّح الأقسام التالية كيفية تمرير البيانات من خلال "أداة إنشاء الإجراءات" ومن خلال ردّ تلقائي على الويب.
استخدام "أداة إنشاء الإجراءات" لتمرير البيانات
باستخدام "أداة إنشاء الإجراءات"، لا تحتاج إلى تعريف ردّ تلقائي على الويب لإدارة البيانات الوصفية
التي يتم إرسالها إلى تطبيق الويب. وبدلاً من ذلك، عند ضبط معالج الغرض في
واجهة مستخدم "أداة إنشاء الإجراءات"، يمكنك تضمين ردّ Canvas
. تتم تعبئة حقل data
تلقائيًا بالبيانات الوصفية اللازمة لتعديل
تطبيق الويب الخاص بك، مثل اسم الغرض وأي معلَمات تم الحصول عليها من البيانات التي أدخلها المستخدم
والمشهد الحالي.
على سبيل المثال، يشير معالج الأهداف Guess
التالي إلى أنّك تريد تضمين استجابة Canvas
:
YAML
candidates: - canvas: send_state_data_to_canvas_app: true
تنسيق JSON
{ "candidates": [ { "canvas": { "send_state_data_to_canvas_app": true } } ] }
يمكنك اختياريًا إلحاق المقتطف التالي بمعالج الأهداف لإرسال رسالة 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 كيلوبايت أو أصغر.