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

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

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

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

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

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

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

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

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

تُرسِل إطارات 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. ويتم إرسالها عندما يكون المستخدم قد استخدم إضافة Chrome في السابق للمساعدة في تقليل المشاكل التي يواجهها المستخدم النهائي عند تسجيل الدخول. عليك معالجة مَعلمة طلب البحث هذه في عملية تنفيذ الإضافة.

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

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 باستخدام معرّف الموارد المطلق لاكتشاف المرفقات 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. ينفّذ المعلّم عملًا داخل إطار iframe لاختيار مرفق.
  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 باستخدام معرّف الموارد المنتظم لرابط الترقية التالي: 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 تكون بترميز معرّف الموارد المنتظم عند تمريرها إلى إطار iframe. عليك فك ترميز المَعلمة للحصول عليها بصورتها الأصلية. على سبيل المثال، توفّر JavaScript الدالة decodeURIComponent().

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

إغلاق إطار iframe

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

<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 هو النطاق+المنفذ نفسهما لعنوان URL المستخدَم لبدء إطار 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 للموارد التي يمكن الوصول إليها في إضافة البيانات. إذا أرفق المعلّم رابطًا يتطابق مع أحد تعبيراتك العادية، سيظهر له مربّع حوار قابل للإغلاق يشجّعه على تجربة إضافة Chrome. لن يظهر لهم مربّع الحوار إلا إذا سبق تثبيت الإضافة لحسابهم.

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

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

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

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

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