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

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

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

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

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

URL การตั้งค่าไฟล์แนบคือ 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 จะเป็นตัวระบุไฟล์แนบ

รวมอยู่ใน 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 อย่าง ได้แก่

  1. ส่งค่า login_hint ระหว่างขั้นตอนการตรวจสอบสิทธิ์เพื่อให้ผู้ใช้ไม่ต้องป้อนข้อมูลเข้าสู่ระบบเมื่อกล่องโต้ตอบการลงชื่อเข้าใช้ปรากฏขึ้น ผู้ใช้ไม่ได้ลงชื่อเข้าใช้โดยอัตโนมัติ
  2. หลังจากที่ผู้ใช้ลงชื่อเข้าใช้แล้ว ให้ใช้พารามิเตอร์นี้เพื่อเปรียบเทียบค่ากับผู้ใช้ที่คุณอาจลงชื่อเข้าใช้ส่วนเสริมอยู่แล้ว หากคุณพบการจับคู่ที่ตรงกัน คุณสามารถปล่อยให้ผู้ใช้ลงชื่อเข้าใช้และหลีกเลี่ยงการแสดงขั้นตอนการลงชื่อเข้าใช้ได้ หากพารามิเตอร์ไม่ตรงกับผู้ใช้ที่ลงชื่อเข้าใช้แล้ว ให้แจ้งให้ผู้ใช้ลงชื่อเข้าใช้ด้วยปุ่มลงชื่อเข้าใช้ที่มีแบรนด์ Google

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

iframe การค้นพบไฟล์แนบ

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

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

  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 ของครู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 พิกเซลสำหรับส่วนหัวด้านบน
ความกว้าง สูงสุด 1,600 พิกเซล
ความกว้างหน้าต่าง 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+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 การค้นพบไฟล์แนบของส่วนเสริม