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

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

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

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

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

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

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

تُستخدم بادئات معرف الموارد المنتظم (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:

  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 الذي يحتوي على معرّف موارد منتظم (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 الخاصة بالمعلِّمين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 بكسل عند التصغير

السمة الوصف
مطلوب نعم، إذا كانت ترقية الروابط إلى مرفقات الإضافات هي التي تدعمها إضافتك.
معرّف الموارد المنتظم (URI) تم توفيره في البيانات الوصفية للإضافة
معلمات طلب البحث courseId، itemId، itemType، addOnToken وurlToUpgrade وlogin_hint
الطول ارتفاع النافذة 80% مطروحًا منه 60 بكسل للعنوان العلوي
العرض الحد الأقصى هو 1600 بكسل
عرض النافذة بنسبة 90% عندما يكون حجم النافذة <= 600 بكسل عريض
يكون 80% من عرض النافذة عندما تكون النافذة > عرض 600 بكسل
  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+ المُطابق لمعرّف الموارد المنتظم (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 لاكتشاف المرفقات في الإضافة.