שדרוג קובצי הקישור שצורפו לקבצים מצורפים ב-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().

סגירה של ה-iframe של שדרוג הקישור

כדי להבטיח חוויית משתמש מיטבית בתכונה הזו, צריך לשלוח 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 של התוסף לבדיקה או לייצור, באימייל לכתובת [e-mail].

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

תקבלו תשובה באימייל כשההגדרות יופעלו. חשוב לזכור שלא ניתן להשתמש בתבניות של כתובות URL שמכילות את התו localhost בתכונה הזו.

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

צריך לעצב את האימייל כך שיכלול את הפרטים הבאים:

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