ส่วนเสริมของ Classroom จะโหลดภายใน iframe เพื่อระบุ ผู้ใช้ปลายทางที่มีประสบการณ์ของผู้ใช้ที่ราบรื่นและสะดวก โดยมีทั้งหมด 4 ประเภท ประเภท iframe โปรดดูหน้า iframe ในไดเรกทอรีเส้นทางของผู้ใช้สำหรับ ภาพรวมของวัตถุประสงค์และลักษณะของ iframe แต่ละอัน
หลักเกณฑ์ด้านความปลอดภัยของ iframe
พาร์ทเนอร์ควรปฏิบัติตามแนวทางปฏิบัติแนะนำของอุตสาหกรรมเพื่อรักษาความปลอดภัยให้กับ iframe ในการป้องกัน iframe ทีมความปลอดภัยของเราแนะนำให้ทำดังต่อไปนี้:
ต้องใช้ HTTPS เราขอแนะนำให้ใช้ TLS 1.2 ขึ้นไปและ เปิดใช้ความปลอดภัยที่เข้มงวดในการรับส่งข้อมูลแบบ HTTP ดู MDN ที่เกี่ยวข้อง บทความเกี่ยวกับ Strict Transport Security
เปิดใช้นโยบายรักษาความปลอดภัยเนื้อหาที่เข้มงวด โปรดดู 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
เมธอด การตรวจสอบคือคำนำหน้าสตริงตามตัวอักษร
ตรงกันและไม่อนุญาตให้ใช้ไวลด์การ์ดในตอนนี้
พารามิเตอร์การค้นหา
iframe จะส่งข้อมูลสำคัญไปยังส่วนเสริมเป็นพารามิเตอร์การค้นหา พารามิเตอร์มี 2 หมวดหมู่ ได้แก่ เกี่ยวข้องกับไฟล์แนบและเกี่ยวกับการลงชื่อเข้าใช้ พารามิเตอร์
พารามิเตอร์ที่เกี่ยวข้องกับไฟล์แนบ
พารามิเตอร์ที่เกี่ยวข้องกับไฟล์แนบจะให้ข้อมูลเกี่ยวกับ งาน ไฟล์แนบของส่วนเสริม งานที่นักเรียนส่ง และ การให้สิทธิ์โทเค็น
- รหัสหลักสูตร
ค่า
courseId
จะเป็นตัวระบุของหลักสูตรรวมอยู่ใน iframe ทั้งหมด
- รหัสสินค้า
ค่า
itemId
คือตัวระบุของAnnouncement
CourseWork
หรือCourseWorkMaterial
ที่มีไฟล์แนบนี้อยู่ แนบมาด้วยรวมอยู่ใน iframe ทั้งหมด
- ประเภทรายการ
ค่า
itemType
ระบุประเภททรัพยากรที่มีไฟล์แนบมาด้วย ค่าสตริงที่ส่งคือ
"announcements"
"courseWork"
หรือ"courseWorkMaterials"
รวมอยู่ใน iframe ทั้งหมด
- รหัสของไฟล์แนบ
ค่า
attachmentId
จะเป็นตัวระบุไฟล์แนบรวมอยู่ใน
teacherViewUri
,studentViewUri
และ iframestudentWorkReviewUri
- รหัสการส่ง
ค่า
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 อย่าง ได้แก่- ส่งค่า
login_hint
ในระหว่างขั้นตอนการตรวจสอบสิทธิ์เพื่อให้พารามิเตอร์ ให้ผู้ใช้ไม่ต้องป้อนข้อมูลเข้าสู่ระบบเมื่อกล่องโต้ตอบการลงชื่อเข้าใช้ จะปรากฏขึ้น ผู้ใช้ไม่ได้ลงชื่อเข้าใช้โดยอัตโนมัติ - หลังจากที่ผู้ใช้ลงชื่อเข้าใช้แล้ว ให้ใช้พารามิเตอร์นี้เพื่อเปรียบเทียบ ให้กับผู้ใช้ที่คุณอาจลงชื่อเข้าใช้ส่วนเสริมไว้แล้ว ถ้า เมื่อพบการจับคู่ที่ตรงกัน คุณสามารถให้ผู้ใช้ลงชื่อเข้าใช้ ขั้นตอนการลงชื่อเข้าใช้ หากพารามิเตอร์ไม่ตรงกับรายการที่คุณลงชื่อเข้าใช้ แจ้งให้ผู้ใช้ลงชื่อเข้าใช้ด้วยการลงชื่อเข้าใช้ที่มีแบรนด์ Google
รวมอยู่ใน iframe ทั้งหมด
- ส่งค่า
iframe การค้นพบไฟล์แนบ
มิติข้อมูล | คำอธิบาย |
---|---|
ต้องระบุ | ใช่ |
URI | ระบุไว้ในข้อมูลเมตาของส่วนเสริม |
พารามิเตอร์การค้นหา | courseId itemId itemType
addOnToken และ login_hint |
ส่วนสูง | ความสูงของหน้าต่าง 80% ลบ 60 พิกเซลสำหรับส่วนหัวด้านบน |
ความกว้าง | สูงสุด 1600 พิกเซล ความกว้างหน้าต่าง 90% เมื่อหน้าต่าง <= 600 พิกเซล กว้าง ความกว้างหน้าต่าง 80% เมื่อหน้าต่าง > กว้าง 600 พิกเซล |
ตัวอย่างสถานการณ์การค้นพบไฟล์แนบ
- ลงทะเบียนส่วนเสริมของ Classroom ใน Google Workspace แล้ว
มาร์เก็ตเพลสที่มี 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 พิกเซลสำหรับส่วนหัวด้านบน |
ความกว้าง | สูงสุด 1600 พิกเซล ความกว้างหน้าต่าง 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+พอร์ต
ที่สัมพันธ์กับ 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 การค้นพบไฟล์แนบของส่วนเสริม