تفاصيل إطار iframe ومَعلمة طلب البحث

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

إرشادات أمان إطار iframe

على الشركاء اتّباع أفضل الممارسات المتّبعة في المجال لتأمين إطار iframe. لحماية إطار iframe، ينصح فريق الأمان بما يلي:

إعداد معرّف الموارد المنتظم (URI) لإطار iframe

معرّف الموارد المنتظم (URI) لإعداد المرفقات هو ما يتم تحميله في إطار iframe الخاص باكتشاف المرفقات، والذي يبدأ فيه المعلمون عملية إنشاء مرفقات الإضافات في مشاركة على Classroom. ويمكن إعداده في وحدة تحكُّم المشروع على Google Cloud. يمكنك إعداد معرّف الموارد المنتظم (URI) هذا في واجهة برمجة التطبيقات والخدمة لمشروع Google Cloud > حزمة تطوير برامج Google Workspace Marketplace > صفحة إعداد التطبيق.

إعداد معرّف الموارد المنتظم (URI) لإطار iframe

يتم استخدام بادئات معرف الموارد المنتظم (URI) المسموح بها للتحقق من صحة معرفات الموارد المنتظمة (URI) التي تم إعدادها في AddOnAttachment باستخدام الطريقتين *.addOnAttachments.create و*.addOnAttachments.patch. التحقق من الصحة هو مطابقة بادئة سلسلة حرفية ولا يسمح باستخدام أحرف البدل في الوقت الحالي.

معلمات طلب البحث

تمرِّر إطارات iframe المعلومات المهمة إلى الإضافة باعتبارها مَعلمات طلب البحث. هناك فئتان من المعلمات: المعلمات المتعلقة بالمرفقات والمعلمات ذات الصلة بتسجيل الدخول.

تزود المعلمات المتعلقة بالمرفقات الإضافة بمعلومات حول الدورة التدريبية والمهمة ومرفق الإضافة وإرسال الطالب ورمز مميز للمصادقة.

رقم تعريف الدورة التدريبية

تشير القيمة courseId إلى معرّف الدورة التدريبية.

مضمّنة مع جميع إطارات iframe

معرِّف السلعة

القيمة itemId هي معرّف Announcement،

CourseWork، أو CourseWorkMaterial التي تم إرفاق هذا المرفق بها.

مضمّنة مع جميع إطارات iframe

نوع العنصر

تحدد القيمة itemType نوع المورد الذي سيتم بناءً عليه

المرفق. قيمة السلسلة التي تم تمريرها هي إحدى القيم التالية: "announcements"، أو "courseWork"، أو "courseWorkMaterials".

مضمّنة مع جميع إطارات iframe

رقم تعريف المرفق

القيمة attachmentId هي معرّف للمرفق.

تم تضمينه في إطارات iframe teacherViewUri وstudentViewUri وstudentWorkReviewUri.

رقم تعريف المَهمّة الدراسية المرسَلة

وsubmissionId هي معرّف لعمل الطالب، ولكن يجب استخدامها مع attachmentId لتحديد عمل الطالب في مهمة معيّنة.

تتوفّر هذه الميزة في studentWorkReviewUri.

الرمز المميّز للإضافة

القيمة addOnToken هي رمز تفويض مميز يُستخدم لإنشاء

addOnAttachments.create مكالمة لإنشاء الإضافة.

تم تضمينه مع إطار iframe لاكتشاف المرفقات وإطار iframe لترقية الرابط.

عنوان URL المطلوب ترقيته

يشير وجود القيمة urlToUpgrade إلى أنّ

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

تم تضمينه في إطار iframe لترقية الرابط.

توفّر مَعلمة طلب البحث login_hint معلومات عن مستخدم Classroom الذي يزور صفحة الويب الخاصة بالإضافة. تتوفر معلَمة طلب البحث هذه على عنوان URL لإطار iframe src. ويتم إرساله عندما سبق أن استخدم المستخدم الإضافة للمساعدة في تقليل الصعوبات التي تواجهك عند تسجيل دخول المستخدم النهائي عليك التعامل مع معلمة طلب البحث هذه عند تنفيذ الإضافة.

تلميح تسجيل الدخول

login_hint هو معرّف فريد لحساب المستخدِم على Google.

الحساب. بعد أن يسجّل المستخدم الدخول إلى الإضافة للمرة الأولى، يتم تمرير المَعلمة login_hint في كل زيارة لاحقة إلى الإضافة من قِبل المستخدم نفسه.

هناك استخدامان محتملان للمَعلمة login_hint:

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

مضمّنة مع جميع إطارات iframe

إطار iframe لاكتشاف المرفقات

السمة الوصف
مطلوبة نعم
معرّف الموارد المنتظم (URI) تم توفيره في البيانات الوصفية للإضافة
معلمات طلب البحث "courseId" و"itemId" و"itemType" وaddOnToken وlogin_hint
الطول ارتفاع النافذة 80% مطروحًا منه 60 بكسل للعنوان العلوي
العرض الحد الأقصى هو 1600 بكسل
عرض النافذة بنسبة 90% عندما يكون عرض النافذة <= 600 بكسل
عرض النافذة بنسبة% 80 عندما يكون عرض النافذة أكبر من 600 بكسل

مثال على سيناريو اكتشاف المرفقات

  1. تم تسجيل إضافة Classroom في Google Workspace Marketplace باستخدام معرّف موارد منتظم (URI) لـ Pending Discovery في https://example.com/addon.
  2. يثبّت المعلِّم هذه الإضافة وينشئ إشعارًا أو مهمة أو مادة جديدة في إحدى دوراته التدريبية. على سبيل المثال، itemId=234 وitemType=courseWork وcourseId=123.
  3. أثناء ضبط هذا العنصر، يختار المعلّم الإضافة المثبَّتة حديثًا كمرفق.
  4. ينشئ Classroom إطار iframe مع ضبط عنوان URL للسمة src على https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456.
    1. ينفذ المعلم عملاً ضمن إطار iframe لاختيار مرفق.
  5. عند اختيار المرفقات، ترسل الإضافة postMessage إلى Classroom لإغلاق إطار iframe.

إطارات iframe الخاصة بالمعلِّمينViewUri وstudentViewUri

السمة الوصف
مطلوبة نعم
معرّف الموارد المنتظم (URI) ‫‎teacherViewUri أو ‎studentViewUri
معلمات طلب البحث "courseId" و"itemId" و"itemType" وattachmentId وlogin_hint
الطول ارتفاع النافذة 100% مطروحًا منه 140 بكسل للعنوان العلوي
العرض عرض النافذة: 100%

إطار iframe الخاص بـ userWorkReviewUri

السمة الوصف
مطلوبة لا (يحدد ما إذا كان هذا مرفقًا من نوع نشاط)
معرّف الموارد المنتظم (URI) studentWorkReviewUri
معلمات طلب البحث "courseId" و"itemId" و"itemType" وattachmentId وsubmissionId وlogin_hint
الطول ارتفاع النافذة 100% مطروحًا منه 168 بكسل للعنوان العلوي
العرض عرض النافذة بنسبة 100% مطروحًا منه عرض الشريط الجانبي<> يكون الشريط الجانبي 312 بكسل عند التوسيع و56 بكسل عند التصغير

السمة الوصف
مطلوبة نعم، إذا كانت الإضافة تتيح ترقية الروابط إلى مرفقات الإضافات.
معرّف الموارد المنتظم (URI) تم توفيره في البيانات الوصفية للإضافة
معلمات طلب البحث "courseId" و"itemId" و"itemType" وaddOnToken وurlToUpgrade وlogin_hint
الطول ارتفاع النافذة 80% مطروحًا منه 60 بكسل للعنوان العلوي
العرض الحد الأقصى هو 1600 بكسل
عرض النافذة بنسبة 90% عندما يكون عرض النافذة <= 600 بكسل
عرض النافذة بنسبة% 80 عندما يكون عرض النافذة أكبر من 600 بكسل
  1. تم تسجيل إضافة Classroom باستخدام معرّف الموارد المنتظم (URI) لترقية الرابط https://example.com/upgrade. أنّك قدّمت أنماط البادئة التالية للمضيف ومسار لمرفقات الروابط التي يجب أن يحاول Classroom الترقية إلى مرفق إضافة:
    • المضيف هو example.com وبادئة المسار /quiz.
  2. ينشئ المعلم إعلانًا أو مهمة أو مادة جديدة ضمن إحدى دوراته التدريبية. على سبيل المثال، itemId=234 وitemType=courseWork وcourseId=123.
  3. يلصق المعلّم رابطًا، https://example.com/quiz/5678، في مربّع حوار "مرفقات" الذي يطابق نمط عنوان URL الذي قدّمته. بعد ذلك، يُطلب من المدرس ترقية الرابط إلى مرفق إضافة.

  4. يُطلق Classroom إطار iframe الخاص بترقية الروابط مع ضبط عنوان URL على https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678.

  5. عليك تقييم معلَمات طلب البحث التي تم تمريرها في إطار iframe وإجراء طلب إلى نقطة نهاية CreateAddOnAttachment. يُرجى العِلم أنّ معلَمة طلب البحث urlToUpgrade هي معرّف موارد منتظم (URI) تم ترميزه عند ضبطه على إطار iframe. تحتاج إلى فك ترميز المعلمة للحصول عليها بشكلها الأصلي. على سبيل المثال، توفّر لغة JavaScript الوظيفة decodeURIComponent().

  6. عند إنشاء مرفق إضافة من رابط بنجاح، يمكنك إرسال postMessage إلى Classroom لإغلاق إطار iframe.

إغلاق إطار iframe

يمكن إغلاق إطار iframe من خلال أداة التعلُّم من خلال إرسال postMessage مع الحمولة {type: 'Classroom', action: 'closeIframe'}. لا يقبل Classroom سوى postMessage هذا من منفذ Host_name+المتوافق مع معرّف الموارد المنتظم (URI) الأصلي الذي تم فتحه.

<button id="close">Send message to close iframe</button>
<script>
  document.querySelector('#close')
    .addEventListener('click', () => {
        window.parent.postMessage({
            type: 'Classroom',
            action: 'closeIframe',
        }, '*');
    });
</script>

إغلاق إطار iframe من إطار iframe

يجب أن يحتوي منفذ +النطاق للصفحة التي ترسل الحدث postMessage على منفذ +النطاق نفسه مثل منفذ معرّف الموارد المنتظم (URI) المستخدَم لتشغيل إطار iframe، وإلا سيتم تجاهل الرسالة. ويتمثَّل الحل البديل في إعادة التوجيه إلى صفحة على النطاق الأصلي، وهذا الإجراء لا يؤدي إلى أكثر من إرسال حدث postMessage.

إغلاق إطار iframe من علامة تبويب جديدة

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

الشروط

يتم فتح جميع إطارات iframe باستخدام سمات وضع الحماية التالية:

  • allow-popups
  • allow-popups-to-escape-sandbox
  • allow-forms
  • allow-scripts
  • allow-storage-access-by-user-activation
  • allow-same-origin

وسياسة الميزات التالية

  • allow="microphone *"

يُرجى الانتباه إلى أنّ حظر ملفات تعريف الارتباط التابعة لجهات خارجية يُصعِّب الاحتفاظ بجلسة تسجيل الدخول في إطار iframe. راجع https://www.cookiestatus.com لمعرفة الحالة الحالية لحظر ملفات تعريف الارتباط عبر المتصفحات المختلفة. وبالطبع، هذه المشكلة ليست فريدة بالنسبة إلى إضافات Google Classroom، وتؤثر في جميع المواقع الإلكترونية التابعة لجهات خارجية بإطار iframe. لقد سبق أن واجه العديد من شركائنا هذه المشكلة.

في ما يلي بعض الحلول العامة:

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

ومن المتوقّع أن يتم فرض المزيد من القيود على ملفات تعريف الارتباط في إصدارات المتصفّح المستقبلية. أنشِئ طلبات ميزات لإرسال ملاحظات وآراء إلى Google حول كيفية خفض التأثير الذي يتطلبه الشركاء.

تفعيل قابلية اكتشاف الإضافات باستخدام التعبيرات العادية لعناوين URL

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

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

معلّم يختار مرفق الرابط الشكل 1. المعلم الذي يختار مرفق رابط إلى مهمة جديدة.

يلصق المعلّم الرابط. الشكل 2. يلصق المعلم رابطًا من مصدر جهة خارجية. ثبَّت المعلّم إضافة Classroom التابعة للجهة الخارجية من قبل.

مربّع حوار قابلية اكتشاف التعبير العادي الشكل 3. يتم عرض مربع الحوار التفاعلي الذي يتم عرضه إلى المعلّم عندما يتطابق الرابط الذي تم لصقه مع تعبير عادي محدّد من قِبل المطوّر التابع لجهة خارجية.

إذا اختار المعلّم "التجربة الآن" في النافذة المنبثقة كما هو موضّح في الشكل 3، ستتم إعادة توجيهه إلى إطار iframe لاكتشاف المرفقات في الإضافة.