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

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

סקירה כללית

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

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

  • courseId
  • itemId (השם שונה מ-postId)
  • itemType (חדש!)
  • addOnToken
  • login_hint או hd
  • urlToUpgrade (חדש!)

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

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

פרטי היישום הטכני

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

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

פרמטר השאילתה urlToUpgrade מקודד ב-URI כשהוא מועבר ב-Link Upgrade iframe. כדי לקבל אותה בצורתה המקורית, צריך לפענח את כתובת ה-URL. לדוגמה, אם אתם משתמשים ב-JavaScript, תוכלו להשתמש בפונקציה decodeURIComponent() כדי לעשות זאת.

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

פרטי ההגדרות האישיות

כדי לשלב את התכונה הזו בתוסף, צריך לקבוע את ההגדרות הבאות:

  • כתובת URL של ה-iframe לשדרוג הקישור: כתובת ה-URL שנפתחת ב-iframe כשהמורה מאשר/ת את השדרוג.

  • דפוסי כתובות URL שמערכת Classroom צריכה לזהות ולנסות לשדרג: תבניות ה-URL יכולות להכיל מארח ומספר קידומות של נתיבים.

    • ניתן לספק מספר תבניות של כתובות URL.
    • אם לא מספקים קידומות של נתיבים, אפשר לשדרג כל כתובת URL שתואמת למארח.
    • אפשר לשדרג רק כתובות URL עם הסכמה https.
    • תבניות URL לא יכולות להכיל localhost.
    • תחיליות של נתיבים אינן יכולות להכיל פרמטרים של שאילתה או קטעים של כתובת אתר.
    • בשלב הזה, תחיליות של נתיבים יכולות לתמוך בתווים כלליים לחיפוש, אבל המארחים לא יכולים:
      • 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 היא התאמה חוקית לדפוס כתובת האתר.
      • https://example.com/bar/123/456/baz אינה התאמה חוקית לדפוס כתובת ה-URL כי התו הכללי לחיפוש בקידומת הנתיב לא תואם ל-/123/456/.

תהליך פיתוח

שולחים אימייל לכתובת classroom-link-upgrade-external@google.com של ה-URL ותבניות ה-URL של השדרוג לבדיקה או לסביבת הייצור.

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