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

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

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

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

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

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

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

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

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

מזהה הקורס

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

כלול בכל תגי iframe.

מזהה פריט

הערך itemId הוא מזהה של Announcement,

CourseWork או CourseWorkMaterial, שבהם הקובץ המצורף מופיע.

כלול בכל תגי iframe.

סוג פריט

הערך של itemType מזהה את סוג המשאב שבו

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

כלול בכל תגי iframe.

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

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

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

מזהה הגשה

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

כלול ב-studentWorkReviewUri.

טוקן של תוסף

הערך addOnToken הוא טוקן הרשאה שמשמש ליצירת

addOnAttachments.create כדי ליצור את התוסף.

כלול ב-iframe של גילוי הקבצים המצורפים וב-iframe של שדרוג הקישור.

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

נוכחות הערך urlToUpgrade מצביעה על כך שה-

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

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

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

רמז להתחברות

השדה login_hint הוא מזהה ייחודי של חשבון Google של המשתמש

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

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

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

כלול בכל תגי iframe.

iframe של Attachment Discovery

מאפיין תיאור
חובה כן
URI מופיעים במטא-נתונים של התוסף
פרמטרים של שאילתות courseId, itemId, itemType, addOnToken וגם login_hint.
גובה 80% מגובה החלון פחות 60px לכותרת העליונה
רוחב מקסימום 1,600 פיקסלים
90% רוחב החלון כשהחלון ברוחב 600 פיקסלים לכל היותר
80% רוחב החלון כשהחלון ברוחב של יותר מ-600 פיקסלים

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

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

iframes של teacherViewUri ו-studentViewUri

מאפיין תיאור
חובה כן
URI teacherViewUri או studentViewUri
פרמטרים של שאילתות courseId, itemId, itemType, attachmentId וגם login_hint.
גובה 100% מגובה החלון פחות 140 פיקסלים לכותרת העליונה
רוחב רוחב חלון של 100%

iframe של studentWorkReviewUri

מאפיין תיאור
חובה לא (הערך הזה קובע אם הקובץ המצורף הוא מסוג פעילות)
URI studentWorkReviewUri
פרמטרים של שאילתות courseId,‏ itemId,‏ itemType,‏ attachmentId,‏ submissionId וגם login_hint.
גובה 100% מגובה החלון פחות 168 פיקסלים לכותרת העליונה
רוחב 100% רוחב החלון בניכוי רוחב סרגל הצד<> סרגל הצד הוא 312 פיקסלים כשמורחב ו-56 פיקסלים כשמצומצם

מאפיין תיאור
חובה כן, אם התוסף תומך בשדרוג קישורים לקבצים מצורפים של תוספים.
URI מופיעים במטא-נתונים של התוסף
פרמטרים של שאילתות courseId,‏ itemId,‏ itemType,‏ addOnToken,‏ urlToUpgrade וגם login_hint.
גובה 80% מגובה החלון פחות 60px לכותרת העליונה
רוחב מקסימום 1,600 פיקסלים
90% רוחב החלון כשהחלון ברוחב 600 פיקסלים לכל היותר
80% רוחב החלון כשהחלון ברוחב של יותר מ-600 פיקסלים
  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 עם עומס העבודה {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 לסגירה. רצינו גם לציין שהקישור ההיפר 'פתיחה ב-Partner Name' יוסר כדי שמשתמשים לא יצרו כרטיסיות בדרך הזו בעתיד הקרוב.

הגבלות

כל ה-iframes נפתחים עם מאפייני sandbox הבאים:

  • allow-popups
  • allow-popups-to-escape-sandbox
  • allow-forms
  • allow-scripts
  • allow-storage-access-by-user-activation
  • allow-same-origin

ועל מדיניות התכונות הבאה

  • allow="microphone *"

חשוב לזכור שחסימת קובצי 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 של Attachment Discovery של התוסף.