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

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

نظرة عامة

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

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

• courseId
• itemId
• itemType
• addOnToken
• urlToUpgrade
• login_hint (فقط إذا سبق للمستخدم تفويض تطبيقك)

تعكس مَعلمات طلب البحث الأربع الأولى مَعلمات طلب البحث التي تم إطلاقها في إطار iframe لميزة "اكتشاف المرفقات". مَعلمة طلب البحث urlToUpgrade هي مَعلمة جديدة ويمكن أن تساعدك في تقييم كيفية إنشاء مرفق الإضافة. بعد ذلك، يمكنك استخدام مَعلمات طلب البحث الأخرى للتحقّق مما إذا كان المستخدم مسجّلاً الدخول، ثم استدعاء CreateAddOnAttachment طريقة courseWork أو courseWorkMaterials أو announcements استنادًا إلى قيمة itemType. ضمن إطار iframe، يمكنك عرض شاشة تحميل للإشارة إلى المعلّم بأنّه يتم إنشاء مرفق الإضافة.

بعد إنشاء مرفق الإضافة، يتم إغلاق إطار iframe ويمكن للمعلّم الاطّلاع على المرفق في المهمة على النحو المعتاد.

تفاصيل التنفيذ الفنية

يسلّط هذا القسم الضوء على بعض التفاصيل الفنية المهمة للميزة.

قراءة مَعلمة طلب البحث urlToUpgrade

إنّ مَعلمة طلب البحث urlToUpgrade هي معرّف موارد منتظم مُشفَّر عند تمريرها في إطار iframe الخاص بـ Link Upgrade. يجب فك ترميز عنوان 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 لتسهيل تسجيل الدخول، إذا كان ذلك مطلوبًا، أو لعرض مؤشر تحميل. لتوفير أفضل تجربة مستخدم، يجب عدم مطالبة المعلّم بأي معلومات إضافية بعد أن يقبل ترقية الرابط الذي تم لصقه إلى مرفق إضافي. ومع ذلك، إذا لم يكن ذلك ممكنًا لإضافة Chrome، يمكنك استخدام عنصر iframe في رابط الترقية لجمع المعلومات الإضافية التي تحتاج إليها. يمكن أيضًا استخدام عنصر iframe لإعلام المعلّم إذا لم يكن من الممكن ترقية الرابط أو إذا حدث خطأ.

تضمين رسائل خطأ سهلة الاستخدام بشأن الوصول

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