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

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

نمای کلی

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

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

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

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

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

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

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

پارامتر کوئری urlToUpgrade را بخوانید

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

بستن iframe ارتقاء لینک

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

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

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

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

• الگوهای URL که Classroom باید تشخیص داده و برای ارتقاء آنها تلاش کند : الگوهای URL می‌توانند شامل یک میزبان و چندین پیشوند مسیر باشند.

  • شما می‌توانید چندین الگوی URL ارائه دهید.
  • اگر هیچ پیشوند مسیری ارائه ندهید، هر URL که با میزبان مطابقت داشته باشد، می‌تواند ارتقا یابد.
  • فقط URL هایی که دارای طرح https هستند قابل ارتقا هستند.
  • الگوهای URL نباید شامل localhost باشند.
  • پیشوندهای مسیر نباید شامل پارامترهای پرس و جو یا قطعات URL باشند.
  • پیشوندهای مسیر در حال حاضر می‌توانند از کاراکترهای جایگزین پشتیبانی کنند، اما میزبان‌ها نمی‌توانند:
    • example.com یک میزبان معتبر است و /foo و /bar/*/baz پیشوندهای مسیر معتبری هستند.
    • example.*.host.com یک میزبان معتبر نیست.
  • یک wildcard بین اجزای پیشوند مسیر فقط با یک جزء واحد مطابقت دارد و با چندین جزء که با اسلش جدا شده‌اند مطابقت ندارد. یک الگوی 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 معتبر برای تطبیق نیست زیرا کاراکتر wildcard در پیشوند مسیر با /123/456/ مطابقت ندارد.

فرآیند توسعه

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