طلبات على لوحة الرسم

لإرسال المعلومات إلى تطبيق الويب، يجب إرسال ردّ Canvas من منطقك الحواري. يمكن لاستجابة Canvas تنفيذ أحد الإجراءات التالية:

• عرض تطبيق الويب في وضع ملء الشاشة على جهاز المستخدم
• تمرير البيانات لتحديث تطبيق الويب

تصف الأقسام التالية كيفية عرض استجابة لوحة رسم لكل سيناريو.

تفعيل ميزة "لوحة الرسم التفاعلية"

يجب إعداد الإجراء الخاص بك بطريقة معيّنة لاستخدام "لوحة الرسم التفاعلية". إنّ إنشاء إجراء يستخدم "لوحة الرسم التفاعلية" يتطلّب ضبطًا إضافيًا في "وحدة تحكُّم المهام" (وتعديلات ملف settings.yaml لحزمة "المهام مع مساعد Google"). للاطّلاع على الإجراء الكامل لإنشاء "إجراء لوحة رسم تفاعلي" وإعداده باستخدام حزمة تطوير البرامج (SDK) للإجراءات، يمكنك الاطّلاع على مقالة إنشاء مشروع.

عند استخدام أداة إنشاء الإجراءات، اتبع هذه الخطوات الإضافية لتفعيل لوحة الرسم التفاعلية:

1. إذا لم تختَر بطاقة اللعبة في شاشة ما نوع الإجراء الذي تريد إنشاءه؟، انقر على نشر في شريط التنقّل العلوي. ضمن معلومات إضافية، اختَر فئة الألعاب والمرح. انقر على حفظ.
2. انقر على تطوير في شريط التنقّل العلوي في "وحدة تحكّم المهام".
3. انقر على لوحة رسم تفاعلية في شريط التنقل الأيمن.
4. ضمن القسم هل تريد أن يستخدم الإجراء الخاص بك "لوحة الرسم التفاعلية"؟، اختَر أحد الخيارات التالية:
   • تفعيل "لوحة الرسم التفاعلية" مع تنفيذ الرد التلقائي على الويب للخادم يعتمد هذا الخيار على الرد التلقائي على الويب للوصول إلى ميزات معيّنة، كما يستخدم بشكلٍ متكرر onUpdate() لتمرير البيانات إلى تطبيق الويب. عندما يكون هذا الخيار مفعّلاً، تتم معالجة مطابقات الأهداف في المشاهد، ويمكنك اختيار استدعاء الردّ التلقائي على الويب قبل الانتقال إلى مشهد آخر أو إنهاء المحادثة.
   • تفعيل "لوحة الرسم التفاعلية" من خلال توفير المتطلبات اللازمة للعميل: يسمح لك هذا الخيار بنقل منطق تنفيذ الردّ التلقائي على الويب إلى تطبيق الويب، وقصر طلبات الردّ التلقائي على الويب على ميزات المحادثة التي تتطلّبها فقط، مثل ربط الحساب. عند تفعيل هذا الإعداد، يمكنك استخدام expect() لتسجيل معالِجات الأهداف من جهة العميل.
5. اختياري: أدخِل عنوان URL لتطبيق الويب في الحقل ضبط عنوان URL التلقائي لتطبيق الويب. يؤدي هذا الإجراء إلى إضافة ردّ Canvas تلقائي مع حقل عنوان URL إلى استدعائك الرئيسي.
6. انقر على حفظ.

عند استخدام حزمة تطوير البرامج (SDK) للإجراءات، يُرجى اتّباع الخطوات الإضافية التالية لتفعيل لوحة الرسم التفاعلية:

1. اضبط الحقل category في ملف settings.yaml على GAMES_AND_TRIVIA لتقديم أفضل وصف ومساعدة المستخدمين في اكتشاف الإجراء الخاص بك.
2. اضبط الحقل usesInteractiveCanvas في ملف settings.yaml على true.

التحقّق من إمكانات السطح

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

لعرض استجابة Canvas، يجب أن يتّبع منطق الإجراء الخاص بك ما يلي:

1. تحقّق من أنّ جهاز المستخدم يتيح استخدام ميزة "INTERACTIVE_CANVAS". إذا كان الأمر كذلك، أرسِل ردًا Canvas إلى المستخدم.
2. في حال عدم توفّر إمكانية "لوحة الرسم التفاعلية"، تحقّق مما إذا كان جهاز المستخدم يتيح استخدام الميزة RICH_RESPONSE. وإذا كان الأمر كذلك، أرسِل ردًا غنيًا إلى المستخدم بدلاً من ذلك.
3. في حال عدم توفّر إمكانية الاستجابة المنسَّقة، أرسِل ردًا بسيطًا إلى المستخدم.

تعرض المقتطفات التالية الاستجابة المناسبة استنادًا إلى إمكانيات جهاز المستخدم:

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 لتطبيق الويب في وحدة التحكم، يُرجى الاطّلاع على قسم تفعيل لوحة الرسم التفاعلية.

ملاحظة: تحديد عنوان URL لتطبيق الويب في "أداة إنشاء الإجراءات" لن يؤدي إلى تعبئة حقل عنوان URL لاستجابة Canvas تلقائيًا في الطلبات التي أنشأتها سابقًا.

توضّح المقتطفات التالية كيفية إنشاء ردود 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 يمرّر البيانات إلى تطبيق الويب، تحدث الخطوات التالية:

1. عند مطابقة الغرض في مشهد، يتم بدء حدث، ثم يتم إرسال استجابة Canvas التي تحتوي على الحقل data مع حمولة JSON كاستجابة.
2. يتم تمرير الحقل data إلى معاودة الاتصال onUpdate واستخدامه لتعديل تطبيق الويب.

3. يمكن أن يرسل "الإجراء المستند إلى المحادثة" ردّ Canvas جديد ويقدّم معلومات في الحقل data لإرسال تعديلات جديدة أو تحميل حالات جديدة.

   ملاحظة: في حال تغيّرت قيمة الحقل url في الردود اللاحقة الخاصة بعملية التنفيذ، تتم إعادة تحميل تطبيق الويب. إذا تم تقديم القيمة نفسها لـ url أو إذا تم استبعاد url كجزء من استجابة لاحقة، يتم الاحتفاظ بتطبيق الويب الحالي على الجهاز.

يمكنك تمرير البيانات إلى تطبيق الويب بطريقتين:

• باستخدام "أداة إنشاء المهام": تملأ "أداة إنشاء الإجراءات" الحقل 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 كيلوبايت أو أصغر.