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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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`

إطار iframe `studentWorkReviewUri`

إطار 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 يتم ترميزها باستخدام معرّف 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 من إطار iframe

يجب أن يتطابق نطاق+المنفذ للصفحة التي تُرسِل حدث postMessage مع نطاق+المنفذ لمعرّف URI المستخدَم لتشغيل إطار iframe، وإلا سيتم تجاهل الرسالة. الحل البديل هو إعادة التوجيه إلى صفحة على النطاق الأصلي لا تفعل شيئًا سوى إرسال حدث postMessage.

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

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

القيود

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

• 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 "اكتشاف المرفقات" الخاص بالإضافة.