שדרוג קובצי הקישור שצורפו לקבצים מצורפים ב-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 גם כדי לתת למורה את ההרשאות המתאימות לגישה לתוכן.