ترقية مرفقات الرابط إلى مرفقات إضافة Classroom

يمكن للمعلّمين إضافة محتوى تابع لجهات خارجية إلى 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 لإضافة الاختبار أو الإنتاج من خلال إرسال رسالة إلكترونية إلى [e-mail].

يمكنك أولاً تقديم إعدادات إضافتك الخاصة وأي بيئة اختبار أو تطوير تملكها. يمكن لفريق Classroom تفعيل إعدادات الاختبار هذه قبل تفعيل إعدادات الإنتاج للسماح لك باختبار التدفق في النطاق التجريبي. سيصلك ردّ على رسالتك الإلكترونية بعد تفعيل الإعدادات يُرجى العلم أنّ أنماط عناوين URL التي تستخدم localhost غير متوافقة مع هذه الميزة.

ملاحظة مهمة: يمكن للمستخدمين الذين يمكنهم تثبيت الإضافة واستخدامها ترقية الروابط المؤدية إلى مرفقات الإضافات فور تفعيل الإعدادات من قِبل فريق Classroom. لهذا السبب، من المهم أولاً توفير عمليات ضبط للإضافة التجريبية في بيئة اختبار أو بيئة تطوير قبل تقديم أي إعدادات للإنتاج.

يجب تنسيق رسالة البريد الإلكتروني لتتضمّن ما يلي:

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 لمنح المعلّم الأذونات المناسبة للوصول إلى المحتوى.