รายละเอียดของ iframe และพารามิเตอร์การค้นหา

ระบบจะโหลดส่วนเสริมของ Classroom ภายใน iframe เพื่อมอบประสบการณ์การใช้งานที่ราบรื่นและสะดวกสบายแก่ผู้ใช้ iframe มี 5 ประเภทที่แตกต่างกัน โปรดดูหน้า iframeในไดเรกทอรีเส้นทางของผู้ใช้เพื่อดู ภาพรวมของวัตถุประสงค์และลักษณะของ iframe แต่ละประเภท

ประเด็นสำคัญ: คุณจะได้รับข้อมูลที่หลากหลายเมื่อผู้ใช้เปิดมุมมองส่วนเสริมอย่างใดอย่างหนึ่ง ใช้ข้อมูลนี้เพื่อระบุไฟล์แนบ ตรวจสอบข้อมูลเข้าสู่ระบบและบทบาทของผู้ใช้ รวมถึงส่งคำขอ API บางอย่าง

หลักเกณฑ์ด้านความปลอดภัยของ iframe

นักพัฒนาแอปควรปฏิบัติตามแนวทางปฏิบัติแนะนำของอุตสาหกรรมเพื่อรักษาความปลอดภัยของ iframe อย่างไรก็ตาม คุณควรผสานรวมการโต้ตอบ API บางอย่างไว้ในโฟลว์ของผู้ใช้เพื่อยืนยันว่าคุณมีข้อมูลเข้าสู่ระบบที่ถูกต้องและสามารถระบุบทบาทของผู้ใช้ในหลักสูตรได้อย่างถูกต้อง

การกำหนดค่าแอปพลิเคชันเซิร์ฟเวอร์

เราขอแนะนำให้ใช้การกำหนดค่าเซิร์ฟเวอร์ต่อไปนี้เพื่อปกป้อง iframe

• ต้องใช้ HTTPS เราขอแนะนำอย่างยิ่งให้ใช้ TLS 1.2 ขึ้นไปและเปิดใช้ HTTP Strict Transport Security (HSTS) ดูบทความ MDN ที่เกี่ยวข้อง นี้เกี่ยวกับ Strict Transport Security
• เปิดใช้นโยบายรักษาความปลอดภัยเนื้อหา (CSP) แบบเข้มงวด ดูบทความ OWASP นี้ และบทความ MDN เกี่ยวกับนโยบายรักษาความปลอดภัยเนื้อหาที่เกี่ยวข้อง
• เปิดใช้แอตทริบิวต์ Secure ของคุกกี้ ดูแอตทริบิวต์ HttpOnly และ บทความ MDN เกี่ยวกับคุกกี้ที่เกี่ยวข้อง

พารามิเตอร์การค้นหา

iframe จะส่งข้อมูลสำคัญไปยังส่วนเสริมเป็นพารามิเตอร์การค้นหา พารามิเตอร์มี 2 หมวดหมู่ ได้แก่ พารามิเตอร์ที่เกี่ยวข้องกับไฟล์แนบและพารามิเตอร์ที่เกี่ยวข้องกับการลงชื่อเข้าใช้

พารามิเตอร์ที่เกี่ยวข้องกับไฟล์แนบ

พารามิเตอร์ที่เกี่ยวข้องกับไฟล์แนบจะให้ข้อมูลเกี่ยวกับหลักสูตร งาน ไฟล์แนบของส่วนเสริม งานที่นักเรียนส่ง และโทเค็นการให้สิทธิ์แก่ส่วนเสริม

รหัสหลักสูตร

ค่า courseId คือตัวระบุหลักสูตร

รวมอยู่ใน iframe ทั้งหมด

รหัสสินค้า

ค่า itemId คือตัวระบุ Announcement, CourseWork หรือ CourseWorkMaterial ที่แนบไฟล์แนบนี้

รวมอยู่ใน iframe ทั้งหมด

ประเภทรายการ

ค่า itemType จะระบุประเภททรัพยากรที่แนบไฟล์แนบนี้ ค่าสตริงที่ส่งคือค่าใดค่าหนึ่งต่อไปนี้ "announcements", "courseWork" หรือ "courseWorkMaterials"

รวมอยู่ใน iframe ทั้งหมด

รหัสของไฟล์แนบ

ค่า attachmentId คือตัวระบุไฟล์แนบ

รวมอยู่ใน iframe teacherViewUri, studentViewUri และ studentWorkReviewUri

รหัสการส่ง

ค่า submissionId คือตัวระบุงานของนักเรียน แต่ควรใช้ร่วมกับ attachmentId เพื่อระบุงานของนักเรียนในงานที่เฉพาะเจาะจง

รวมอยู่ใน studentWorkReviewUri

หมายเหตุ: คุณอาจใช้คีย์ผสมของ submissionId และ attachmentId เพื่อ ระบุงานของนักเรียนในกรณีที่มอบหมายไฟล์แนบเดียวกันให้กับนักเรียนคนเดียวกันในหลักสูตรต่างๆ ดูข้อมูลเพิ่มเติมได้ที่ เนื้อหาที่คัดลอก

โทเค็นของส่วนเสริม

ค่า addOnToken คือโทเค็นการให้สิทธิ์ที่ใช้เพื่อเรียก addOnAttachments.create เพื่อสร้างส่วนเสริม

รวมอยู่ใน iframe การค้นหาไฟล์แนบ และ iframe การอัปเกรดลิงก์

URL ที่จะอัปเกรด

การมีค่า urlToUpgrade หมายความว่าครูได้รวมไฟล์แนบลิงก์ไว้ในงานและตกลงที่จะอัปเกรดเป็นไฟล์แนบของส่วนเสริม หากยังไม่ได้กำหนดค่าฟีเจอร์นี้ โปรดดูรายละเอียดเพิ่มเติมในคู่มือเกี่ยวกับการอัปเกรดลิงก์เป็นไฟล์แนบของส่วนเสริม

รวมอยู่ใน iframe การอัปเกรดลิงก์

พารามิเตอร์ที่เกี่ยวข้องกับการลงชื่อเข้าใช้

พารามิเตอร์การค้นหา login_hint ให้ข้อมูลเกี่ยวกับผู้ใช้ Classroom ที่เข้าชมหน้าเว็บของส่วนเสริม พารามิเตอร์การค้นหานี้มีให้ใน URL src ของ iframe ระบบจะส่งพารามิเตอร์นี้เมื่อผู้ใช้เคยใช้ส่วนเสริมของคุณเพื่อช่วยลดความยุ่งยากในการลงชื่อเข้าใช้ของผู้ใช้ คุณต้องจัดการพารามิเตอร์การค้นหานี้ในการติดตั้งใช้งานส่วนเสริม

คำแนะนำในการเข้าสู่ระบบ

login_hint คือตัวระบุที่ไม่ซ้ำกันสำหรับบัญชี Google ของผู้ใช้ หลังจากที่ผู้ใช้เข้าสู่ระบบส่วนเสริมของคุณเป็นครั้งแรก ระบบจะส่งพารามิเตอร์ login_hint ในการเข้าชมส่วนเสริมของคุณครั้งต่อๆ ไปโดยผู้ใช้คนเดียวกัน

พารามิเตอร์ login_hint มีการใช้งานที่เป็นไปได้ 2 อย่าง ดังนี้

1. ส่งค่า login_hint ในระหว่างโฟลว์การตรวจสอบสิทธิ์เพื่อให้ผู้ใช้ไม่ต้องป้อนข้อมูลเข้าสู่ระบบเมื่อกล่องโต้ตอบการลงชื่อเข้าใช้ปรากฏขึ้น ระบบจะไม่ลงชื่อเข้าใช้ผู้ใช้โดยอัตโนมัติ
2. หลังจากที่ผู้ใช้ลงชื่อเข้าใช้แล้ว ให้ใช้พารามิเตอร์นี้เพื่อเปรียบเทียบค่ากับผู้ใช้ที่คุณอาจลงชื่อเข้าใช้ส่วนเสริมอยู่แล้ว หากพบรายการที่ตรงกัน คุณสามารถปล่อยให้ผู้ใช้ลงชื่อเข้าใช้ต่อไปและหลีกเลี่ยงการแสดงโฟลว์การลงชื่อเข้าใช้ หากพารามิเตอร์ไม่ตรงกับผู้ใช้ที่ลงชื่อเข้าใช้ ให้แจ้งให้ผู้ใช้ลงชื่อเข้าใช้ด้วยปุ่มลงชื่อเข้าใช้ที่มีแบรนด์ Google

รวมอยู่ใน iframe ทั้งหมด

หมายเหตุ: ดูข้อมูลเพิ่มเติมเกี่ยวกับการติดตั้งใช้งานพารามิเตอร์ login_hint และโฟลว์การลงชื่อเข้าใช้ได้ในหน้าคำแนะนำทีละขั้นตอนเกี่ยวกับ SSO, การลงชื่อเข้าใช้ที่ราบรื่น และ การจัดการการเข้าสู่ระบบซ้ำ

iframe การค้นหาไฟล์แนบ

มิติข้อมูล	คำอธิบาย
ต้องระบุ	ใช่
URI	ระบุไว้ในข้อมูลเมตาของส่วนเสริม
พารามิเตอร์การค้นหา	courseId, itemId, itemType, addOnToken และ login_hint
ส่วนสูง	ความสูงของหน้าต่าง 80% ลบ 60 พิกเซลสำหรับส่วนหัวด้านบน
ความกว้าง	สูงสุด 1,600 พิกเซล ความกว้างของหน้าต่าง 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` และ `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 พิกเซลเมื่อยุบ

หมายเหตุ: ครูสามารถเปิด iframe การตรวจงานของนักเรียนสำหรับนักเรียนที่ ยังไม่เคยดูไฟล์แนบของส่วนเสริม ในกรณีนี้ ส่วนเสริมอาจยังไม่รู้จักนักเรียนคนนี้และควรแสดงข้อความที่เหมาะสม

iframe การอัปเกรดลิงก์

มิติข้อมูล	คำอธิบาย
ต้องระบุ	ใช่ หากส่วนเสริมของคุณรองรับการอัปเกรดลิงก์เป็นไฟล์แนบของส่วนเสริมคือ รองรับโดยส่วนเสริมของคุณ
URI	ระบุไว้ในข้อมูลเมตาของส่วนเสริม
พารามิเตอร์การค้นหา	courseId, itemId, itemType, addOnToken, urlToUpgrade และ login_hint
ส่วนสูง	ความสูงของหน้าต่าง 80% ลบ 60 พิกเซลสำหรับส่วนหัวด้านบน
ความกว้าง	สูงสุด 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 เป็น to https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678

5. คุณประเมินพารามิเตอร์การค้นหาที่ส่งใน iframe และเรียกใช้ ปลายทาง CreateAddOnAttachment โปรดทราบว่าระบบจะเข้ารหัส URI พารามิเตอร์การค้นหา urlToUpgrade เมื่อส่งใน 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 ปิดท้าย หมายเหตุ: ระบบกำลังนำไฮเปอร์ลิงก์ "เปิดในชื่อพาร์ทเนอร์" ออก เพื่อไม่ให้ผู้ใช้สร้างแท็บด้วยวิธีนี้ในอนาคตอันใกล้นี้

ข้อจำกัด

ระบบจะเปิด iframe ทั้งหมดด้วยแอตทริบิวต์แซนด์บ็อกซ์ต่อไปนี้

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

และนโยบายฟีเจอร์ต่อไปนี้

• allow="microphone *"

การบล็อกคุกกี้ของบุคคลที่สาม

โปรดทราบว่าการบล็อกคุกกี้ของบุคคลที่สามทำให้การรักษาเซสชันที่ลงชื่อเข้าใช้ใน iframe เป็นเรื่องยาก โปรดดู https://www.cookiestatus.com เกี่ยวกับ สถานะปัจจุบันของการบล็อกคุกกี้ในเบราว์เซอร์ต่างๆ แน่นอนว่าปัญหานี้ไม่ได้เกิดขึ้นกับส่วนเสริมของ Google Classroom เท่านั้น แต่ยังส่งผลต่อเว็บไซต์ทั้งหมดที่ใช้ iframe ของบุคคลที่สาม พาร์ทเนอร์หลายรายของเราพบปัญหานี้แล้ว

วิธีแก้ปัญหาทั่วไปมีดังนี้

• เปิดแท็บใหม่เพื่อสร้างคุกกี้ในบริบทของบุคคลที่หนึ่ง เบราว์เซอร์บางประเภทจะให้สิทธิ์เข้าถึงคุกกี้ที่สร้างขึ้นในบริบทของบุคคลที่หนึ่งขณะอยู่ในบริบทของบุคคลที่สาม
• ขอให้ผู้ใช้อนุญาตคุกกี้ของบุคคลที่สาม ซึ่งอาจไม่สามารถทำได้กับผู้ใช้บางราย
• ออกแบบเว็บแอปพลิเคชันแบบหน้าเดียวที่ไม่ต้องใช้คุกกี้

เราคาดว่าจะมีการจำกัดคุกกี้เพิ่มเติมในเบราว์เซอร์เวอร์ชันต่อๆ ไป สร้าง คำขอฟีเจอร์เพื่อ ส่งความคิดเห็นถึง Google เกี่ยวกับวิธีลดภาระที่พาร์ทเนอร์ต้องรับผิดชอบ

เปิดใช้การค้นพบส่วนเสริมโดยใช้นิพจน์ทั่วไปของ URL

ครูมักจะสร้างงานที่มีไฟล์แนบลิงก์ หากต้องการส่งเสริมการใช้ส่วนเสริม คุณสามารถระบุนิพจน์ทั่วไปที่ตรงกับ URL ของทรัพยากรที่เข้าถึงได้ในส่วนเสริม ครูที่แนบลิงก์ที่ตรงกับนิพจน์ทั่วไปอย่างใดอย่างหนึ่งจะเห็นกล่องโต้ตอบที่ปิดได้ซึ่งกระตุ้นให้ลองใช้ส่วนเสริม กล่องโต้ตอบจะปรากฏขึ้นก็ต่อเมื่อมีการติดตั้งส่วนเสริมสำหรับบัญชีของครูแล้ว

หากต้องการให้ครูได้รับประสบการณ์การใช้งานนี้ โปรดระบุนิพจน์ทั่วไปที่เหมาะสมให้แก่ผู้ติดต่อ Google หากนิพจน์ทั่วไปที่คุณระบุครอบคลุมกว้างเกินไปหรือขัดแย้งกับส่วนเสริมอื่น ระบบอาจแก้ไขนิพจน์ทั่วไปให้มีความเฉพาะเจาะจงมากขึ้นหรือแตกต่างออกไป

รูปที่ 1 ครูเลือกไฟล์แนบลิงก์สำหรับงานใหม่

รูปที่ 2 ครูวางลิงก์จากแหล่งที่มาของบุคคลที่สาม ครูได้ติดตั้งส่วนเสริมของ Classroom ของบุคคลที่สามแล้ว

รูปที่ 3 กล่องโต้ตอบแบบโต้ตอบที่แสดงต่อครูเมื่อลิงก์ที่วางตรงกับนิพจน์ทั่วไปที่นักพัฒนาแอปของบุคคลที่สามระบุ

หากครูเลือก "ลองเลย" ในป๊อปอัปตามที่แสดงในรูปที่ 3 ระบบจะเปลี่ยนเส้นทางครูไปยัง iframe การค้นหาไฟล์แนบของส่วนเสริม