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

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

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

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

إعدادات تطبيق الخادم

لحماية إطار iframe، ننصحك بإجراء إعدادات الخادم التالية:

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

تُمرِّر إطارات 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 إلى أنّ المعلّم قد أدرج مرفق رابط في المهمة ووافق على ترقيته إلى مرفق إضافة. إذا لم يسبق لك إعداد هذه الميزة، يمكنك الاطّلاع على الدليل حول ترقية الروابط لإضافة مرفقات للحصول على مزيد من التفاصيل.

مضمّن في إطار Link Upgrade‏ 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) الخاص بميزة "اكتشاف المرفقات" وهو https://example.com/addon.
  2. يثبّت المعلّم هذه الإضافة وينشئ إشعارًا أو مهمة دراسية أو مادة جديدة ضمن إحدى دوراته التدريبية. على سبيل المثال، itemId=234 وitemType=courseWork وcourseId=123.
  3. أثناء إعداد هذا العنصر، يختار المعلّم الإضافة المثبَّتة حديثًا كمرفق.
  4. ينشئ Classroom إطار iframe مع ضبط عنوان URL للمصدر على https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456.
    1. ينفّذ المعلّم العمل داخل الإطار المتضمّن لاختيار مرفق.
  5. عند اختيار المرفق، يرسل التطبيق الإضافي postMessage إلى Classroom لإغلاق إطار iframe.

إطارات iframe الخاصة بـ teacherViewUri وstudentViewUri

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

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

السمة الوصف
مطلوب لا (تحديد ما إذا كان هذا المرفق من نوع نشاط)
معرّف الموارد المنتظم (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+port المتوافق مع معرّف الموارد المنتظم (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 من داخل الإطار

يجب أن يتطابق النطاق+المنفذ الخاصان بالصفحة التي ترسل الحدث postMessage مع النطاق+المنفذ الخاصين بمعرّف الموارد الموحّد المستخدَم لتشغيل إطار 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 الخاص بميزة "اقتراح المرفقات" في الإضافة.