שדרוג קובצי הקישור שצורפו לקבצים מצורפים ב-Classroom

אחת הדרכים שבהן מורים מוסיפים תוכן של צד שלישי ל-Classroom היא מדביקים קישור כקובץ מצורף של קישור בדף ליצירת המטלה. כדי ליצור על מה שהמורים כבר מכירים, עכשיו אפשר להגדיר את התוסף לאפשר למורים לשדרג קובץ מצורף של קישור לקובץ מצורף של תוסף.

סקירה כללית

אם הגדרתם את התוסף עם היכולת הזו, המורים יתבקשו לשדרג קישור לקובץ מצורף של תוסף כאשר הם מדביקים קובץ מצורף של קישור ב דף ליצירת מטלה. המורים מתבקשים לעשות זאת רק אם הם כבר להתקין את התוסף.

לאחר שהמורה יסכים לשדרג את הקישור לקובץ מצורף של תוסף, הקישור ה-iframe של השדרוג מופעל עם הפרמטרים הבאים של השאילתה:

  • courseId
  • itemId
  • itemType
  • addOnToken
  • urlToUpgrade
  • login_hint (רק אם המשתמש כבר אישר את האפליקציה)

ארבעת הפרמטרים הראשונים של השאילתה משקפים את הפרמטרים של השאילתה שהופעלו קובץ iframe מסוג Discovery. פרמטר השאילתה urlToUpgrade הוא חדש ויכול יעזרו לכם להעריך איך ליצור את הקובץ המצורף של התוסף. לאחר מכן, אפשר להשתמש את הפרמטרים האחרים של השאילתה, כדי לבדוק אם המשתמש מחובר לחשבון ולקרוא CreateAddOnAttachment מסוג courseWork, courseWorkMaterials או announcements על סמך הערך itemType. בתוך ה-iframe ניתן: מסך טעינה שיציין למורה שקובץ התוסף המצורף בתהליך יצירה.

לאחר יצירת הקובץ המצורף של התוסף, ה-iframe נסגר המורה יכול לצפות בקובץ המצורף במטלה כרגיל.

פרטי ההטמעה הטכנית

בקטע הזה נדגיש כמה פרטים טכניים חשובים לגבי התכונה.

קריאת הפרמטר של השאילתה urlToUpgrade

פרמטר השאילתה urlToUpgrade מקודד ב-URI כשהוא מועבר בקישור שדרוג iframe. עליך לפענח את כתובת ה-URL כדי לקבל אותה בצורתה המקורית. אם המיקום משתמשים ב-JavaScript. לדוגמה, אפשר להשתמש ב-decodeURIComponent() כדי לעשות את זה.

כדי להבטיח חוויית משתמש מיטבית לתכונה הזו, יש לשלוח postMessage פעם אחת הקובץ המצורף של התוסף נוצר בהצלחה. הפעולה הזו סוגרת את ה-iframe. צפייה לקבלת פרטים נוספים, ראו דף הפרטים של ההטמעה של iframe.

פרטי ההגדרות האישיות

ההגדרות הבאות נדרשות כדי לשלב את התכונה הזו :

  • כתובת ה-URL ל-iframe של השדרוג של הקישור: זו כתובת ה-URL שנפתחת ב iframe כשמורה מסכים לשדרג.

  • תבניות URL שמערכת Classroom צריכה לזהות ולנסות לזהות בהן Upgrade: תבניות ה-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 ותבניות ה-URL של ה-iframe של השדרוג של הקישור לבדיקה או לסביבת הייצור שולחים אימייל לכתובת 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 גם כדי לספק למורה הרשאות גישה לתוכן.