پیوست‌های پیوند را به پیوست‌های Classroom ارتقا دهید

یکی از راه هایی که معلمان محتوای شخص ثالث را به Classroom اضافه می کنند، قرار دادن پیوندی به عنوان پیوست پیوند در صفحه ایجاد تکلیف است. برای ایجاد آنچه معلمان قبلاً با آن آشنا هستند، اکنون می‌توانید برافزای خود را طوری پیکربندی کنید که به معلمان اجازه دهد پیوست پیوند پیوند را به پیوست افزودنی ارتقا دهند.

نمای کلی

اگر افزونه خود را با این قابلیت پیکربندی کنید، از معلمان خواسته می‌شود تا زمانی که پیوست پیوند را در صفحه ایجاد تکلیف جای‌گذاری می‌کنند، پیوندی را به یک پیوست افزودنی ارتقا دهند. فقط در صورتی از معلمان خواسته می شود که این افزونه را نصب کرده باشند.

هنگامی که معلم موافقت می کند پیوند را به یک پیوست افزودنی ارتقا دهد، iframe ارتقاء لینک با پارامترهای جستجوی زیر راه اندازی می شود:

  • courseId
  • itemId
  • itemType
  • addOnToken
  • urlToUpgrade
  • login_hint (فقط در صورتی که کاربر قبلاً برنامه شما را مجاز کرده باشد)

چهار پارامتر پرس و جو اول منعکس کننده پارامترهای پرس و جو راه اندازی شده در iframe Attachment Discovery هستند. پارامتر پرس و جو urlToUpgrade جدید است و می تواند به شما در ارزیابی نحوه ایجاد پیوست افزودنی کمک کند. سپس، می‌توانید از سایر پارامترهای پرس و جو برای بررسی اینکه آیا کاربر به سیستم وارد شده است یا نه استفاده کنید و روش CreateAddOnAttachment courseWork ، courseWorkMaterials یا announcements بر اساس مقدار itemType فراخوانی کنید. در iframe، می‌توانید صفحه بارگیری را نمایش دهید تا به معلم نشان دهد که پیوست افزودنی در حال ایجاد است.

هنگامی که پیوست افزودنی ایجاد شد، iframe بسته می‌شود و معلم می‌تواند پیوست را در تکالیف به‌طور معمول مشاهده کند.

جزئیات پیاده سازی فنی

این بخش برخی از جزئیات فنی مهم را برای این ویژگی برجسته می کند.

پارامتر پرس و جو urlToUpgrade را بخوانید

پارامتر پرس و جو urlToUpgrade زمانی که در iframe Link Upgrade ارسال می شود، URI رمزگذاری می شود. شما باید URL را رمزگشایی کنید تا آن را به شکل اصلی دریافت کنید. برای مثال، اگر از جاوا اسکریپت استفاده می کنید، می توانید از تابع decodeURIComponent() برای این کار استفاده کنید.

برای اطمینان از تجربه کاربری بهینه برای این ویژگی، پس از ایجاد موفقیت آمیز پیوست افزونه، یک postMessage ارسال کنید. با این کار iframe بسته می شود. برای جزئیات بیشتر به صفحه جزئیات پیاده سازی iframe مراجعه کنید.

جزئیات پیکربندی

برای ادغام این ویژگی در افزونه شما، تنظیمات زیر مورد نیاز است:

  • URL برای iframe ارتقاء پیوند : این نشانی اینترنتی است که وقتی معلمی با ارتقا موافقت می کند در iframe باز می شود.

  • الگوهای نشانی وب که Classroom باید شناسایی کند و برای ارتقاء آن تلاش کند : الگوهای 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/ مطابقت ندارد.

فرآیند توسعه

از طریق ایمیل classroom-link-upgrade-external@google.com، نشانی وب iframe و الگوهای URL ارتقا پیوند را برای افزونه آزمایشی یا تولیدی خود ارسال کنید.

می‌توانید برای هر پروژه 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 : نشانی اینترنتی که باید در 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 برای تسهیل ورود به سیستم یا نمایش نشانگر بارگیری استفاده کنید. برای بهترین تجربه کاربری، پس از موافقت معلم برای ارتقاء پیوند چسبانده شده به پیوست افزودنی، نباید از معلم خواسته شود که اطلاعات بیشتری دریافت کند. با این حال، اگر این امکان برای افزونه شما وجود ندارد، می توانید از Link Upgrade iframe برای جمع آوری اطلاعات اضافی مورد نیاز خود استفاده کنید. همچنین می‌توان از iframe برای اطلاع معلم در صورت عدم امکان ارتقاء لینک یا خطا استفاده کرد.

پیام‌های خطای دسترسی کاربرپسند را وارد کنید

اگر معلمان پیوندی را که به آن دسترسی ندارند جای‌گذاری و ارتقا دهند، یک پیام خطای کاربرپسند در iframe نمایش دهند تا معلمان از این مشکل آگاه شوند. همچنین می توان از iframe برای ارائه مجوزهای مناسب برای دسترسی به محتوا به معلم استفاده کرد.