אחת הדרכים שבהן מורים מוסיפים תוכן של צד שלישי ל-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 של השדרוג של הקישור לגרסת הבדיקה או לתוסף הייצור, באימייל classroom-link-upgrade-external@google.com.
קודם אתם יכולים לספק הגדרות לתוסף הפרטי שלכם ולכל סביבת בדיקה או פיתוח שבבעלותכם. צוות 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 של Link Upgrade כדי לאסוף את המידע הנוסף הדרוש. אפשר גם להשתמש ב-iframe כדי ליידע את המורה אם אי אפשר לשדרג את הקישור או אם אירעה שגיאה.
הכללת הודעות שגיאה בנושא גישה ידידותית למשתמש
אם המורים מדביקים ומשדרגים קישור שאין להם גישה אליו, תוצג הודעת שגיאה ידידותית למשתמש ב-iframe, כדי שהמורים יהיו מודעים לבעיה. אפשר להשתמש ב-iframe גם כדי לתת למורה את ההרשאות המתאימות כדי לגשת לתוכן.