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

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

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

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

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

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

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

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

عند استخدام حزمة تطوير برامج المهام، اتّبِع هذه الخطوات الإضافية لتفعيل ميزة "الإعلانات التفاعلية" لوحة الرسم:

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 رد في العادة مباشرةً بعد استدعاء المستخدم للإجراء. عند تحميل تطبيق الويب، يتم تحميل مكتبة لوحة الرسم التفاعلية، ويسجِّل تطبيق الويب معالِج معاودة الاتصال باستخدام واجهة برمجة تطبيقات 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.

توضّح الأقسام التالية كيفية تمرير البيانات من خلال "أداة إنشاء المهام" الرد التلقائي على الويب.

استخدام "أداة إنشاء المهام" لتمرير البيانات

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

على سبيل المثال، يشير معالج النية Guess التالي إلى أنّك تريد تضمين Canvas. الرد:

YAML

candidates:
  - canvas:
      send_state_data_to_canvas_app: true
    

JSON

{
  "candidates": [
    {
      "canvas": {
        "send_state_data_to_canvas_app": true
      }
    }
  ]
}
    

يمكنك اختياريًا إلحاق المقتطف التالي بمعالج intent لإرسال رسالة 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 كيلوبايت أو أصغر.