يمكن للمعلّمين إضافة محتوى تابع لجهات خارجية إلى Classroom من خلال لصق رابط كمرفق رابط في صفحة إنشاء المهام الدراسية. للبناء على ما يعرفه المعلّمون، يمكنك الآن ضبط الإضافة للسماح للمعلّمين بترقية مرفق رابط إلى مرفق إضافة.
نظرة عامة
وفي حال ضبط الإضافة باستخدام هذه الميزة، سيُطلَب من المعلّمين ترقية رابط إلى مرفق إضافة عند لصق مرفق رابط في صفحة إنشاء المهمة. يُطلب من المعلمين القيام بذلك فقط إذا كانوا قد تم تثبيت الإضافة بالفعل.
بعد موافقة المعلّم على ترقية الرابط إلى مرفق إضافة، يتم تشغيل إطار iframe لترقية الرابط مع معلَمات طلب البحث التالية:
courseId
itemId
itemType
addOnToken
urlToUpgrade
login_hint
(فقط إذا سبق أن فوَّض المستخدم تطبيقك)
تعكس مَعلمات طلب البحث الأربع الأولى مَعلمات طلب البحث التي تم تشغيلها في
إطار iframe الخاص باكتشاف المرفقات. إنّ معلَمة طلب البحث urlToUpgrade
جديدة ويمكن أن
تساعدك في تقييم كيفية إنشاء مرفق الإضافة. بعد ذلك، يمكنك استخدام مَعلمات طلب البحث الأخرى للتأكّد من أنّ المستخدم قد سجّل الدخول، ويمكنك طلب طريقة CreateAddOnAttachment
، وهي courseWork
أو courseWorkMaterials
أو announcements
استنادًا إلى قيمة itemType
. ضمن iframe، يمكنك عرض شاشة تحميل لإعلام المدرس بأنه يتم إنشاء مرفق الإضافة.
بعد إنشاء مرفق الإضافة، يتم إغلاق إطار iframe وسيتمكّن المعلّم من عرض المرفق في المهمة على النحو المعتاد.
تفاصيل التنفيذ الفني
يلقي هذا القسم الضوء على بعض التفاصيل الفنية المهمة للميزة.
قراءة مَعلمة طلب البحث "urlToUpgrade
"
إنّ معلَمة طلب البحث urlToUpgrade
هي معرّف موارد منتظم (URI) تم ترميزه عند تمريرها في إطار iframe
لترقية الرابط. يجب فك ترميز عنوان URL للحصول عليه بشكله الأصلي. على سبيل المثال، إذا كنت تستخدم JavaScript، يمكنك استخدام الدالة decodeURIComponent()
لإجراء ذلك.
إغلاق إطار iframe الخاص بترقية الرابط
لضمان تقديم أفضل تجربة مستخدم لهذه الميزة، أرسِل postMessage
بعد إنشاء مرفق الإضافة بنجاح. ويؤدي ذلك إلى إغلاق إطار iframe. يمكنك الاطّلاع على صفحة تفاصيل تنفيذ إطار iframe لمزيد من التفاصيل.
تفاصيل الإعدادات
يجب ضبط الإعدادات التالية لدمج هذه الميزة في إضافتك:
عنوان URL لإطار iframe الخاص بترقية الروابط: هو عنوان URL الذي يفتح في إطار iframe عندما يوافق المعلّم على الترقية.
أنماط عناوين URL التي يجب على Classroom رصدها ومحاولة الترقية: يمكن أن تتألف أنماط عناوين URL من مضيف وبادئات مسارات متعددة.
- يمكنك توفير أنماط عناوين URL متعددة.
- إذا لم تقدّم أي بادئات مسار، يمكن ترقية أي عنوان URL يطابق المضيف.
- لا يمكن ترقية سوى عناوين URL التي تستخدم المخطط
https
. - يجب ألا تحتوي أنماط عناوين URL على
localhost
. - يجب ألا تحتوي بادئات المسار على معلَمات طلب بحث أو أجزاء من عنوان URL.
- ويمكن أن تتيح بادئات المسار استخدام أحرف البدل في الوقت الحالي، ولكن لا يمكن للمضيفين:
-
example.com
هو مضيف صالح، و/foo
و/bar/*/baz
هما بادئتا مسار صالحتان. -
example.*.host.com
ليس مضيفًا صالحًا.
-
- يتطابق حرف البدل بين مكونات بادئة المسار مع مكون واحد فقط، ولا يتطابق مع مكونات متعددة مفصولة بشرطة مائلة.
يمكنك استخدام نمط عنوان URL مع المضيف
example.com
وبادئة المسار/bar/*/baz
:-
يعتبر
https://example.com/bar/123/baz
مطابقة صالحة لنمط عنوان URL. -
يعتبر
https://example.com/bar/123/baz/456/789
مطابقة صالحة لنمط عنوان URL. -
https://example.com/bar/123/456/baz
ليس مطابقة صالحة لنمط عنوان URL لأن حرف البدل في بادئة المسار غير مطابق/123/456/
.
-
يعتبر
عملية التطوير
أرسِل عنوان URL لإطار iframe الخاص بترقية الرابط وأنماط عناوين URL لإضافة الاختبار أو الإنتاج من خلال إرسال رسالة إلكترونية إلى classroom-link-upgrade-external@google.com.
يمكنك تقديم إعدادات لأي مشروع على Google Cloud يمثّل إضافة Classroom. ننصحك أولاً بتقديم عمليات ضبط لإضافة ذات مستوى رؤية خاص كي تتمكّن من تطويرها واختبارها في نطاق تجريبي بدون التأثير في المستخدمين المباشرين.
سيصلك ردّ على رسالتك الإلكترونية بعد تفعيل الإعدادات. يُرجى العلم أنّ أنماط عناوين URL التي تستخدِم localhost
غير متوافقة مع هذه الميزة.
يجب تنسيق رسالة البريد الإلكتروني لتتضمّن ما يلي:
Google Cloud Project number: GCP_PROJECT_NUMBER
Link Upgrade iframe URL: LINK_UPGRADE_IFRAME_URL
URL Patterns:
- Host:HOST_1
- Path prefixes:
- PATH_PREFIX_1
- PATH_PREFIX_2
- Host:HOST_2
- Path prefixes:
- PATH_PREFIX_3
- PATH_PREFIX_4
// add more hosts and path prefixes as needed
استبدِل ما يلي:
- GCP_PROJECT_NUMBER: رقم مشروع Google Cloud الذي ترتبط به الإضافة
- LINK_UPGRADE_IFRAME_URL: عنوان URL الذي من المفترض أن يتم فتحه في إطار iframe الخاص بترقية الروابط
- HOST_1: مضيف يجب أن يرصده Classroom. لا يتوافق سوى المخطط
https
. - PATH_PREFIX_1 وPATH_PREFIX_2: بادئات المسار المرتبطة بالنطاق
HOST_1
والتي يجب أن يرصدها Classroom ويحاول ترقيتها. - HOST_2: مضيف يجب أن يرصده Classroom. لا يتوافق سوى المخطط
https
. - PATH_PREFIX_3 وPATH_PREFIX_4: بادئات المسار المرتبطة بالنطاق
HOST_2
والتي يجب أن يرصدها Classroom ويحاول ترقيتها.
تجربة المستخدم التي ننصح بها
في ما يلي بعض الاقتراحات التي يجب أخذها في الاعتبار عند استخدام هذه الميزة.
تجنُّب العمل الإضافي على المعلّمين
ننصحك بشدة باستخدام إطار iframe لتسهيل تسجيل الدخول، إذا كان ذلك مطلوبًا، أو لعرض مؤشر تحميل. لتقديم أفضل تجربة للمستخدم، يجب ألا يُطلب من المعلّم أي معلومات إضافية بعد الموافقة على ترقية الرابط الذي تم لصقه إلى مرفق إضافة. ومع ذلك، إذا لم يكن ذلك ممكنًا بالنسبة إلى الإضافة، يمكنك استخدام إطار iframe لترقية الرابط لجمع المعلومات الإضافية التي تحتاجها. يمكن أيضًا استخدام إطار iframe لإبلاغ المعلّم إذا كانت ترقية الرابط غير ممكنة أو في حال حدوث خطأ ما.
تضمين رسائل خطأ بشأن الوصول السهل
إذا لصق المعلّمون رابطًا لا يمكنهم الوصول إليه وتمّت ترقيته، يمكنك عرض رسالة خطأ سهلة الاستخدام في إطار iframe حتى يكون المعلّمون على دراية بالمشكلة. ويمكن أيضًا استخدام إطار iframe لمنح المعلّم الأذونات المناسبة للوصول إلى المحتوى.