פרטים לגבי iframe ופרמטרים של שאילתה

תוספים ל-Classroom נטענים בתוך iframe כדי לספק למשתמש הקצה חוויית משתמש חלקה ונוחה. יש חמישה סוגים שונים של iframe. אפשר לעיין בדפי ה-iframe בספרייה User journeys (מסלולי משתמשים) כדי לקבל סקירה כללית על המטרה והמראה של כל iframe.

הנחיות אבטחה ל-iframe

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

הגדרת אפליקציית השרת

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

• חובה להשתמש ב-HTTPS. מומלץ מאוד להשתמש ב-TLS 1.2 ומעלה ולהפעיל HTTP Strict Transport Security‏ (HSTS). מידע נוסף על Strict Transport Security זמין במאמר MDN בנושא.
• מפעילים את התכונה Strict Content Security Policy (מדיניות אבטחת תוכן מחמירה, Strict CSP). אפשר לעיין במאמר הזה של OWASP ובמאמר הזה של MDN בנושא Content Security Policy.
• מפעילים את מאפיין קובץ ה-Cookie המאובטח. אפשר לעיין במאפיין HttpOnly ובמאמר הזה בנושא קובצי Cookie ב-MDN.

פרמטרים של שאילתה

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

פרמטרים שקשורים לקבצים מצורפים

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

מזהה הקורס

הערך של courseId הוא מזהה של הקורס.

כלול בכל ה-iframe.

מזהה פריט

הערך של itemId הוא מזהה של Announcement,‏ CourseWork או CourseWorkMaterial שאליהם מצורף הקובץ המצורף.

כלול בכל ה-iframe.

סוג פריט

הערך itemType מזהה את סוג המשאב שאליו מצורף הקובץ המצורף. ערך המחרוזת שהועבר הוא אחד מהערכים "announcements",‏ "courseWork" או "courseWorkMaterials".

כלול בכל ה-iframe.

מזהה הקובץ המצורף

הערך attachmentId הוא מזהה של הקובץ המצורף.

כלול במסגרות iframe של teacherViewUri, ‏ studentViewUri ו-studentWorkReviewUri.

מזהה הגשה

הערך של submissionId הוא מזהה של העבודה של התלמיד או התלמידה, אבל צריך להשתמש בו בשילוב עם attachmentId כדי לזהות את העבודה של התלמיד או התלמידה במטלה מסוימת.

כלול ב-studentWorkReviewUri.

טוקן של תוסף

הערך addOnToken הוא טוקן הרשאה שמשמש לביצוע קריאות של addOnAttachments.create כדי ליצור את התוסף.

נכלל ב-Attachment Discovery iframe וב-Link Upgrade iframe.

כתובת URL לשדרוג

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

כלול ב-iframe של שדרוג הקישור.

פרמטרים שקשורים לכניסה

פרמטר השאילתה login_hint מספק מידע על משתמש Classroom שנכנס לדף האינטרנט של התוסף. פרמטר השאילתה הזה מופיע בכתובת ה-URL של ה-iframe‏ src. הוא נשלח אם המשתמש השתמש בעבר בתוסף שלכם, כדי לצמצם את החיכוך בתהליך הכניסה של משתמשי הקצה. אתם נדרשים לטפל בפרמטר השאילתה הזה בהטמעה של התוסף.

רמז לכניסה

‫login_hint הוא מזהה ייחודי של חשבון Google של המשתמש. אחרי שהמשתמש מתחבר לתוסף בפעם הראשונה, הפרמטר login_hint מועבר בכל ביקור הבא של אותו משתמש בתוסף.

יש שני שימושים אפשריים לפרמטר login_hint:

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

כלול בכל ה-iframe.

‫iframe של איתור קבצים מצורפים

תרחיש לדוגמה של גילוי קבצים מצורפים

1. תוסף ל-Classroom רשום ב-Google Workspace Marketplace עם URI של גילוי קבצים מצורפים https://example.com/addon.
2. מורה מתקין את התוסף הזה ויוצר הודעה חדשה, מטלה או חומר לימוד באחד מהקורסים שלו. לדוגמה, itemId=234, itemType=courseWork ו-courseId=123.
3. במהלך הגדרת הפריט, המורה בוחר את התוסף החדש שהותקן כקובץ מצורף.
4. ‫Classroom יוצר iframe עם כתובת ה-URL של המקור שמוגדרת ל-https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456.
   1. איש/אשת ההוראה מבצע/ת פעולה ב-iframe כדי לבחור קובץ מצורף.
5. כשבוחרים קובץ מצורף, התוסף שולח postMessage ל-Classroom כדי לסגור את ה-iframe.

‫iframes של teacherViewUri ו-studentViewUri

‫iframe של studentWorkReviewUri

שדרוג הקישור ב-iframe

תרחיש לדוגמה לשדרוג קישור

1. תוסף ל-Classroom רשום עם URI לשדרוג קישור של https://example.com/upgrade. סיפקת את התבניות הבאות של קידומות של מארח ונתיב עבור קבצים מצורפים מסוג קישור ש-Classroom צריך לנסות לשדרג לקבצים מצורפים של תוספים:
   • המארח הוא example.com ותחילית הנתיב היא /quiz.
2. מורה יוצר הודעה, מטלה או חומר לימוד חדשים באחד מהקורסים שלו. לדוגמה, itemId=234, ‏ itemType=courseWork ו-courseId=123.
3. מורה מדביק קישור, https://example.com/quiz/5678, בתיבת הדו-שיח 'צירוף קישור' שתואם לתבנית כתובת URL שסיפקתם. לאחר מכן, המורה מקבל הנחיה לשדרג את הקישור לקובץ מצורף של תוסף.

4. מערכת Classroom מפעילה את ה-iframe של שדרוג הקישור עם כתובת ה-URL שמוגדרת ל-https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678.

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

6. אם יצירת הקובץ המצורף של התוסף מקישור מצליחה, שולחים 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. הערה: אנחנו מתכוונים להסיר את ההיפר-קישור 'פתיחה בשם השותף' כדי שמשתמשים לא יוכלו ליצור כרטיסיות בדרך הזו בעתיד הקרוב.

הגבלות

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

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