يتم تحميل إضافات Classroom ضمن إطار iframe لتوفير المستخدم النهائي مع تجربة مستخدم سلسة ومريحة. هناك أربعة أنواع أنواع iframe، الاطّلاع على صفحات إطارات iframe في دليل رحلات المستخدم نظرة عامة على الغرض من كل إطار iframe ومظهره.
إرشادات أمان إطار iframe
على الشركاء اتّباع أفضل الممارسات المتّبعة في المجال لتأمين إطار iframe. لحماية إطار iframe، ينصح فريق الأمان بما يلي:
بروتوكول HTTPS مطلوب. نوصي بشدة باستخدام طبقة النقل الآمنة (TLS) الإصدار 1.2 أو الإصدارات الأحدث تفعيل الأمان المشدَّد لنقل البيانات باستخدام بروتوكول HTTP. راجع MDN (MDN) ذي الصلة هذا حول "الأمان المشدَّد لنقل البيانات".
تفعيل سياسة أمان المحتوى الصارم عرض OWASP هذا ومقالة MDN المتعلقة بسياسة أمان المحتوى
فعِّل سمة ملفات تعريف الارتباط الآمنة. اطّلِع على سمة HttpOnly وهذا مقالة حول ملفات تعريف الارتباط MDN ذات الصلة.
إعداد معرّف الموارد المنتظم (URI) لإطار iframe
عنوان URI لإعداد المرفقات هو ما يُحمِّله إطار iframe لاكتشاف المرفقات، هي المكان الذي يبدأ فيه المعلمون عملية إنشاء مرفقات الإضافات على مشاركة حول Classroom ويمكن إعداده في وحدة تحكُّم المشروع على Google Cloud. ضبط معرّف الموارد المنتظم (URI) هذا في واجهة برمجة التطبيقات لمشروع 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
هي معرّف للمرفق.مضمّنة في
teacherViewUri
وstudentViewUri
studentWorkReviewUri
إطارات iframe- رقم تعريف المَهمّة الدراسية المرسَلة
تمثّل القيمة
submissionId
معرّفًا لعمل الطالب، ولكن يجب استخدامه معattachmentId
لتحديد عمل الطالب في مهمة معينة.تتوفّر هذه الميزة في
studentWorkReviewUri
.
- الرمز المميّز للإضافة
القيمة
addOnToken
هي رمز تفويض مميز يُستخدم لإنشاءaddOnAttachments.create
مكالمة لإنشاء الإضافة.تم تضمينه في إطار iframe الخاص باكتشاف المرفقات وترقية الرابط iframe.
- عنوان URL المطلوب ترقيته
يشير وجود القيمة
urlToUpgrade
إلى أنّأدرج المعلّم مرفقًا لرابط في المهمة، ووافق على لترقيته إلى مرفق إضافة. إذا لم يكن لديك هذا بالفعل الميزات التي تمت تهيئتها، يُرجى الاطلاع على الدليل حول ترقية الروابط إلى الوظائف الإضافية المرفقات للاطّلاع على مزيد من التفاصيل.
تم تضمينه في إطار iframe لترقية الرابط.
المَعلمات ذات الصلة بتسجيل الدخول
توفّر معلَمة طلب البحث login_hint
معلومات عن
مستخدم في Classroom يزور صفحة الويب الخاصة بالإضافة معلمة طلب البحث هذه
على عنوان URL src
لإطار iframe. يتم إرسال الرسالة بعد أن سبق للمستخدم استخدامها.
الإضافة للمساعدة في تقليل الصعوبات التي يواجهها المستخدم عند تسجيل دخوله. عليك التعامل مع
معلمة طلب البحث هذه في تنفيذ الإضافة.
- تلميح تسجيل الدخول
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) لاكتشاف المرفقات هو
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 للموارد التي يمكن الوصول إليها في إضافتك. يرفق معلّم رابطًا يتطابق مع أحد الروابط. من التعبيرات العادية يظهر مربع حوار يمكن إغلاقه لتشجيعهم على محاولة الإضافة التي تريدها. ولن يظهر لهم مربّع الحوار إلا إذا تم تثبيت الإضافة من قبل في حساباتهم.
إذا كنت ترغب في تقديم هذا السلوك للمعلّمين، قدِّم بياناتك في جهات الاتصال باستخدام التعبيرات العادية المناسبة. إذا كانت التعبيرات العادية التي تقدمها أوسع مما ينبغي أو تتعارض مع إضافة أخرى، فقد تعديلها لتكون أكثر تقييدًا أو تميزًا.
الشكل 1. المعلّم يختار رابطًا مرفق بمهمة جديدة.
الشكل 2. معلّم يلصق رابطًا من جهة خارجية المصدر. ثبَّت المعلّم بالفعل برنامج تشغيل الجهة الخارجية إضافة Classroom
الشكل 3. تم عرض مربع الحوار التفاعلي إلى المعلم عندما يتطابق الرابط الذي تم لصقه مع تعبير عادي محدد بواسطة مطور الطرف الثالث.
إذا اختار المعلّم "التجربة الآن" في البوب كما هو موضح في الشكل 3، تتم إعادة توجيهها إلى إطار iframe لاكتشاف المرفقات في الإضافة.