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

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

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

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

การกำหนดค่า URI ของ iframe

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

การกำหนดค่า URI ของ iframe

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

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

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

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

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

ค่า courseId จะเป็นตัวระบุของหลักสูตร

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

รหัสสินค้า

ค่า itemId คือตัวระบุของ Announcement

CourseWork หรือ CourseWorkMaterial ที่มีไฟล์แนบนี้อยู่ แนบมาด้วย

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

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

ค่า itemType ระบุประเภททรัพยากรที่

มีไฟล์แนบมาด้วย ค่าสตริงที่ส่งคือ "announcements" "courseWork" หรือ "courseWorkMaterials"

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

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

ค่า attachmentId จะเป็นตัวระบุไฟล์แนบ

รวมอยู่ในteacherViewUri, studentViewUri และ iframe 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 การค้นพบไฟล์แนบ

มิติข้อมูล คำอธิบาย
ต้องระบุ ใช่
URI ระบุไว้ในข้อมูลเมตาของส่วนเสริม
พารามิเตอร์การค้นหา courseId itemId itemType addOnToken และ login_hint
ส่วนสูง ความสูงของหน้าต่าง 80% ลบ 60 พิกเซลสำหรับส่วนหัวด้านบน
ความกว้าง สูงสุด 1600 พิกเซล
ความกว้างหน้าต่าง 90% เมื่อหน้าต่าง <= 600 พิกเซล กว้าง
ความกว้างหน้าต่าง 80% เมื่อหน้าต่าง > กว้าง 600 พิกเซล

ตัวอย่างสถานการณ์การค้นพบไฟล์แนบ

  1. ลงทะเบียนส่วนเสริมของ Classroom ใน Google Workspace แล้ว มาร์เก็ตเพลสที่มี 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 ของครู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 พิกเซลเมื่อยุบ

มิติข้อมูล คำอธิบาย
ต้องระบุ ได้ หากการอัปเกรดลิงก์เป็นไฟล์แนบของส่วนเสริมมีลักษณะดังนี้ ที่ส่วนเสริมของคุณรองรับ
URI ระบุไว้ในข้อมูลเมตาของส่วนเสริม
พารามิเตอร์การค้นหา courseId itemId itemType addOnToken, urlToUpgrade และ login_hint
ส่วนสูง ความสูงของหน้าต่าง 80% ลบ 60 พิกเซลสำหรับส่วนหัวด้านบน
ความกว้าง สูงสุด 1600 พิกเซล
ความกว้างหน้าต่าง 90% เมื่อหน้าต่าง <= 600 พิกเซล กว้าง
ความกว้างหน้าต่าง 80% เมื่อหน้าต่าง > กว้าง 600 พิกเซล
  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+พอร์ต ที่สัมพันธ์กับ 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 การค้นพบไฟล์แนบของส่วนเสริม