يُرجى استخدام ردّ مرئي إذا أردت أن يختار المستخدم خيارًا واحدًا من بين عدّة خيارات ليتابع تنفيذ الإجراء الخاص بك. يمكنك استخدام أنواع ردود الاختيار المرئي كجزء من الطلب:
- قائمة
- المجموعة
- تصفُّح المجموعات
عند تحديد إجابة اختيار مرئي، استخدِم مرشحًا مع مساحة العرض RICH_RESPONSE
بحيث يعرض "مساعد Google" الاستجابة فقط على الأجهزة المتوافقة. لا يمكنك استخدام سوى استجابة منسّقة واحدة لكل عنصر content
في الطلب.
إضافة رد اختيار مرئي
تستخدم ردود الاختيار المرئي تعبئة الفتحة في المشهد لتقديم الخيارات التي يمكن للمستخدم تحديدها والتعامل مع عنصر محدد. عندما يختار المستخدمون عنصرًا، يمرِّر "مساعد Google" قيمة العنصر المحدّدة إلى الرد التلقائي على الويب كوسيطة. بعد ذلك، في قيمة الوسيطة، تتلقى المفتاح للعنصر المحدد.
قبل أن تتمكّن من استخدام ردّ اختيار مرئي، يجب تحديد نوع يمثّل الردّ الذي يختاره المستخدم لاحقًا. في الرد التلقائي على الويب، يمكنك إلغاء هذا النوع بالمحتوى الذي تريد عرضه للاختيار.
لإضافة رد تحديد مرئي إلى مشهد في أداة إنشاء الإجراءات، اتبع الخطوات التالية:
- في المشهد، أضِف فتحة إلى القسم تعبئة الفتحة.
- اختَر type (نوعًا) محدّدًا مسبقًا لردك على الاختيار المرئي وأدخِل اسمًا له. يستخدِم الرد التلقائي على الويب اسم الخانة هذا للإشارة إلى النوع لاحقًا.
- ضَع علامة في المربّع طلب الردّ التلقائي على الويب وأدخِل اسم معالِج الحدث في الردّ التلقائي على الويب الذي تريد استخدامه لردّ الاختيار المرئي.
- ضَع علامة في المربّع إرسال الطلبات.
- في الطلب، قدِّم محتوى JSON أو YAML المناسب استنادًا إلى ردّ الاختيار المرئي الذي تريد عرضه.
- في الرد التلقائي على الويب، اتّبِع الخطوات الواردة في التعامل مع العناصر المحدّدة.
يمكنك الاطّلاع على أقسام القائمة والجمع وتصفّح المجموعات أدناه للتعرّف على خصائص الطلبات المتاحة وأمثلة حول أنواع الإلغاء.
التعامل مع العناصر المحددة
تتطلب منك ردود الاختيار المرئي التعامل مع اختيار المستخدم في كود الرد التلقائي على الويب. عندما يختار المستخدِم شيئًا من ردّ اختيار مرئي، يملأ "مساعد Google" الخانة بهذه القيمة.
في المثال التالي، يتلقّى رمز الرد التلقائي على الويب الخيار المحدَّد ويخزّنه في متغيّر:
Node.js
app.handle('Option', conv => { // Note: 'prompt_option' is the name of the slot. const selectedOption = conv.session.params.prompt_option; conv.add(`You selected ${selectedOption}.`); });
تنسيق JSON
{ "responseJson": { "session": { "id": "session_id", "params": { "prompt_option": "ITEM_1" } }, "prompt": { "override": false, "firstSimple": { "speech": "You selected ITEM_1.", "text": "You selected ITEM_1." } } } }
قائمة
![مثال لردّ على اختيار قائمة على جهاز جوّال](https://developers.google.cn/static/assistant/conversational/images/list.png?authuser=5&hl=ar)
تقدّم القائمة للمستخدمين قائمة رأسية تضم عدة عناصر وتسمح لهم بتحديد أحدها باللمس أو بالإدخال الصوتي. عندما يختار المستخدم عنصرًا من القائمة، ينشئ "مساعد Google" طلب بحث للمستخدم (فقاعة محادثة) يتضمّن عنوان العنصر في القائمة.
تكون القوائم جيدة عندما يكون من المهم إزالة غموض الخيارات، أو عندما يحتاج المستخدم إلى الاختيار من بين الخيارات التي تحتاج إلى فحصها بالكامل. على سبيل المثال، إلى أي "بيتر" تريد التحدث إليه، بيتر جونس أم بيتر هانز؟
يجب أن تحتوي القوائم على عنصرَين على الأقل و30 عنصرًا كحدّ أقصى. يعتمد عدد العناصر التي يتم عرضها في البداية على جهاز المستخدم، ورقم البداية الشائع هو 10 عناصر.
إنشاء قائمة
عند إنشاء قائمة، تحتوي المطالبة فقط على مفاتيح لكل عنصر يمكن للمستخدم
اختياره. في الرد التلقائي على الويب، يمكنك تحديد العناصر التي تتوافق مع هذه المفاتيح استنادًا إلى النوع Entry
.
تتميز عناصر القائمة المصنَّفة ككائنات Entry
بخصائص العرض التالية:
- العنوان
- حجم الخط وحجمه الثابتَين
- الحد الأقصى للطول: سطر واحد (يتم اقتطاعه بعلامات حذف...)
- يجب أن يكون فريدًا (لإتاحة اختيار الصوت)
- الوصف (اختياري)
- حجم الخط وحجمه الثابتَين
- الحد الأقصى للطول: سطران (يتم اقتطاعه بعلامات حذف...)
- الصورة (اختيارية)
- الحجم: 48 × 48 بكسل
تتطلّب ردود الاختيار المرئي إلغاء النوع حسب اسم خانته باستخدام نوع وقت تشغيل في وضع TYPE_REPLACE
. في معالج أحداث الرد التلقائي على الويب،
أشِر إلى النوع المطلوب تجاهله حسب اسم الخانة (المحدد في
إضافة ردود الاختيار) في السمة name
.
بعد استبدال أحد الأنواع، يمثّل النوع الناتج قائمة العناصر التي يمكن للمستخدم الاختيار من بينها والتي يعرضها "مساعد Google".
أماكن إقامة
يحتوي نوع استجابة القائمة على الخصائص التالية:
الموقع | Type | المتطلب | الوصف |
---|---|---|---|
items |
مصفوفة ListItem |
مطلوبة | يمثّل عنصرًا في القائمة يمكن للمستخدمين اختياره. يحتوي كل ListItem على مفتاح مرتبط بنوع مُشار إليه في عنصر القائمة. |
title |
سلسلة | إجراء اختياري | عنوان نص عادي للقائمة، مقتصر على سطر واحد. وإذا لم يتم تحديد أي عنوان، سيتم تصغير ارتفاع البطاقة. |
subtitle |
سلسلة | إجراء اختياري | العنوان الفرعي للنص العادي في القائمة. |
نموذج التعليمات البرمجية
تحدِّد النماذج التالية محتوى الطلب في رمز الردّ التلقائي على الويب أو في استجابة JSON للردّ التلقائي على الويب. ومع ذلك، يمكنك بدلاً من ذلك تحديد محتوى الطلب في أداة إنشاء الإجراءات (مثل YAML أو JSON).
Node.js
const ASSISTANT_LOGO_IMAGE = new Image({ url: 'https://developers.google.com/assistant/assistant_96.png', alt: 'Google Assistant logo' }); app.handle('List', conv => { conv.add('This is a list.'); // Override type based on slot 'prompt_option' conv.session.typeOverrides = [{ name: 'prompt_option', mode: 'TYPE_REPLACE', synonym: { entries: [ { name: 'ITEM_1', synonyms: ['Item 1', 'First item'], display: { title: 'Item #1', description: 'Description of Item #1', image: ASSISTANT_LOGO_IMAGE, } }, { name: 'ITEM_2', synonyms: ['Item 2', 'Second item'], display: { title: 'Item #2', description: 'Description of Item #2', image: ASSISTANT_LOGO_IMAGE, } }, { name: 'ITEM_3', synonyms: ['Item 3', 'Third item'], display: { title: 'Item #3', description: 'Description of Item #3', image: ASSISTANT_LOGO_IMAGE, } }, { name: 'ITEM_4', synonyms: ['Item 4', 'Fourth item'], display: { title: 'Item #4', description: 'Description of Item #4', image: ASSISTANT_LOGO_IMAGE, } }, ] } }]; // Define prompt content using keys conv.add(new List({ title: 'List title', subtitle: 'List subtitle', items: [ { key: 'ITEM_1' }, { key: 'ITEM_2' }, { key: 'ITEM_3' }, { key: 'ITEM_4' } ], })); });
تنسيق JSON
{ "responseJson": { "session": { "id": "session_id", "params": {}, "typeOverrides": [ { "name": "prompt_option", "synonym": { "entries": [ { "name": "ITEM_1", "synonyms": [ "Item 1", "First item" ], "display": { "title": "Item #1", "description": "Description of Item #1", "image": { "alt": "Google Assistant logo", "height": 0, "url": "https://developers.google.com/assistant/assistant_96.png", "width": 0 } } }, { "name": "ITEM_2", "synonyms": [ "Item 2", "Second item" ], "display": { "title": "Item #2", "description": "Description of Item #2", "image": { "alt": "Google Assistant logo", "height": 0, "url": "https://developers.google.com/assistant/assistant_96.png", "width": 0 } } }, { "name": "ITEM_3", "synonyms": [ "Item 3", "Third item" ], "display": { "title": "Item #3", "description": "Description of Item #3", "image": { "alt": "Google Assistant logo", "height": 0, "url": "https://developers.google.com/assistant/assistant_96.png", "width": 0 } } }, { "name": "ITEM_4", "synonyms": [ "Item 4", "Fourth item" ], "display": { "title": "Item #4", "description": "Description of Item #4", "image": { "alt": "Google Assistant logo", "height": 0, "url": "https://developers.google.com/assistant/assistant_96.png", "width": 0 } } } ] }, "typeOverrideMode": "TYPE_REPLACE" } ] }, "prompt": { "override": false, "content": { "list": { "items": [ { "key": "ITEM_1" }, { "key": "ITEM_2" }, { "key": "ITEM_3" }, { "key": "ITEM_4" } ], "subtitle": "List subtitle", "title": "List title" } }, "firstSimple": { "speech": "This is a list.", "text": "This is a list." } } } }
المجموعة
يتم تمرير المجموعة أفقيًا وتسمح للمستخدمين باختيار عنصر واحد عن طريق اللمس أو الإدخال الصوتي. بالمقارنة مع القوائم، تحتوي المجموعات على مربّعات كبيرة وتسمح بعرض محتوى أكثر ثراءً. تشبه المربعات التي تشكل مجموعة البطاقة الأساسية ذات الصورة. عندما يختار المستخدمون عنصرًا من مجموعة، ينشئ "مساعد Google" طلب بحث للمستخدم (فقاعة محادثة) يتضمّن عنوان العنصر.
تكون المجموعات جيدة عندما يتم تقديم خيارات مختلفة للمستخدم، ولكن لا يلزم إجراء مقارنة مباشرة فيما بينها (مقابل القوائم). وبشكل عام، ننصحك بتفضيل القوائم على المجموعات لأن المسح الضوئي للقوائم أسهل والتفاعل الصوتي بها.
يجب أن تحتوي المجموعات على قسمَين على الأقل و10 مربّعات كحدّ أقصى. على الأجهزة التي تتيح العرض، يمكن للمستخدمين التمرير يمينًا أو يسارًا للتمرير عبر البطاقات في مجموعة قبل تحديد عنصر.
![مثال على ردّ بشأن اختيار مجموعة على شاشة ذكية](https://developers.google.cn/static/assistant/conversational/images/smart-display/carousel.png?authuser=5&hl=ar)
إنشاء مجموعة
عند إنشاء مجموعة، لا تحتوي المطالبة إلا على مفاتيح لكل عنصر يمكن للمستخدم اختياره. في الرد التلقائي على الويب، يمكنك تحديد العناصر التي تتوافق مع هذه
المفاتيح استنادًا إلى النوع Entry
.
تتمتع عناصر المجموعة المحدّدة على أنها كائنات Entry
بخصائص العرض التالية:
- الصورة (اختيارية)
- يجب أن تكون الصورة بطول 128 بكسل مستقل الكثافة × عرض 232 بكسل مستقل الكثافة
- إذا كانت نسبة العرض إلى الارتفاع للصورة لا تتطابق مع مربّع إحاطة الصورة، فسيتم توسيط الصورة بأشرطة على كلا الجانبين
- في حال كان رابط الصورة معطّلاً، يتم استخدام صورة عنصر نائب بدلاً من ذلك.
- العنوان (مطلوب)
- إنّ ميزة Markdown غير متاحة بنص عادي. تُطابق خيارات التنسيق نفسها مثل الردّ المنسَّق للبطاقة الأساسية
- يتم تصغير ارتفاع البطاقة إذا لم يتم تحديد عنوان.
- يجب أن يكون فريدًا (لإتاحة اختيار الصوت)
- الوصف (اختياري)
- إنّ ميزة Markdown غير متاحة بنص عادي. تُطابق خيارات التنسيق نفسها مثل الردّ المنسَّق للبطاقة الأساسية
تتطلّب ردود الاختيار المرئي إلغاء النوع حسب اسم خانته باستخدام نوع وقت تشغيل في وضع TYPE_REPLACE
. في معالج أحداث الرد التلقائي على الويب،
أشِر إلى النوع المطلوب تجاهله حسب اسم الخانة (المحدد في
إضافة ردود الاختيار) في السمة name
.
بعد استبدال أحد الأنواع، يمثّل النوع الناتج مجموعة العناصر التي يمكن للمستخدم الاختيار من بينها والتي يعرضها "مساعد Google".
أماكن إقامة
يحتوي نوع استجابة المجموعة على السمات التالية:
الموقع | Type | المتطلب | الوصف |
---|---|---|---|
items |
مصفوفة CollectionItem |
مطلوبة | يمثّل عنصرًا في المجموعة يمكن للمستخدمين اختياره. يحتوي كل CollectionItem على مفتاح مرتبط بنوع مُشار إليه
لعنصر المجموعة. |
title |
سلسلة | إجراء اختياري | عنوان النص العادي للمجموعة. ويجب أن تكون العناوين فريدة في المجموعة لإتاحة اختيار الصوت. |
subtitle |
سلسلة | إجراء اختياري | العنوان الفرعي للنص العادي للمجموعة. |
image_fill |
ImageFill |
إجراء اختياري | يتم استخدام الحدود بين البطاقة وحاوية الصورة لاستخدامها عندما لا تتطابق نسبة العرض إلى الارتفاع للصورة مع نسبة العرض إلى الارتفاع لحاوية الصورة. |
نموذج التعليمات البرمجية
تحدِّد النماذج التالية محتوى الطلب في رمز الردّ التلقائي على الويب أو في استجابة JSON للردّ التلقائي على الويب. ومع ذلك، يمكنك بدلاً من ذلك تحديد محتوى الطلب في أداة إنشاء الإجراءات (مثل YAML أو JSON).
Node.js
const ASSISTANT_LOGO_IMAGE = new Image({ url: 'https://developers.google.com/assistant/assistant_96.png', alt: 'Google Assistant logo' }); app.handle('Collection', conv => { conv.add("This is a collection."); // Override type based on slot 'prompt_option' conv.session.typeOverrides = [{ name: 'prompt_option', mode: 'TYPE_REPLACE', synonym: { entries: [ { name: 'ITEM_1', synonyms: ['Item 1', 'First item'], display: { title: 'Item #1', description: 'Description of Item #1', image: ASSISTANT_LOGO_IMAGE, } }, { name: 'ITEM_2', synonyms: ['Item 2', 'Second item'], display: { title: 'Item #2', description: 'Description of Item #2', image: ASSISTANT_LOGO_IMAGE, } }, { name: 'ITEM_3', synonyms: ['Item 3', 'Third item'], display: { title: 'Item #3', description: 'Description of Item #3', image: ASSISTANT_LOGO_IMAGE, } }, { name: 'ITEM_4', synonyms: ['Item 4', 'Fourth item'], display: { title: 'Item #4', description: 'Description of Item #4', image: ASSISTANT_LOGO_IMAGE, } }, ] } }]; // Define prompt content using keys conv.add(new Collection({ title: 'Collection Title', subtitle: 'Collection subtitle', items: [ { key: 'ITEM_1' }, { key: 'ITEM_2' }, { key: 'ITEM_3' }, { key: 'ITEM_4' } ], })); });
تنسيق JSON
{ "responseJson": { "session": { "id": "ABwppHHz--uQEEy3CCOANyB0J58oF2Yw5JEX0oXwit3uxDlRwzbEIK3Bcz7hXteE6hWovrLX9Ahpqu8t-jYnQRFGpAUqSuYjZ70", "params": {}, "typeOverrides": [ { "name": "prompt_option", "synonym": { "entries": [ { "name": "ITEM_1", "synonyms": [ "Item 1", "First item" ], "display": { "title": "Item #1", "description": "Description of Item #1", "image": { "alt": "Google Assistant logo", "height": 0, "url": "https://developers.google.com/assistant/assistant_96.png", "width": 0 } } }, { "name": "ITEM_2", "synonyms": [ "Item 2", "Second item" ], "display": { "title": "Item #2", "description": "Description of Item #2", "image": { "alt": "Google Assistant logo", "height": 0, "url": "https://developers.google.com/assistant/assistant_96.png", "width": 0 } } }, { "name": "ITEM_3", "synonyms": [ "Item 3", "Third item" ], "display": { "title": "Item #3", "description": "Description of Item #3", "image": { "alt": "Google Assistant logo", "height": 0, "url": "https://developers.google.com/assistant/assistant_96.png", "width": 0 } } }, { "name": "ITEM_4", "synonyms": [ "Item 4", "Fourth item" ], "display": { "title": "Item #4", "description": "Description of Item #4", "image": { "alt": "Google Assistant logo", "height": 0, "url": "https://developers.google.com/assistant/assistant_96.png", "width": 0 } } } ] }, "typeOverrideMode": "TYPE_REPLACE" } ] }, "prompt": { "override": false, "content": { "collection": { "imageFill": "UNSPECIFIED", "items": [ { "key": "ITEM_1" }, { "key": "ITEM_2" }, { "key": "ITEM_3" }, { "key": "ITEM_4" } ], "subtitle": "Collection subtitle", "title": "Collection Title" } }, "firstSimple": { "speech": "This is a collection.", "text": "This is a collection." } } } }
تصفُّح المجموعات
وعلى غرار المجموعة، يمثّل تصفُّح المجموعات ردًا ثريًا يسمح للمستخدمين بالتمرير عبر بطاقات الخيارات. تم تصميم "تصفّح المجموعات" خصيصًا لمحتوى الويب ويفتح المربّع المحدد في متصفّح ويب (أو في متصفّح AMP إذا كانت جميع المربّعات مفعّلة).
تتضمّن الردود على تصفُّح المجموعات ما لا يقل عن مربّعَين و10 مربّعات كحدّ أقصى. على الأجهزة التي تتيح العرض، يمكن للمستخدمين التمرير لأعلى أو لأسفل للتمرير بين البطاقات قبل تحديد عنصر.
تصفُّح إنشاء مجموعة
عند إنشاء تصفح لمجموعة، ضع في اعتبارك كيفية تفاعل المستخدمين
مع هذا الطلب. تفتح كل مجموعة تصفُّح item
عنوان URL المحدَّد لها، لذا يجب توفير تفاصيل مفيدة للمستخدم.
تتصف عناصر تصفح المجموعة بخصائص العرض التالية:
- الصورة (اختيارية)
- يتم فرض ارتفاع الصورة على 128 بكسل مستقل الكثافة × عرض 232 بكسل مستقل الكثافة.
- إذا كانت نسبة العرض إلى الارتفاع للصورة لا تتطابق مع مربّع إحاطة الصورة، يتم توسيط الصورة بأشرطة على جانبي الصورة أو أعلاها وأسفلها. يتم تحديد لون الأشرطة من خلال سمة تصفّح المجموعة
ImageFill
. - في حال كان رابط الصورة غير مفعّل، يتم استخدام صورة عنصر نائب بدلاً منها.
- العنوان (مطلوب)
- إنّ ميزة Markdown غير متاحة بنص عادي. يتم استخدام التنسيق نفسه مثل الاستجابة المنسّقة للبطاقة الأساسية.
- يتم تصغير ارتفاع البطاقة في حال عدم تحديد عنوان.
- الوصف (اختياري)
- إنّ ميزة Markdown غير متاحة بنص عادي. يتم استخدام التنسيق نفسه مثل الاستجابة المنسّقة للبطاقة الأساسية.
- التذييل (اختياري)
- نص عادي: ميزة Markdown غير متاحة.
أماكن إقامة
يحتوي نوع الرد على تصفُّح المجموعة على الخصائص التالية:
الموقع | Type | المتطلب | الوصف |
---|---|---|---|
item |
كائن | مطلوبة | يمثّل عنصرًا في المجموعة يمكن للمستخدمين اختياره. |
image_fill |
ImageFill |
إجراء اختياري | يتم استخدام الحدود بين البطاقة وحاوية الصورة لاستخدامها عندما لا تتطابق نسبة العرض إلى الارتفاع للصورة مع نسبة العرض إلى الارتفاع لحاوية الصورة. |
يحتوي تصفّح المجموعات item
على السمات التالية:
الموقع | Type | المتطلب | الوصف |
---|---|---|---|
title |
سلسلة | مطلوبة | عنوان نص عادي لعنصر المجموعة. |
description |
سلسلة | إجراء اختياري | وصف عنصر المجموعة. |
footer |
سلسلة | إجراء اختياري | نص تذييل عنصر المجموعة، معروض أسفل الوصف. |
image |
Image |
إجراء اختياري | الصورة المعروضة لعنصر المجموعة. |
openUriAction |
OpenUrl |
مطلوبة | عنوان URI لفتحه عند اختيار عنصر المجموعة. |
نموذج التعليمات البرمجية
تحدِّد النماذج التالية محتوى الطلب في رمز الردّ التلقائي على الويب أو في استجابة JSON للردّ التلقائي على الويب. ومع ذلك، يمكنك بدلاً من ذلك تحديد محتوى الطلب في أداة إنشاء الإجراءات (مثل YAML أو JSON).
YAML
candidates: - first_simple: variants: - speech: This is a collection browse. content: collection_browse: items: - title: Item #1 description: Description of Item #1 footer: Footer of Item #1 image: url: 'https://developers.google.com/assistant/assistant_96.png' open_uri_action: url: 'https://www.example.com' - title: Item #2 description: Description of Item #2 footer: Footer of Item #2 image: url: 'https://developers.google.com/assistant/assistant_96.png' open_uri_action: url: 'https://www.example.com' image_fill: WHITE
تنسيق JSON
{ "candidates": [ { "firstSimple": { "speech": "This is a collection browse.", "text": "This is a collection browse." }, "content": { "collectionBrowse": { "items": [ { "title": "Item #1", "description": "Description of Item #1", "footer": "Footer of Item #1", "image": { "url": "https://developers.google.com/assistant/assistant_96.png" }, "openUriAction": { "url": "https://www.example.com" } }, { "title": "Item #2", "description": "Description of Item #2", "footer": "Footer of Item #2", "image": { "url": "https://developers.google.com/assistant/assistant_96.png" }, "openUriAction": { "url": "https://www.example.com" } } ], "imageFill": "WHITE" } } } ] }
Node.js
// Collection Browse app.handle('collectionBrowse', (conv) => { conv.add('This is a collection browse.'); conv.add(new CollectionBrowse({ 'imageFill': 'WHITE', 'items': [ { 'title': 'Item #1', 'description': 'Description of Item #1', 'footer': 'Footer of Item #1', 'image': { 'url': 'https://developers.google.com/assistant/assistant_96.png' }, 'openUriAction': { 'url': 'https://www.example.com' } }, { 'title': 'Item #2', 'description': 'Description of Item #2', 'footer': 'Footer of Item #2', 'image': { 'url': 'https://developers.google.com/assistant/assistant_96.png' }, 'openUriAction': { 'url': 'https://www.example.com' } } ] })); });
تنسيق JSON
{ "responseJson": { "session": { "id": "session_id", "params": {}, "languageCode": "" }, "prompt": { "override": false, "content": { "collectionBrowse": { "imageFill": "WHITE", "items": [ { "title": "Item #1", "description": "Description of Item #1", "footer": "Footer of Item #1", "image": { "url": "https://developers.google.com/assistant/assistant_96.png" }, "openUriAction": { "url": "https://www.example.com" } }, { "title": "Item #2", "description": "Description of Item #2", "footer": "Footer of Item #2", "image": { "url": "https://developers.google.com/assistant/assistant_96.png" }, "openUriAction": { "url": "https://www.example.com" } } ] } }, "firstSimple": { "speech": "This is a collection browse.", "text": "This is a collection browse." } } } }