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

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

إرشادات الأمان في إطار iframe

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

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

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

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

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

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

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

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

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

تمثّل القيمة courseId معرّفًا للدورة التدريبية.

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

معرّف المشاركة (متوقّف نهائيًا)

تمثل القيمة postId معرّف المشاركة (الإعلان أو عمل الدورة التدريبية أو مواد عمل الدورة التدريبية) التي تم إرفاق هذا المرفق بها.

مضمّنة مع جميع إطارات 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 الخاص بـ src لإطار iframe. يتم إرسال هذه الرسالة عندما يكون المستخدم قد استخدم إضافتك في السابق للمساعدة في تقليل الصعوبات التي قد تواجه المستخدم في عملية تسجيل الدخول. عليك التعامل مع معلَمة طلب البحث هذه عند تنفيذ الإضافة.

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

إنّ السمة login_hint هي معرّف فريد لواجهة المستخدم في Google

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

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

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

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

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

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

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

  1. تم تسجيل إحدى إضافات Classroom في Google Workspace Marketplace باستخدام معرّف الموارد المنتظم (URI) لاكتشاف المرفقات بقيمة 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 في teacherViewUri وstudentViewUri

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

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

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

السمة الوصف
مطلوبة نعم، إذا كانت إضافتك متوافقة مع ترقية الروابط إلى مرفقات الإضافات.
معرّف الموارد المنتظم (URI) تتوفر في البيانات الوصفية للإضافة
مَعلمات طلب البحث courseId وpostId (متوقف نهائيًا) و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&postId=234&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 المغلق. كملاحظة جانبية، تتم إزالة الرابط التشعّبي "Open in Partner Name" (فتح في اسم الشريك) كي لا ينشئ المستخدمون علامات تبويب بهذه الطريقة في المستقبل القريب.

القيود

يتم فتح جميع إطارات 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 لاكتشاف المرفقات في الإضافة.