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

يمكن للمعلّمين إضافة محتوى تابع لجهة خارجية إلى Classroom من خلال لصق الرابط على أنّه مرفق رابط في صفحة إنشاء المهمة. بناءً على الميزات التي يعرفها المعلّمون، يمكنك الآن ضبط الإضافة للسماح للمعلّمين بترقية مرفق رابط إلى مرفق إضافة.

نظرة عامة

في حال ضبط الإضافة باستخدام هذه الإمكانية، سيُطلب من المعلّمين ترقية رابط إلى مرفق إضافة عند لصق مرفق "رابط" في صفحة إنشاء المهمة. يُطلب من المعلِّمين إجراء ذلك فقط إذا كان لديهم الإضافة مثبّتة لديهم.

بعد موافقة المعلّم على ترقية الرابط إلى مرفق إضافة، يتم إطلاق إطار iframe لترقية الرابط باستخدام معلَمات طلب البحث التالية:

• courseId
• itemId (تمت إعادة التسمية من postId)
• itemType (جديد!)
• addOnToken
• ‫login_hint أو hd
• urlToUpgrade (جديد!)

تتطابق أول أربع مَعلمات طلب البحث مع مَعلمات طلب البحث التي تم إطلاقها في إطار 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 وأنماط عناوين 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 أيضًا لتزويد المعلم بالأذونات المناسبة للوصول إلى المحتوى.