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

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

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

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

הגדרת iFrame URI

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

הגדרת iFrame URI

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

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

תגי ה-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 מסוג 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 של המקור https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456.
    1. המורה מבצע פעולות בתוך ה-iframe כדי לבחור קובץ להוספה.
  5. כשבוחרים קובץ מצורף, התוסף שולח postMessage ל-Classroom כדי לסגור את ה-iframe.

מסגרות iframe של 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% גובה חלון פחות 60 פיקסלים לכותרת העליונה
רוחב מקסימום 1600px
90% מרוחב החלון כשרוחב החלון הוא ‎600px לכל היותר
80% מרוחב החלון כשרוחב החלון הוא יותר מ-600px
  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.

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

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