ترقية مرفقات الرابط إلى مرفقات إضافة 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].

يمكنك تقديم إعدادات لأي مشروع على Google Cloud يمثّل إضافة في 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 لمنح المعلّم الأذونات المناسبة للوصول إلى المحتوى.