رسائل المطالبة

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

أنواع الردود

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

  • الردود البسيطة: تكون الردود البسيطة على شكل فقاعة محادثة بشكل مرئي وتستخدم تحويل النص إلى كلام (TTS) أو لغة ترميز تركيب الكلام (SSML) للصوت. الردود البسيطة هي الردود الوحيدة المتوافقة مع جميع أنواع الأجهزة.
  • الردود المنسّقة: تحتوي الردود المنسّقة على عناصر مرئية أو وظيفية تحسِّن تفاعلات المستخدمين مع الإجراءات. مع الردود المنسّقة، يمكنك أيضًا عرض بيانات جدولية أو تشغيل محتوى صوتي طويل.
  • ردود التحديد المرئي: توفر إجابات التحديد المرئي واجهة مرئية للمستخدمين للاختيار من بين خيارات متعددة يمكن تمييزها بسهولة أكبر من خلال العنوان أو الصورة.
  • الردود على الوسائط: تتيح الردود الخاصة بالوسائط على الإجراءات تشغيل محتوى صوتي أطول من SSML، وتوفّر مكوِّنًا مرئيًا يتضمن عناصر تحكّم في الوسائط.
  • لوحة الرسم التفاعلية: تعرض "لوحة الرسم التفاعلية" الردود كردود على الويب بملء الشاشة، كما أنّها تعمل كتطبيق ويب تفاعلي يرسله "مساعد Google" كردّ على المستخدم في المحادثة. يستخدم Canvas تنسيق طلب مختلفًا قليلاً لاستيعاب مرونة إضافية من معايير الويب مثل HTML وCSS وJavaScript.

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

تنسيق الطلب

في مشروع "المهام"، يمكنك تحديد الطلبات بتنسيق YAML أو JSON. ويمكن أن يتضمّن كل طلب ما يصل إلى ردّين بسيطين، ويمكن بشكل اختياري تحديد ردّ غني بالمعلومات. يتم تعريف الردود بالطرق التالية:

  • first_simple: الاستجابة الأولية للنص أو الكلام (بسيطة) لإرسالها إلى المستخدم
  • content: محتوى تكميلي للردود المنسّقة لإرساله بعد ردود بسيطة
  • last_simple الرد النهائي للنص أو الكلام (البسيط) لإرساله إلى المستخدم.
  • canvas: يشير إلى تطبيق ويب يتكامل مع "لوحة الرسم التفاعلية".

بشكل تلقائي، يتم إلحاق الطلبات ببعضها البعض بالترتيب الموضّح أعلاه ضمن قائمة انتظار المطالبات. قبل أن يتمكّن المستخدم من الردّ، يعرض "مساعد Google" للمستخدم جميع الطلبات في قائمة انتظار الطلبات.

يمكنك أيضًا توفير المرونة في الطلب باستخدام الميزات التالية:

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

يستخدم الطلب التلقائي فئة مرشحة واحدة وخيارًا واحدًا واستجابة first_simple.

المرشحون

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

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

YAML

candidates:
  - selector:
      surface_capabilities:
        capabilities:
          - RICH_RESPONSE
    first_simple:
      variants:
        - speech: Here's a simple message.
    content:
      card:
        title: Image card title
        text: Some details about the image
        image:
          url: 'https://www.example.com/image/'
  - first_simple:
      variants:
        - speech: Text explains what the image might have shown in more detail.
    

تنسيق JSON

{
  "candidates": [{
    "selector": {
      "surface_capabilities": {
        "capabilities": ["RICH_RESPONSE"]
      }
    },
    "first_simple": {
      "variants": [{
        "speech": "Here's a simple message."
      }]
    },
    "content": {
      "card": {
        "title": "Image card title",
        "text": "Some details about the image",
        "image": {
          "url": "https://www.example.com/image/"
        }
      }
    }
  }, {
    "first_simple": {
      "variants": [{
        "speech": "Text explains what the image might have shown in more detail."
      }]
    }
  }]
}
    

ويمكنك تقديم واحد أو أكثر من متطلبات الإمكانات لمرشح معيّن. توضّح القائمة التالية جميع متطلبات الإمكانات المتاحة:

  • SPEECH: يمكن للجهاز التحدّث إلى المستخدم من خلال ميزة "تحويل النص إلى كلام" أو SSML.
  • RICH_RESPONSE: يمكن للجهاز عرض ردود منسّقة، مثل البطاقات والقوائم والجداول.
  • LONG_FORM_AUDIO: يمكن للجهاز تشغيل وسائط صوتية طويلة مثل الموسيقى وملفات البودكاست.
  • INTERACTIVE_CANVAS: يمكن للجهاز عرض استجابة "لوحة الرسم التفاعلية".
  • WEB_LINK: يمكن للجهاز استخدام روابط ويب في الردود المنسّقة لفتح متصفّح ويب.
  • HOME_STORAGE: يمكن للجهاز تخزين البيانات في وحدة التخزين المنزلية والوصول إليها.

المتغيرات

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

على سبيل المثال، قدِّم صيغًا مختلفة من الرسائل الترحيبية كي لا يسمع المستخدمون الرد نفسه في كل مرة يستدعون فيها الإجراء الخاص بك:

YAML

candidates:
  - first_simple:
      variants:
        - speech: Hello.
        - speech: Hi there.
        - speech: Welcome.
    

تنسيق JSON

{
  "candidates": [{
    "first_simple": {
      "variants": [{
        "speech": "Hello."
      },{
        "speech": "Hi there."
      },{
        "speech": "Welcome."
      }]
    }
  }]
}
    

الاقتراحات

مثال على شرائح الاقتراحات على شاشة ذكية

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

يمكن أن يكون لديك 8 اقتراحات كحدّ أقصى في طلب واحد، على أن يبلغ طول كلّ اقتراح 25 حرفًا في النص العادي.

لإضافة اقتراح، قدِّم عنصر Suggestion يتضمّن كل اقتراح في حقل title منفصل. يجب أن يكون كل عنوان فريدًا بين مجموعة شرائح الاقتراحات. في "أداة إنشاء الإجراءات"، يتم تمثيل هذا الكائن في YAML وJSON باسم suggestions.

على سبيل المثال، يمكنك تقديم اقتراحات "نعم" و "لا" بجانب السؤال:

YAML

candidates:
  - first_simple:
      variants:
        - speech: 'Welcome, do you want to play a game?'
    suggestions:
      - title: 'Yes'
      - title: 'No'
    

تنسيق JSON

{
  "candidates": [{
    "first_simple": {
      "variants": [{
        "speech": "Welcome, do you want to play a game?"
      }]
    },
    "suggestions": [{
      "title": "Yes"
    }, {
      "title": "No"
    }]
  }]
}