يتم تحميل إضافات Classroom ضمن إطار iframe لتوفير تجربة مستخدم سلسة وملائمة. هناك أربعة أنواع مختلفة من إطارات iframe، ويمكنك الاطّلاع على صفحات إطارات iframe في دليل رحلات المستخدم للحصول على نظرة عامة على الغرض من كل إطار iframe ومظهره.
إرشادات أمان إطار iframe
على الشركاء اتّباع أفضل الممارسات المتّبعة في المجال لتأمين إطار iframe. لحماية إطار iframe، ينصح فريق الأمان بما يلي:
بروتوكول HTTPS مطلوب. ننصح بشدة باستخدام الإصدار 1.2 من بروتوكول أمان طبقة النقل (TLS) أو إصدار أحدث وتفعيل الأمان المشدَّد لنقل البيانات باستخدام بروتوكول HTTP. يُرجى الاطّلاع على مقالة MDN ذات الصلة حول الأمان المشدَّد لنقل البيانات.
تفعيل سياسة أمان المحتوى الصارم يُرجى الاطّلاع على مقالة OWASP ومقالة MDN المتعلقة بسياسة أمان المحتوى ذات الصلة.
فعِّل سمة ملفات تعريف الارتباط الآمنة. راجِع سمة HttpOnly ومقالة MDN الخاصة بملفات تعريف الارتباط هذه ذات الصلة.
إعداد معرّف الموارد المنتظم (URI) لإطار iframe
معرّف الموارد المنتظم (URI) لإعداد المرفقات هو ما يتم تحميله في إطار iframe الخاص باكتشاف المرفقات، والذي يبدأ فيه المعلمون عملية إنشاء مرفقات الإضافات في مشاركة على Classroom. ويمكن إعداده في وحدة تحكُّم المشروع على Google Cloud. يمكنك إعداد معرّف الموارد المنتظم (URI) هذا في واجهة برمجة التطبيقات والخدمة لمشروع Google Cloud > حزمة تطوير برامج 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
. ويتم إرساله عندما سبق أن استخدم المستخدم الإضافة
للمساعدة في تقليل الصعوبات التي تواجهك عند تسجيل دخول المستخدم النهائي عليك التعامل مع معلمة طلب البحث هذه
عند تنفيذ الإضافة.
- تلميح تسجيل الدخول
login_hint
هو معرّف فريد لحساب المستخدِم على Google.الحساب. بعد أن يسجّل المستخدم الدخول إلى الإضافة للمرة الأولى، يتم تمرير المَعلمة
login_hint
في كل زيارة لاحقة إلى الإضافة من قِبل المستخدم نفسه.هناك استخدامان محتملان للمَعلمة
login_hint
:- مرِّر قيمة
login_hint
أثناء مسار المصادقة حتى لا يحتاج المستخدم إلى إدخال بيانات الاعتماد عند ظهور مربّع حوار تسجيل الدخول. لا يتم تسجيل دخول المستخدم تلقائيًا. - بعد أن يسجّل المستخدم دخوله، استخدِم هذه المَعلمة لمقارنة القيمة بأيّ مستخدِمين قد سجّلت الدخول إلى الإضافة من قبل. إذا عثرت على تطابق، يمكنك ترك المستخدم مسجّلاً الدخول وتجنب عرض خطوات تسجيل الدخول. إذا لم تتطابق المَعلمة مع أي من المستخدمين الذين سجّلوا الدخول، اطلب من المستخدم تسجيل الدخول باستخدام زر تسجيل الدخول الذي يحمل علامة Google التجارية.
مضمّنة مع جميع إطارات iframe
- مرِّر قيمة
إطار iframe لاكتشاف المرفقات
السمة | الوصف |
---|---|
مطلوب | نعم |
معرّف الموارد المنتظم (URI) | تم توفيره في البيانات الوصفية للإضافة |
معلمات طلب البحث | "courseId " و"itemId " و"itemType "
وaddOnToken وlogin_hint |
الطول | ارتفاع النافذة 80% مطروحًا منه 60 بكسل للعنوان العلوي |
العرض | الحد الأقصى هو 1600 بكسل عرض النافذة بنسبة 90% عندما يكون عرض النافذة <= 600 بكسل عرض النافذة بنسبة% 80 عندما يكون عرض النافذة أكبر من 600 بكسل |
مثال على سيناريو اكتشاف المرفقات
- تم تسجيل إضافة Classroom في Google Workspace
Marketplace باستخدام معرّف موارد منتظم (URI) لـ Pending Discovery في
https://example.com/addon
. - يثبّت المعلِّم هذه الإضافة وينشئ إشعارًا أو مهمة أو مادة
جديدة في إحدى دوراته التدريبية. على سبيل المثال،
itemId=234
وitemType=courseWork
وcourseId=123
. - أثناء ضبط هذا العنصر، يختار المعلّم الإضافة المثبَّتة حديثًا كمرفق.
- ينشئ Classroom إطار iframe مع ضبط عنوان URL للسمة src على
https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456
.- ينفذ المعلم عملاً ضمن إطار iframe لاختيار مرفق.
- عند اختيار المرفقات، ترسل الإضافة
postMessage
إلى Classroom لإغلاق إطار iframe.
إطارات iframe الخاصة بالمعلِّمينViewUri وstudentViewUri
السمة | الوصف |
---|---|
مطلوب | نعم |
معرّف الموارد المنتظم (URI) | teacherViewUri أو studentViewUri |
معلمات طلب البحث | "courseId " و"itemId " و"itemType "
وattachmentId وlogin_hint |
الطول | ارتفاع النافذة 100% مطروحًا منه 140 بكسل للعنوان العلوي |
العرض | عرض النافذة: 100% |
إطار iframe الخاص بـ userWorkReviewUri
السمة | الوصف |
---|---|
مطلوب | لا (يحدد ما إذا كان هذا مرفقًا من نوع نشاط) |
معرّف الموارد المنتظم (URI) | studentWorkReviewUri |
معلمات طلب البحث | "courseId " و"itemId " و"itemType "
وattachmentId وsubmissionId وlogin_hint |
الطول | ارتفاع النافذة 100% مطروحًا منه 168 بكسل للعنوان العلوي |
العرض | عرض النافذة بنسبة 100% مطروحًا منه عرض الشريط الجانبي<> يكون الشريط الجانبي 312 بكسل عند التوسيع و56 بكسل عند التصغير |
إطار iframe لترقية الرابط
السمة | الوصف |
---|---|
مطلوب | نعم، إذا كانت الإضافة تتيح ترقية الروابط إلى مرفقات الإضافات. |
معرّف الموارد المنتظم (URI) | تم توفيره في البيانات الوصفية للإضافة |
معلمات طلب البحث | "courseId " و"itemId " و"itemType "
وaddOnToken وurlToUpgrade وlogin_hint |
الطول | ارتفاع النافذة 80% مطروحًا منه 60 بكسل للعنوان العلوي |
العرض | الحد الأقصى هو 1600 بكسل عرض النافذة بنسبة 90% عندما يكون عرض النافذة <= 600 بكسل عرض النافذة بنسبة% 80 عندما يكون عرض النافذة أكبر من 600 بكسل |
مثال على سيناريو ترقية الرابط
- تم تسجيل إضافة Classroom باستخدام معرّف الموارد المنتظم (URI) لترقية الرابط
https://example.com/upgrade
. أنّك قدّمت أنماط البادئة التالية للمضيف ومسار لمرفقات الروابط التي يجب أن يحاول Classroom الترقية إلى مرفق إضافة:- المضيف هو
example.com
وبادئة المسار/quiz
.
- المضيف هو
- ينشئ المعلم إعلانًا أو مهمة أو مادة جديدة ضمن إحدى دوراته التدريبية. على سبيل المثال،
itemId=234
وitemType=courseWork
وcourseId=123
. - يلصق المعلّم رابطًا،
https://example.com/quiz/5678
، في مربّع حوار "مرفقات" الذي يطابق نمط عنوان URL الذي قدّمته. بعد ذلك، يُطلب من المدرس ترقية الرابط إلى مرفق إضافة. يُطلق Classroom إطار iframe الخاص بترقية الروابط مع ضبط عنوان URL على
https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678
.عليك تقييم معلَمات طلب البحث التي تم تمريرها في إطار iframe وإجراء طلب إلى نقطة نهاية
CreateAddOnAttachment
. يُرجى العِلم أنّ معلَمة طلب البحثurlToUpgrade
هي معرّف موارد منتظم (URI) تم ترميزه عند ضبطه على إطار iframe. تحتاج إلى فك ترميز المعلمة للحصول عليها بشكلها الأصلي. على سبيل المثال، توفّر لغة JavaScript الوظيفةdecodeURIComponent()
.عند إنشاء مرفق إضافة من رابط بنجاح، يمكنك إرسال
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
المغلق. وكملاحظة جانبية، ستتم إزالة الرابط التشعبي "فتح في اسم الشريك" حتى لا ينشئ المستخدمون علامات تبويب بهذه الطريقة في المستقبل القريب.
الشروط
يتم فتح جميع إطارات 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 لاكتشاف المرفقات في الإضافة.