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

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

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