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

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

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

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

• يجب استخدام بروتوكول HTTPS. ننصحك بشدة باستخدام بروتوكول أمان طبقة النقل (TLS) 1.2 أو إصدار أحدث وتفعيل الأمان المشدَّد لنقل البيانات باستخدام بروتوكول HTTP. اطّلِع على مقالة MDN ذات الصلة حول سياسة "الأمان المشدَّد لنقل البيانات".

• فعِّل سياسة أمان المحتوى الصارمة. يمكنك الاطّلاع على مقالة OWASP هذه ومقالة MDN ذات الصلة بسياسة أمان المحتوى.

• فعِّل سمة ملفّ تعريف الارتباط الآمن. اطّلِع على سمة HttpOnly ومقالة MDN حول ملفات تعريف الارتباط المتعلّقة بهذه السمة.

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

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

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

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

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

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

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

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

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

إطار iframe لميزة "اكتشاف المرفقات"

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

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

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

رابط ترقية إطار iframe

مثال على سيناريو ترقية الرابط

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 تكون بترميز معرّف الموارد المنتظم عند تمريرها إلى إطار 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 لميزة "اكتشاف المرفقات" في الإضافة.