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

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

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

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

הגדרת URI של iFrame

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

הגדרת URI של iFrame

קידומות URI מותרות משמשות לאימות מזהי ה-URI שהוגדרו ב-AddOnAttachment באמצעות השיטות *.addOnAttachments.create ו-*.addOnAttachments.patch. האימות הוא התאמת קידומת של מחרוזת מילולית, והוא לא מאפשר כרגע שימוש בתווים כלליים לחיפוש.

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

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

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

מזהה הקורס

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

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

מזהה הפוסט (הוצא משימוש)

הערך postId הוא מזהה של הפוסט (ההודעה, העבודה בקורס או חומרי העבודה בקורס) שאליו מצורף הקובץ.

כלולה בכל מסגרות ה-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 וב-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 להצגת קבצים מצורפים

המאפיין תיאור
חובה כן
URI סופק במטא-נתונים של התוסף
פרמטרים של שאילתות courseId, postId (הוצאה משימוש), 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.

מסגרות iframe שלTeacherViewUri ו-schoolViewUri

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

קובץ iframe של SchoolWorkReviewUri

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

המאפיין תיאור
חובה כן, אם התוסף תומך בשדרוג קישורים לקבצים מצורפים של תוספים.
URI סופק במטא-נתונים של התוסף
פרמטרים של שאילתות courseId, postId (הוצאה משימוש), 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&postId=234&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 Partner Name' מוסר כדי שהמשתמשים לא ייצרו כרטיסיות בצורה הזו בעתיד הקרוב.

הגבלות

כל רכיבי ה-iframe נפתחים באמצעות המאפיינים הבאים של 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 בהקשר של אינטראקציה ישירה (First-Party). חלק מהדפדפנים מעניקים גישה לקובצי cookie שנוצרו בהקשר של צד ראשון, בהקשר של צד שלישי.
  • צריך לבקש מהמשתמש לאשר קובצי cookie של צד שלישי. יכול להיות שלא תמיד זה אפשרי לכל המשתמשים.
  • עיצוב אפליקציות אינטרנט בדף יחיד שלא מסתמכות על קובצי cookie.

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

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

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

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

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

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

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

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