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

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

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

พาร์ทเนอร์ควรปฏิบัติตามแนวทางปฏิบัติแนะนำของอุตสาหกรรมเพื่อรักษาความปลอดภัยให้ iframe ทีมรักษาความปลอดภัยของเราขอแนะนําให้ทําดังนี้เพื่อปกป้อง iframe

• ต้องใช้ HTTPS เราขอแนะนําอย่างยิ่งให้ใช้ TLS 1.2 ขึ้นไปและเปิดใช้ HTTP Strict Transport Security ดูบทความเกี่ยวกับ Strict Transport Security ของ MDN ที่เกี่ยวข้อง

• เปิดใช้นโยบายความปลอดภัยของเนื้อหาที่เข้มงวด โปรดดูบทความนี้จาก OWASP และบทความ MDN เกี่ยวกับนโยบายรักษาความปลอดภัยเนื้อหาที่เกี่ยวข้อง

• เปิดใช้แอตทริบิวต์คุกกี้ที่ปลอดภัย ดูแอตทริบิวต์ HttpOnly และบทความเกี่ยวกับคุกกี้ใน MDN ที่เกี่ยวข้อง

การกําหนดค่า URI ของ iFrame

URI การตั้งค่าไฟล์แนบคือสิ่งที่ iframe ของเครื่องมือค้นหาไฟล์แนบจะโหลด และเป็นจุดที่ครูจะเริ่มขั้นตอนการสร้างไฟล์แนบของส่วนเสริมในโพสต์ของ Classroom ซึ่งตั้งค่าได้ในคอนโซลโปรเจ็กต์ Google Cloud ตั้งค่า URI นี้ในหน้า API และบริการของโปรเจ็กต์ Google Cloud > SDK ของ Google Workspace Marketplace > การกำหนดค่าแอป

คำนำหน้า URI ของไฟล์แนบที่ได้รับอนุญาตใช้เพื่อตรวจสอบ URI ที่กําหนดไว้ใน AddOnAttachment โดยใช้เมธอด *.addOnAttachments.create และ *.addOnAttachments.patch การตรวจสอบเป็นการจับคู่สตริงอักษรตัวแรกของสตริงตามตัวอักษรและยังไม่อนุญาตให้ใช้ไวลด์การ์ดในขณะนี้

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

ซึ่งจะส่งข้อมูลสำคัญไปยังส่วนเสริมเป็นพารามิเตอร์การค้นหา พารามิเตอร์มี 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 ของ iframe src ระบบจะส่งเมื่อผู้ใช้เคยใช้ส่วนเสริมของคุณก่อนหน้านี้เพื่อช่วยลดความยุ่งยากในการลงชื่อเข้าใช้ของผู้ใช้ปลายทาง คุณต้องจัดการพารามิเตอร์การค้นหานี้ในการติดตั้งใช้งานส่วนเสริม

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

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