تتوفّر الآن إضافات Google Classroom بشكل عام للمطوّرين. يُرجى الاطّلاع على مستندات الإضافات للحصول على مزيد من المعلومات.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

نظرة عامة

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

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

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

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

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

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

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

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

إنّ مَعلمة طلب البحث urlToUpgrade هي عنوان URL مُشفَّر عند تمريرها في إطار 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 لإضافة الاختبار أو الإصدار العلني من خلال إرسال رسالة إلكترونية إلى 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 لمنح المعلّم الأذونات المناسبة للوصول إلى المحتوى.