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