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

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

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

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

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

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

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

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

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

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

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

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

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

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

รหัสสินค้า

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

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

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

itemType value identifies the resource type on which this attachment is attached. ค่าสตริงที่ส่งผ่านต้องเป็นค่าใดค่าหนึ่งใน "announcements", "courseWork" หรือ "courseWorkMaterials"

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

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

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

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

รหัสการส่ง

ค่า submissionId คือตัวระบุงานของนักเรียน/นักศึกษา แต่ควรใช้ร่วมกับ attachmentId เพื่อระบุงานของนักเรียน/นักศึกษาในงานที่กำหนด

รวมอยู่ใน studentWorkReviewUri

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

addOnToken value คือโทเค็นการให้สิทธิ์ที่ใช้ในการเรียก 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 การค้นพบไฟล์แนบเป็น 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 การค้นพบไฟล์แนบของส่วนเสริม