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

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

סקירה

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

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

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

ארבעת הפרמטרים הראשונים של השאילתה משקפים את הפרמטרים של השאילתה שהופעלו ב-Attachment Discovery iframe. פרמטר השאילתה urlToUpgrade חדש, והוא יכול לעזור לכם להעריך איך צריך ליצור את הקובץ המצורף של התוסף. לאחר מכן תוכלו להשתמש בפרמטרים האחרים של השאילתה כדי לבדוק אם המשתמש מחובר לחשבון ולקרוא ל-method 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 ואת תבניות ה-URL של ה-iframe של השדרוג של הקישור לגרסת הבדיקה או לתוסף הייצור, באימייל [e-mail].

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

הכללת הודעות שגיאה בנושא גישה ידידותית למשתמש

אם המורים מדביקים ומשדרגים קישור שאין להם גישה אליו, תוצג הודעת שגיאה ידידותית למשתמש ב-iframe, כדי שהמורים יהיו מודעים לבעיה. אפשר להשתמש ב-iframe גם כדי לתת למורה את ההרשאות המתאימות כדי לגשת לתוכן.