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

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

หลักเกณฑ์ด้านความปลอดภัยของ 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

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

ค่า 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 ทั้งหมด

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

สถานการณ์ตัวอย่างของการค้นหาไฟล์แนบ

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`

iframe `studentWorkReviewUri`

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

สถานการณ์ตัวอย่างของการอัปเกรดลิงก์

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 การค้นหาไฟล์แนบของส่วนเสริม