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

จัดทุกอย่างให้เป็นระเบียบอยู่เสมอด้วยคอลเล็กชัน บันทึกและจัดหมวดหมู่เนื้อหาตามค่ากำหนดของคุณ

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

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

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

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

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

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

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

ซึ่งจะส่งข้อมูลสำคัญไปยังส่วนเสริมเป็นพารามิเตอร์การค้นหา พารามิเตอร์มี 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 ของ Discovery ไฟล์แนบ 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 เป็น https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fptop.only.wip.la%3A443%2Fhttps%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 โปรดทราบว่าเราจะนำไฮเปอร์ลิงก์ "เปิดในชื่อพาร์ทเนอร์" ออกเพื่อไม่ให้ผู้ใช้สร้างแท็บด้วยวิธีนี้อีกในอนาคตอันใกล้

ข้อจำกัด

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