ส่วนเสริมของ Classroom จะโหลดขึ้นใน iframe เพื่อมอบประสบการณ์การใช้งานที่ราบรื่นและสะดวกแก่ผู้ใช้ iframe มี 4 ประเภทที่แตกต่างกัน โปรดดูหน้า iframe ในไดเรกทอรีเส้นทางของผู้ใช้เพื่อดูภาพรวมของวัตถุประสงค์และรูปลักษณ์ของ iframe แต่ละรายการ
หลักเกณฑ์ด้านความปลอดภัยของ iframe
พาร์ทเนอร์ควรปฏิบัติตามแนวทางปฏิบัติแนะนำของอุตสาหกรรมเพื่อรักษาความปลอดภัยให้กับ iframe ในการป้องกัน iframe ทีมความปลอดภัยของเราแนะนำให้ทำดังต่อไปนี้:
ต้องใช้ HTTPS เราขอแนะนำให้ใช้ TLS 1.2 ขึ้นไปและเปิดใช้ความปลอดภัยที่เข้มงวดในการรับส่งข้อมูลแบบ HTTP โปรดดูบทความ MDN ที่เกี่ยวข้องนี้เกี่ยวกับ Strict Transport Security
เปิดใช้นโยบายรักษาความปลอดภัยเนื้อหาที่เข้มงวด อ่านบทความ OWASP และบทความ MDN ของนโยบายรักษาความปลอดภัยเนื้อหาที่เกี่ยวข้อง
เปิดใช้แอตทริบิวต์คุกกี้ที่ปลอดภัย โปรดดูแอตทริบิวต์ HttpOnly และบทความ MDN ของคุกกี้ที่เกี่ยวข้อง
การกำหนดค่า URI ของ iframe
URL การตั้งค่าไฟล์แนบคือ iframe ของการค้นพบไฟล์แนบที่โหลดขึ้นมา และเป็นที่ที่ครูจะเริ่มขั้นตอนการสร้างไฟล์แนบของส่วนเสริมในโพสต์ของ Classroom ตั้งค่าได้ในคอนโซลโปรเจ็กต์ Google Cloud ตั้งค่า URI นี้ใน API และบริการของโปรเจ็กต์ Google Cloud > SDK ของ Google Workspace Marketplace > หน้าการกำหนดค่าแอป
คำนำหน้า URI ของไฟล์แนบที่อนุญาตใช้เพื่อตรวจสอบ URI ที่ตั้งค่าไว้ใน AddOnAttachment โดยใช้เมธอด *.addOnAttachments.create
และ *.addOnAttachments.patch
การตรวจสอบจะเป็นการจับคู่คำนำหน้าสตริงตามตัวอักษรและไม่อนุญาตให้ใช้ไวลด์การ์ดในขณะนี้
พารามิเตอร์การค้นหา
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 Upgrade ลิงก์
- URL ที่จะอัปเกรด
ค่า
urlToUpgrade
ที่มีอยู่หมายความว่าครูได้รวมไฟล์แนบลิงก์ในงานและตกลงที่จะอัปเกรดเป็นไฟล์แนบของส่วนเสริม หากยังไม่ได้กำหนดค่าฟีเจอร์นี้ โปรดดูคู่มือเกี่ยวกับการอัปเกรดลิงก์ไปยังไฟล์แนบของส่วนเสริมสำหรับรายละเอียดเพิ่มเติม
รวมอยู่ใน iframe การอัปเกรดลิงก์
พารามิเตอร์ที่เกี่ยวข้องกับการลงชื่อเข้าใช้
พารามิเตอร์การค้นหาของ login_hint
จะให้ข้อมูลเกี่ยวกับผู้ใช้ Classroom ที่เข้าชมหน้าเว็บส่วนเสริม พารามิเตอร์การค้นหานี้ระบุไว้ใน URL src
ของ iframe ระบบจะส่งข้อความนี้เมื่อผู้ใช้ได้ใช้ส่วนเสริมของคุณก่อนหน้านี้เพื่อช่วยลดความยุ่งยากในการลงชื่อเข้าใช้ของผู้ใช้ปลายทาง คุณต้องจัดการพารามิเตอร์การค้นหานี้ในการใช้งานส่วนเสริม
- คำแนะนำการเข้าสู่ระบบ
login_hint
คือตัวระบุที่ไม่ซ้ำสำหรับแท็ก Googleการตั้งค่า หลังจากที่ผู้ใช้เข้าสู่ระบบส่วนเสริมเป็นครั้งแรกแล้ว ระบบจะส่งพารามิเตอร์
login_hint
ในการเข้าชมส่วนเสริมแต่ละครั้งโดยผู้ใช้รายเดิมการใช้งานที่เป็นไปได้สำหรับพารามิเตอร์
login_hint
มีอยู่ 2 อย่าง ได้แก่- ส่งค่า
login_hint
ระหว่างขั้นตอนการตรวจสอบสิทธิ์เพื่อให้ผู้ใช้ไม่ต้องป้อนข้อมูลเข้าสู่ระบบเมื่อกล่องโต้ตอบการลงชื่อเข้าใช้ปรากฏขึ้น ผู้ใช้ไม่ได้ลงชื่อเข้าใช้โดยอัตโนมัติ - หลังจากที่ผู้ใช้ลงชื่อเข้าใช้แล้ว ให้ใช้พารามิเตอร์นี้เพื่อเปรียบเทียบค่ากับผู้ใช้ที่คุณอาจลงชื่อเข้าใช้ส่วนเสริมอยู่แล้ว หากคุณพบการจับคู่ที่ตรงกัน คุณสามารถปล่อยให้ผู้ใช้ลงชื่อเข้าใช้และหลีกเลี่ยงการแสดงขั้นตอนการลงชื่อเข้าใช้ได้ หากพารามิเตอร์ไม่ตรงกับผู้ใช้ที่ลงชื่อเข้าใช้แล้ว ให้แจ้งให้ผู้ใช้ลงชื่อเข้าใช้ด้วยปุ่มลงชื่อเข้าใช้ที่มีแบรนด์ Google
รวมอยู่ใน iframe ทั้งหมด
- ส่งค่า
iframe การค้นพบไฟล์แนบ
มิติข้อมูล | คำอธิบาย |
---|---|
จำเป็น | ได้ |
URI | ระบุไว้ในข้อมูลเมตาของส่วนเสริม |
พารามิเตอร์การค้นหา | courseId , itemId , itemType ,
addOnToken และ login_hint |
ส่วนสูง | ความสูงของหน้าต่าง 80% ลบ 60 พิกเซลสำหรับส่วนหัวด้านบน |
ความกว้าง | สูงสุด 1,600 พิกเซล ความกว้างหน้าต่าง 90% เมื่อหน้าต่างกว้าง <= 600 พิกเซล ความกว้างหน้าต่าง 80% เมื่อหน้าต่างกว้างมากกว่า 600 พิกเซล |
ตัวอย่างสถานการณ์การค้นพบไฟล์แนบ
- ส่วนเสริมของ Classroom ได้รับการลงทะเบียนใน Google Workspace Marketplace ด้วย URI การค้นพบไฟล์แนบเป็น
https://example.com/addon
- ครูติดตั้งส่วนเสริมนี้และสร้างประกาศ งาน หรือสื่อการเรียนการสอนของชั้นเรียนใหม่ในหลักสูตรของตน เช่น
itemId=234
,itemType=courseWork
และcourseId=123
- ขณะกำหนดค่ารายการนั้น ครูจะเลือกส่วนเสริมที่ติดตั้งใหม่เป็นไฟล์แนบ
- Classroom จะสร้าง iframe โดยตั้งค่า URL ของ src เป็น
https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456
- ครูทำงานภายใน iframe เพื่อเลือกไฟล์แนบ
- ในการเลือกไฟล์แนบ ส่วนเสริมจะส่ง
postMessage
ไปยัง Classroom เพื่อปิด iframe
iframe ของครูViewUri และนักเรียนViewUri
มิติข้อมูล | คำอธิบาย |
---|---|
จำเป็น | ได้ |
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 การอัปเกรดลิงก์
มิติข้อมูล | คำอธิบาย |
---|---|
จำเป็น | ได้ หากส่วนเสริมรองรับการอัปเกรดลิงก์เป็นไฟล์แนบของส่วนเสริม |
URI | ระบุไว้ในข้อมูลเมตาของส่วนเสริม |
พารามิเตอร์การค้นหา | courseId , itemId , itemType ,
addOnToken , urlToUpgrade และ login_hint |
ส่วนสูง | ความสูงของหน้าต่าง 80% ลบ 60 พิกเซลสำหรับส่วนหัวด้านบน |
ความกว้าง | สูงสุด 1,600 พิกเซล ความกว้างหน้าต่าง 90% เมื่อหน้าต่างกว้าง <= 600 พิกเซล ความกว้างหน้าต่าง 80% เมื่อหน้าต่างกว้างมากกว่า 600 พิกเซล |
ตัวอย่างสถานการณ์การอัปเกรดลิงก์
- ส่วนเสริมของ Classroom ลงทะเบียนด้วย URI การอัปเกรดลิงก์เป็น
https://example.com/upgrade
คุณได้ระบุรูปแบบคำนำหน้าของโฮสต์และเส้นทางต่อไปนี้สำหรับไฟล์แนบในลิงก์ที่ Classroom ควรพยายามอัปเกรดเป็นไฟล์แนบของส่วนเสริม- โฮสต์คือ
example.com
และคำนำหน้าเส้นทางคือ/quiz
- โฮสต์คือ
- ครูสร้างประกาศ งาน หรือสื่อการเรียนการสอนของชั้นเรียนใหม่ในหลักสูตรหนึ่ง เช่น
itemId=234
,itemType=courseWork
และcourseId=123
- ครูวางลิงก์
https://example.com/quiz/5678
ในกล่องโต้ตอบไฟล์แนบของลิงก์ที่ตรงกับรูปแบบ URL ที่คุณระบุ จากนั้นระบบจะแจ้งให้ครูอัปเกรดลิงก์เป็นไฟล์แนบของส่วนเสริม Classroom จะเปิดตัว iframe ของการอัปเกรดลิงก์โดยมี URL ที่ตั้งค่าเป็น
https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678
คุณต้องประเมินพารามิเตอร์การค้นหาที่ส่งผ่านใน iframe และเรียกไปยังปลายทาง
CreateAddOnAttachment
โปรดทราบว่าพารามิเตอร์การค้นหาurlToUpgrade
มีการเข้ารหัส URI เมื่อส่งผ่านใน iframe คุณต้องถอดรหัสพารามิเตอร์ เพื่อให้ได้มาในรูปแบบดั้งเดิม ตัวอย่างเช่น JavaScript มี ฟังก์ชันdecodeURIComponent()
เมื่อสร้างไฟล์แนบของส่วนเสริมจากลิงก์ได้สำเร็จ ให้ส่ง
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 การค้นพบไฟล์แนบของส่วนเสริม