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

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

סקירה כללית

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

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

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

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

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

פרטים טכניים לגבי ההטמעה

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

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

פרמטר השאילתה urlToUpgrade מקודד ב-URI כשהוא מועבר ב-iframe של Link Upgrade. כדי לקבל את כתובת ה-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 גם כדי להעניק למורה את ההרשאות המתאימות לגישה לתוכן.