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

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

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

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

הגדרת iFrame URI

ה-URI של הגדרת הקובץ המצורף הוא הרכיב ה-iframe של Discovery של קבצים מצורפים שנטען, וזהו המקום שבו המורים מתחילים את התהליך של יצירת קבצים מצורפים לתוספים בפוסט ב-Classroom. אפשר להגדיר אותו במסוף הפרויקט ב-Google Cloud. מגדירים את ה-URI הזה ב-API & Service של הפרויקט ב-Google Cloud > Google Workspace Marketplace SDK > הדף App Configuration (הגדרת האפליקציה).

הגדרת iFrame URI

הקידומות המותרות של 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:

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

כלולה בכל מסגרות ה-iframe.

קובץ iframe מסוג Discovery של קבצים מצורפים

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

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

  1. תוסף של Classroom רשום ב-Google Workspace Marketplace עם מזהה 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 של 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 פיקסלים במצב מכווץ

המאפיין תיאור
נדרש כן, אם התוסף תומך בשדרוג קישורים לקבצים מצורפים.
URI סופקו במטא-נתונים של התוסף
פרמטרים של שאילתה courseId, itemId, itemType, addOnToken, urlToUpgrade ו-login_hint.
גובה 80% גובה חלון פחות 60 פיקסלים לכותרת העליונה
רוחב עד 1600 פיקסלים
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 עם המטען הייעודי (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 של צד שלישי מקשה על ניהול סשן מחובר ב-iframe. בכתובת https://www.cookiestatus.com מופיע המצב הנוכחי של חסימת קובצי cookie בדפדפנים שונים. כמובן, הבעיה הזו לא ייחודית לתוספים ל-Google Classroom, ומשפיעה על כל האתרים של צדדים שלישיים ב-iframe. רבים מהשותפים שלנו כבר נתקלו בבעיה הזו.

כמה פתרונות כלליים הם:

  • פותחים כרטיסייה חדשה כדי ליצור את קובץ ה-cookie בהקשר של צד ראשון. דפדפנים מסוימים מעניקים גישה לקובצי Cookie שנוצרו בהקשר של צד ראשון בהקשר של צד שלישי.
  • לבקש מהמשתמש לאפשר קובצי cookie של צד שלישי. יכול להיות שלא תמיד יהיה זה אפשרי אצל כל המשתמשים.
  • מעצבים אפליקציות אינטרנט עם דף יחיד שלא מסתמכות על קובצי Cookie.

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

הפעלת יכולת גילוי של תוספים באמצעות ביטויים רגולריים של כתובות URL

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

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

מורה בוחר קובץ מצורף לקישור איור 1. המורה בוחר/ת קובץ מצורף עם קישור למטלה חדשה.

קישור להדבקה של מורה איור 2. והמורים מדביקים קישור ממקור של צד שלישי. המורה כבר התקין את תוסף Classroom של הצד השלישי.

תיבת דו-שיח של יכולת הגילוי של ביטוי רגולרי (regex) איור 3. תיבת הדו-שיח האינטראקטיבית שמוצגת למורה כשהקישור שהודבק תואם לביטוי רגולרי שצוין על ידי המפתח של הצד השלישי.

אם מורה יבחר/ה באפשרות "Try it now" בחלון הקופץ, כפי שמוצג בתרשים מספר 3, הם יופנו אוטומטית ל-Attachment Discovery iframe של התוסף.