ترقية مرفقات الرابط إلى مرفقات إضافة 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() لإجراء ذلك.

لضمان أفضل تجربة مستخدم لهذه الميزة، أرسِل 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 لمنح المعلّم الأذونات المناسبة للوصول إلى المحتوى.