התוספים ל-Classroom נטענים ב-iframe כדי לספק למשתמשי הקצה חוויית משתמש נוחה וחלקה. יש ארבעה סוגים נפרדים של iframe. כדי לקבל סקירה כללית על המטרה והמראה של כל iframe, מומלץ לעיין בדפי iframes בספרייה 'תהליכים שעוברים המשתמשים'.
הנחיות אבטחה ב-iframe
אנחנו מצפים משותפים לפעול לפי השיטות המומלצות בתחום כדי לאבטח את ה-iframe שלהם. כדי להגן על ה-iframe, צוות האבטחה שלנו ממליץ על הדברים הבאים:
חובה להשתמש ב-HTTPS. אנחנו ממליצים מאוד להשתמש ב-TLS 1.2 ואילך ולהפעיל את HTTP Strict Transport Security. כדאי לקרוא את המאמר בנושא MDN בנושא אבטחה מחמירה של תעבורה.
מפעילים את האפשרות Strict Content Security Policy. אפשר לעיין במאמר הזה בנושא OWASP ובמאמר שקשור ל-MDN בנושא מדיניות Content Security.
מפעילים את המאפיין Secure cookie. אפשר לעיין במאפיין HttpOnly ובמאמר בנושא MDN שקשור לקובצי Cookie.
הגדרת iFrame URI
ה-URI של הגדרת הקובץ המצורף הוא הרכיב ה-iframe של Discovery של קבצים מצורפים שנטען, וזהו המקום שבו המורים מתחילים את התהליך של יצירת קבצים מצורפים לתוספים בפוסט ב-Classroom. אפשר להגדיר אותו במסוף הפרויקט ב-Google Cloud. מגדירים את ה-URI הזה ב-API & Service של הפרויקט ב-Google Cloud > Google Workspace Marketplace SDK > הדף App Configuration (הגדרת האפליקציה).
הקידומות המותרות של URI של קבצים מצורפים לאימות של מזהי ה-URI שהוגדרו ב-AddOnAttachment באמצעות ה-methods *.addOnAttachments.create
ו-*.addOnAttachments.patch
. האימות הוא התאמה מילולית לתחילית של מחרוזת, ולכן הוא לא מאפשר כרגע להשתמש בתווים כלליים לחיפוש.
פרמטרים של שאילתה
רכיבי ה-iframe מעבירים מידע קריטי לתוסף כפרמטרים של שאילתה. יש שתי קטגוריות של פרמטרים: פרמטרים שקשורים לקבצים מצורפים ופרמטרים שקשורים לכניסה.
פרמטרים שקשורים לקבצים מצורפים
הפרמטרים שקשורים לקבצים מצורפים מספקים לתוסף מידע על הקורס, המטלה, הקובץ המצורף של התוסף, הקובץ שהתלמיד או התלמידה הגישו ואסימון מאשר.
- מזהה הקורס
הערך
courseId
הוא מזהה של הקורס.כלולה בכל מסגרות ה-iframe.
- מזהה פריט
הערך
itemId
הוא מזהה שלAnnouncement
,CourseWork
אוCourseWorkMaterial
שאליו מצורף הקובץ המצורף.כלולה בכל מסגרות ה-iframe.
- סוג פריט
הערך
itemType
מזהה את סוג המשאב שבומצורף קובץ. ערך המחרוזת שמועברת הוא
"announcements"
,"courseWork"
או"courseWorkMaterials"
.כלולה בכל מסגרות ה-iframe.
- מזהה הקובץ המצורף
הערך
attachmentId
הוא מזהה של הקובץ המצורף.כלולה ב-iframes
teacherViewUri
,studentViewUri
ו-studentWorkReviewUri
.- מזהה שליחה
הערך
submissionId
הוא מזהה לעבודה של התלמיד/ה, אבל צריך להשתמש בו בשילוב עם המאפייןattachmentId
כדי לזהות את העבודות של התלמיד/ה במטלה מסוימת.כלול ב-
studentWorkReviewUri
.
- אסימון של תוסף
הערך
addOnToken
הוא אסימון הרשאה שמשמש לביצועצריך
addOnAttachments.create
שיחות כדי ליצור את התוסף.כלול ב-Attachment Discovery iframe וב-iframe של שדרוג הקישור.
- כתובת URL לשדרוג
נוכחות הערך
urlToUpgrade
מרמזת על כךהמורה כלל/ה קובץ מצורף של קישור במטלה, והסכים לשדרג אותו לקובץ מצורף של תוסף. אם עדיין לא הגדרתם את התכונה הזו, תוכלו לקרוא את המדריך בנושא שדרוג קישורים לקבצים מצורפים של תוספים.
כלולה ב-iframe של השדרוג של הקישור.
פרמטרים שקשורים לכניסה
פרמטר השאילתה login_hint
מספק מידע על
משתמש ב-Classroom שנכנס לדף האינטרנט של התוסף. פרמטר השאילתה הזה נמצא בכתובת ה-URL src
של ה-iframe. ההודעה נשלחת כשהמשתמש השתמש בעבר בתוסף, כדי להקל על משתמשי הקצה בכניסה לחשבון. אתם צריכים לטפל בפרמטר השאילתה הזה בהטמעה של התוסף.
- רמז להתחברות
login_hint
הוא מזהה ייחודי של חשבון Google של המשתמשחשבון. אחרי שהמשתמש מתחבר לתוסף בפעם הראשונה, הפרמטר
login_hint
מועבר בכל כניסה של אותו משתמש לתוסף.יש שני שימושים אפשריים לפרמטר
login_hint
:- מעבירים את הערך של
login_hint
במהלך תהליך האימות, כדי שהמשתמשים לא יצטרכו להזין את פרטי הכניסה כשמופיעה תיבת הדו-שיח לכניסה. המשתמש לא נכנס לחשבון באופן אוטומטי. - אחרי שהמשתמש נכנס לחשבון, אפשר להשתמש בפרמטר הזה כדי להשוות את הערך למשתמשים שאולי כבר מחוברים לחשבון לתוסף. אם מוצאים התאמה, אפשר להשאיר את המשתמש מחובר ולא להציג את תהליך הכניסה. אם הפרמטר לא תואם לאף אחד מהמשתמשים שמחוברים לחשבון, מבקשים מהמשתמש להיכנס באמצעות לחצן כניסה עם מיתוג של Google.
כלולה בכל מסגרות ה-iframe.
- מעבירים את הערך של
קובץ iframe מסוג Discovery של קבצים מצורפים
המאפיין | תיאור |
---|---|
נדרש | כן |
URI | סופקו במטא-נתונים של התוסף |
פרמטרים של שאילתה | courseId , itemId , itemType , addOnToken וגם login_hint . |
גובה | 80% גובה חלון פחות 60 פיקסלים לכותרת העליונה |
רוחב | עד 1600 פיקסלים 90% רוחב חלון כאשר חלון <= 600 פיקסלים רחב 80% רוחב חלון כאשר חלון גדול מ-600 פיקסלים |
תרחיש לדוגמה של גילוי קבצים מצורפים
- תוסף של Classroom רשום ב-Google Workspace
Marketplace עם מזהה URI של קבצים מצורפים מסוג
https://example.com/addon
. - מורים מתקינים את התוסף הזה ויוצרים הודעה, מטלה או חומר לימוד חדשים באחד מהקורסים שלו. לדוגמה,
itemId=234
,itemType=courseWork
ו-courseId=123
. - כשמגדירים את הפריט, המורה בוחר/ת את התוסף החדש שהותקן כקובץ מצורף.
- מערכת Classroom יוצרת iframe שבו כתובת ה-URL של src מוגדרת
https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456
.- המורה מבצע עבודה בתוך ה-iframe כדי לבחור קובץ מצורף.
- בבחירת קובץ מצורף, התוסף שולח
postMessage
ל-Classroom כדי לסגור את ה-iframe.
iframes של merchantViewUri ו-תלמידיםViewUri
המאפיין | תיאור |
---|---|
נדרש | כן |
URI | teacherViewUri או studentViewUri |
פרמטרים של שאילתה | courseId , itemId , itemType , attachmentId וגם login_hint . |
גובה | 100% גובה חלון פחות 140 פיקסלים לכותרת העליונה |
רוחב | 100% רוחב חלון |
iframe WorkReviewUri
המאפיין | תיאור |
---|---|
נדרש | לא (קובע אם זהו קובץ מצורף מסוג פעילות) |
URI | studentWorkReviewUri |
פרמטרים של שאילתה | courseId , itemId , itemType , attachmentId , submissionId ו-login_hint . |
גובה | 100% גובה חלון פחות 168 פיקסלים לכותרת העליונה |
רוחב | 100% רוחב חלון פחות רוחב סרגל הצד<> סרגל הצד הוא 312 פיקסלים כשהוא מורחב ו-56 פיקסלים במצב מכווץ |
iframe של שדרוג קישור
המאפיין | תיאור |
---|---|
נדרש | כן, אם התוסף תומך בשדרוג קישורים לקבצים מצורפים. |
URI | סופקו במטא-נתונים של התוסף |
פרמטרים של שאילתה | courseId , itemId , itemType , addOnToken , urlToUpgrade ו-login_hint . |
גובה | 80% גובה חלון פחות 60 פיקסלים לכותרת העליונה |
רוחב | עד 1600 פיקסלים 90% רוחב חלון כאשר חלון <= 600 פיקסלים רחב 80% רוחב חלון כאשר חלון גדול מ-600 פיקסלים |
תרחיש לדוגמה של שדרוג קישורים
- תוסף של Classroom רשום עם ה-URI לשדרוג לקישור של
https://example.com/upgrade
. סיפקתם את הדפוסים הבאים של קידומת מארח ונתיב לקבצים מצורפים לקישורים שמערכת Classroom צריכה לנסות לשדרג לקובץ מצורף של תוסף:- המארח הוא
example.com
והקידומת של הנתיב היא/quiz
.
- המארח הוא
- המורים יוצרים הודעה חדשה, מטלה או חומר לימוד חדשים באחד מהקורסים שלהם. לדוגמה,
itemId=234
,itemType=courseWork
ו-courseId=123
. - המורה מדביק את הקישור
https://example.com/quiz/5678
בתיבת הדו-שיח של הקובץ המצורף, שתואם לדפוס כתובת ה-URL שסיפקתם. המורים יתבקשו לשדרג את הקישור לקובץ מצורף של תוסף. Classroom משיק את ה-iframe של שדרוג הקישור כאשר כתובת ה-URL מוגדרת ל-
https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678
.אתם מעריכים את הפרמטרים של השאילתה שמועברים ב-iframe ומבצעים קריאה לנקודת הקצה
CreateAddOnAttachment
. שימו לב שפרמטר השאילתהurlToUpgrade
מקודד ב-URI כשמעבירים אותו ב-iframe. צריך לפענח את הפרמטר כדי לקבל אותו בצורתו המקורית. לדוגמה, JavaScript מציע את הפונקציהdecodeURIComponent()
.אם קובץ מצורף של תוסף מקישור ייווצר בהצלחה, תוכלו לשלוח
postMessage
ל-Classroom כדי לסגור את ה-iframe.
סגירת ה-iframe
כדי לסגור את ה-iframe מכלי הלמידה, שולחים postMessage
עם המטען הייעודי (Payload) {type: 'Classroom', action: 'closeIframe'}
.
המערכת של Classroom מקבלת את ה-postMessage
הזה רק מה-host_name+port בהתאם ל-URI המקורי שנפתח.
<button id="close">Send message to close iframe</button>
<script>
document.querySelector('#close')
.addEventListener('click', () => {
window.parent.postMessage({
type: 'Classroom',
action: 'closeIframe',
}, '*');
});
</script>
סגירת iframe מה-iframe
ביציאת הדומיין+ של הדף ששולח את האירוע postMessage
, צריכה להיות אותה
יציאת דומיין כמו זו של ה-URI המשמש להפעלת ה-iframe, אחרת המערכת תתעלם מההודעה. הדרך לעקוף את הבעיה היא להפנות חזרה לדף בדומיין המקורי שלא מבצע יותר משליחת האירוע postMessage
.
סגירת iframe מכרטיסייה חדשה
אמצעי הגנה על כמה דומיינים מונעים מההגנה הזו לפעול. הדרך לעקוף את הבעיה היא לטפל בעצמכם בתקשורת בין ה-iframe לבין הכרטיסייה החדשה, ולאפשר ל-iframe בסופו של דבר להיות אחראי להנפקת אירוע הסגירה postMessage
. לידיעתך, אנחנו מסירים את ההיפר-קישור 'Open in Name' כדי שהמשתמשים לא ייצרו כרטיסיות בצורה הזו בעתיד הקרוב.
הגבלות
כל מסגרות ה-iframe נפתחות באמצעות המאפיינים הבאים של ארגז חול:
allow-popups
allow-popups-to-escape-sandbox
allow-forms
allow-scripts
allow-storage-access-by-user-activation
allow-same-origin
והמדיניות הבאה בנושא תכונות
allow="microphone *"
חסימת קובצי cookie של צד שלישי
שימו לב שחסימת קובצי cookie של צד שלישי מקשה על ניהול סשן מחובר ב-iframe. בכתובת https://www.cookiestatus.com מופיע המצב הנוכחי של חסימת קובצי cookie בדפדפנים שונים. כמובן, הבעיה הזו לא ייחודית לתוספים ל-Google Classroom, ומשפיעה על כל האתרים של צדדים שלישיים ב-iframe. רבים מהשותפים שלנו כבר נתקלו בבעיה הזו.
כמה פתרונות כלליים הם:
- פותחים כרטיסייה חדשה כדי ליצור את קובץ ה-cookie בהקשר של צד ראשון. דפדפנים מסוימים מעניקים גישה לקובצי Cookie שנוצרו בהקשר של צד ראשון בהקשר של צד שלישי.
- לבקש מהמשתמש לאפשר קובצי cookie של צד שלישי. יכול להיות שלא תמיד יהיה זה אפשרי אצל כל המשתמשים.
- מעצבים אפליקציות אינטרנט עם דף יחיד שלא מסתמכות על קובצי Cookie.
גרסאות עתידיות של הדפדפן צפויות הגבלות נוספות על קובצי cookie. אפשר ליצור בקשות לתכונות כדי לשלוח ל-Google משוב על דרכים לצמצום העלייה שנדרשת על ידי השותפים.
הפעלת יכולת גילוי של תוספים באמצעות ביטויים רגולריים של כתובות URL
מורים יוצרים לעיתים קרובות מטלות שמצורפים אליהן קישורים. כדי לקדם את השימוש בתוסף, תוכלו לציין ביטויים רגולריים שתואמים לכתובות URL של משאבים שאפשר לגשת אליהם בתוסף. כשמצרפים מורה כשמצרפים קישור שתואם לאחד מהביטויים הרגולריים, נפתחת תיבת דו-שיח שאפשר לסגור, שבה הם מתבקשים לנסות את התוסף. הם יראו את תיבת הדו-שיח רק אם התוסף כבר מותקן בחשבון שלהם.
אם אתם רוצים לספק את ההתנהגות הזו למורים, עליכם לספק לאנשי הקשר שלכם ב-Google את הביטויים הרגולריים המתאימים. אם הביטויים הרגולריים שסיפקתם רחבים מדי או מתנגשים עם תוסף אחר, יכול להיות שהם ישונו כך שיהיו מוגבלים או ייחודיים יותר.
איור 1. המורה בוחר/ת קובץ מצורף עם קישור למטלה חדשה.
איור 2. והמורים מדביקים קישור ממקור של צד שלישי. המורה כבר התקין את תוסף Classroom של הצד השלישי.
איור 3. תיבת הדו-שיח האינטראקטיבית שמוצגת למורה כשהקישור שהודבק תואם לביטוי רגולרי שצוין על ידי המפתח של הצד השלישי.
אם מורה יבחר/ה באפשרות "Try it now" בחלון הקופץ, כפי שמוצג בתרשים מספר 3, הם יופנו אוטומטית ל-Attachment Discovery iframe של התוסף.