الردود المنسّقة

تضيف الردود التفاعلية عناصر مرئية لتحسين تفاعلات المستخدم مع الإجراء الخاص بك. يمكنك استخدام أنواع الردود المنسّقة التالية كجزء من طلب:

  • البطاقة الأساسية
  • بطاقة صورة
  • بطاقة جدول

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

البطاقة الأساسية

تم تصميم البطاقات الأساسية بحيث تكون موجزة لتقديم المعلومات الرئيسية (أو التلخيصية) للمستخدمين، وتتيح لهم معرفة المزيد من المعلومات إذا اخترت ذلك (باستخدام رابط ويب).

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

مثال على بطاقة أساسية على الشاشة الذكية

أماكن إقامة

يضم نوع استجابة البطاقة الأساسي السمات التالية:

الموقع Type المتطلب الوصف
title سلسلة إجراء اختياري عنوان النص العادي للبطاقة. تكون العناوين ذات خط وحجم ثابت، ويتم اقتطاع الأحرف التي تتجاوز السطر الأول. يتم تصغير ارتفاع البطاقة إذا لم يتم تحديد عنوان.
subtitle سلسلة إجراء اختياري العنوان الفرعي للنص العادي للبطاقة. تكون العناوين ذات خط وحجم ثابت، ويتم اقتطاع الأحرف التي تتجاوز السطر الأول. يتم تصغير ارتفاع البطاقة في حال عدم تحديد عنوان فرعي.
text سلسلة الجملة الشرطية

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

يخضع هذا الموقع للقيود التالية:

  • الحد الأقصى هو 15 سطرًا بدون صورة أو 10 أسطر بدون صورة image. وهو ما يقرب من 750 حرف (بدون صورة) أو 500 حرف (مع صور). ويُرجى العِلم بأنّ الأجهزة الجوّالة تقتطع النص قبل مساحات العرض ذات الشاشات الأكبر حجمًا.
  • يجب ألا يحتوي النص على رابط.

تتم إتاحة مجموعة فرعية محدودة من Markdown:

  • سطر جديد بمسافة مزدوجة متبوعًا بـ \n
  • **bold**
  • *italics*
image Image إجراء اختياري الصورة المعروضة في البطاقة ويمكن أن تكون الصور بتنسيق JPG وPNG وGIF (الرسوم المتحركة وغير المتحركة).
image_fill ImageFill إجراء اختياري يتم استخدام الحدود بين البطاقة وحاوية الصورة لاستخدامها عندما لا تتطابق نسبة العرض إلى الارتفاع للصورة مع نسبة العرض إلى الارتفاع لحاوية الصورة.
button Link إجراء اختياري زر يربط المستخدم بعنوان URL عند النقر عليه ويجب أن يحتوي الزر على السمة name التي تحتوي على نص الزر، والسمة url التي تحتوي على عنوان URL للرابط. قد لا يكون نص الزر مضللاً، ويتم التحقق منه أثناء عملية المراجعة.

نموذج التعليمات البرمجية

YAML

candidates:
  - first_simple:
      variants:
        - speech: This is a card.
          text: This is a card.
    content:
      card:
        title: Card Title
        subtitle: Card Subtitle
        text: Card Content
        image:
          url: 'https://developers.google.com/assistant/assistant_96.png'
          alt: Google Assistant logo

تنسيق JSON

{
  "candidates": [
    {
      "first_simple": {
        "variants": [
          {
            "speech": "This is a card.",
            "text": "This is a card."
          }
        ]
      },
      "content": {
        "card": {
          "title": "Card Title",
          "subtitle": "Card Subtitle",
          "text": "Card Content",
          "image": {
            "url": "https://developers.google.com/assistant/assistant_96.png",
            "alt": "Google Assistant logo"
          }
        }
      }
    }
  ]
}

Node.js

app.handle('Card', conv => {
  conv.add('This is a card.');
  conv.add(new Card({
    "title": "Card Title",
    "subtitle": "Card Subtitle",
    "text": "Card Content",
    "image": new Image({
      url: 'https://developers.google.com/assistant/assistant_96.png',
      alt: 'Google Assistant logo'
    })
  }));
});

تنسيق JSON

{
  "responseJson": {
    "session": {
      "id": "session_id",
      "params": {}
    },
    "prompt": {
      "override": false,
      "content": {
        "card": {
          "title": "Card Title",
          "subtitle": "Card Subtitle",
          "text": "Card Content",
          "image": {
            "alt": "Google Assistant logo",
            "height": 0,
            "url": "https://developers.google.com/assistant/assistant_96.png",
            "width": 0
          }
        }
      },
      "firstSimple": {
        "speech": "This is a card.",
        "text": "This is a card."
      }
    }
  }
}

بطاقات الصور

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

أماكن إقامة

يضم نوع استجابة بطاقة الصورة السمات التالية:

الموقع Type المتطلب الوصف
url سلسلة مطلوبة عنوان URL المصدر للصورة يمكن أن تكون الصور بتنسيق JPG أو PNG أو GIF (الرسوم المتحركة وغير المتحركة).
alt سلسلة مطلوبة الوصف النصي للصورة التي سيتم استخدامها لإمكانية الوصول.
height int32 إجراء اختياري ارتفاع الصورة بالبكسل.
width int32 إجراء اختياري عرض الصورة بالبكسل.

نموذج التعليمات البرمجية

YAML

candidates:
  - first_simple:
      variants:
        - speech: This is an image prompt.
          text: This is an image prompt.
    content:
      image:
        alt: Google Assistant logo
        url: 'https://developers.google.com/assistant/assistant_96.png'

تنسيق JSON

{
  "candidates": [
    {
      "first_simple": {
        "variants": [
          {
            "speech": "This is an image prompt.",
            "text": "This is an image prompt."
          }
        ]
      },
      "content": {
        "image": {
          "alt": "Google Assistant logo",
          "url": "https://developers.google.com/assistant/assistant_96.png"
        }
      }
    }
  ]
}

Node.js

app.handle('Image', conv => {
  conv.add("This is an image prompt!");
  conv.add(new Image({
      url: 'https://developers.google.com/assistant/assistant_96.png',
      alt: 'Google Assistant logo'
  }));
});

تنسيق JSON

{
  "responseJson": {
    "session": {
      "id": "session_id",
      "params": {}
    },
    "prompt": {
      "override": false,
      "content": {
        "image": {
          "alt": "Google Assistant logo",
          "height": 0,
          "url": "https://developers.google.com/assistant/assistant_96.png",
          "width": 0
        }
      },
      "firstSimple": {
        "speech": "This is an image prompt.",
        "text": "This is an image prompt."
      }
    }
  }
}

بطاقات الطاولة

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

مثال على بطاقة جدول على الشاشة الذكية

تعرض الجداول بيانات ثابتة ولا يمكن التفاعل معها. لردود الاختيار التفاعلي، استخدم رد التحديد المرئي بدلاً من ذلك.

أماكن إقامة

يحتوي نوع استجابة بطاقة الجدول على السمات التالية:

الموقع Type المتطلب الوصف
title سلسلة الجملة الشرطية تمثّل هذه السمة عنوان الجدول بتنسيق نص عادي. ويجب إدراج هذه السمة في حال ضبط subtitle.
subtitle سلسلة إجراء اختياري العنوان الفرعي للنص العادي للجدول. ولا تتأثر الترجمة في بطاقات الجدول بتخصيص المظهر.
columns مصفوفة TableColumn مطلوبة العناوين ومحاذاة الأعمدة. ويصف كل كائن TableColumn عنوان عمود مختلف في الجدول نفسه ومحاذاة هذا العنصر.
rows مصفوفة TableRow مطلوبة

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

يصف كل كائن TableRow خلايا صف مختلف في الجدول نفسه.

image Image إجراء اختياري صورة مرتبطة بالجدول
button Link إجراء اختياري زر يربط المستخدم بعنوان URL عند النقر عليه ويجب أن يحتوي الزر على السمة name التي تحتوي على نص الزر، والسمة url التي تحتوي على عنوان URL للرابط. قد لا يكون نص الزر مضللاً، ويتم التحقق منه أثناء عملية المراجعة.

نموذج التعليمات البرمجية

توضّح المقتطفات التالية كيفية تطبيق بطاقة جدول:

YAML

candidates:
  - first_simple:
      variants:
        - speech: This is a table.
          text: This is a table.
    content:
      table:
        title: Table Title
        subtitle: Table Subtitle
        columns:
          - header: Column A
          - header: Column B
          - header: Column C
        rows:
          - cells:
              - text: A1
              - text: B1
              - text: C1
          - cells:
              - text: A2
              - text: B2
              - text: C2
          - cells:
              - text: A3
              - text: B3
              - text: C3
        image:
          alt: Google Assistant logo
          url: 'https://developers.google.com/assistant/assistant_96.png'

تنسيق JSON

{
  "candidates": [
    {
      "first_simple": {
        "variants": [
          {
            "speech": "This is a table.",
            "text": "This is a table."
          }
        ]
      },
      "content": {
        "table": {
          "title": "Table Title",
          "subtitle": "Table Subtitle",
          "columns": [
            {
              "header": "Column A"
            },
            {
              "header": "Column B"
            },
            {
              "header": "Column C"
            }
          ],
          "rows": [
            {
              "cells": [
                {
                  "text": "A1"
                },
                {
                  "text": "B1"
                },
                {
                  "text": "C1"
                }
              ]
            },
            {
              "cells": [
                {
                  "text": "A2"
                },
                {
                  "text": "B2"
                },
                {
                  "text": "C2"
                }
              ]
            },
            {
              "cells": [
                {
                  "text": "A3"
                },
                {
                  "text": "B3"
                },
                {
                  "text": "C3"
                }
              ]
            }
          ],
          "image": {
            "alt": "Google Assistant logo",
            "url": "https://developers.google.com/assistant/assistant_96.png"
          }
        }
      }
    }
  ]
}

Node.js

app.handle('Table', conv => {
  conv.add('This is a table.');
  conv.add(new Table({
    "title": "Table Title",
    "subtitle": "Table Subtitle",
    "image": new Image({
      url: 'https://developers.google.com/assistant/assistant_96.png',
      alt: 'Google Assistant logo'
    }),
    "columns": [{
      "header": "Column A"
    }, {
      "header": "Column B"
    }, {
      "header": "Column C"
    }],
    "rows": [{
      "cells": [{
        "text": "A1"
      }, {
        "text": "B1"
      }, {
        "text": "C1"
      }]
    }, {
      "cells": [{
        "text": "A2"
      }, {
        "text": "B2"
      }, {
        "text": "C2"
      }]
    }, {
      "cells": [{
        "text": "A3"
      }, {
        "text": "B3"
      }, {
        "text": "C3"
      }]
    }]
  }));
});

تنسيق JSON

{
  "responseJson": {
    "session": {
      "id": "session_id",
      "params": {}
    },
    "prompt": {
      "override": false,
      "content": {
        "table": {
          "button": {},
          "columns": [
            {
              "header": "Column A"
            },
            {
              "header": "Column B"
            },
            {
              "header": "Column C"
            }
          ],
          "image": {
            "alt": "Google Assistant logo",
            "height": 0,
            "url": "https://developers.google.com/assistant/assistant_96.png",
            "width": 0
          },
          "rows": [
            {
              "cells": [
                {
                  "text": "A1"
                },
                {
                  "text": "B1"
                },
                {
                  "text": "C1"
                }
              ]
            },
            {
              "cells": [
                {
                  "text": "A2"
                },
                {
                  "text": "B2"
                },
                {
                  "text": "C2"
                }
              ]
            },
            {
              "cells": [
                {
                  "text": "A3"
                },
                {
                  "text": "B3"
                },
                {
                  "text": "C3"
                }
              ]
            }
          ],
          "subtitle": "Table Subtitle",
          "title": "Table Title"
        }
      },
      "firstSimple": {
        "speech": "This is a table.",
        "text": "This is a table."
      }
    }
  }
}

تخصيص الردود

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

لضبط مظهر ردّ مخصّص، يُرجى اتّباع الخطوات التالية:

  1. في وحدة تحكُّم الإجراءات، انتقِل إلى التطوير > تخصيص المظهر.
  2. اضبط أيًا مما يلي أو كل ما يلي:
    • لون الخلفية: يُستخدَم كخلفية لبطاقاتك. بشكل عام، استخدِم لونًا فاتحًا للخلفية لتسهيل قراءة محتوى البطاقة.
    • اللون الأساسي: اللون الرئيسي لنصوص عناوين البطاقات وعناصر الواجهة. بشكل عام، استخدم لونًا أساسيًا أغمق للتباين بشكل أفضل مع لون الخلفية.
    • مجموعة الخطوط: تصف نوع الخط المستخدَم للعناوين والعناصر النصية البارزة الأخرى.
    • نمط زاوية الصورة: يغير مظهر زوايا البطاقات.
    • صورة الخلفية: هي صورة مخصَّصة لاستخدامها بدلاً من لون الخلفية. قدِّم صورتَين مختلفتَين عندما يكون الجهاز السطحي في الوضع الأفقي أو العمودي. إذا كنت تستخدم صورة خلفية، فسيتم تعيين اللون الأساسي على الأبيض.
  3. انقر على حفظ.
تخصيص المظهر في "وحدة تحكّم المهام"