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

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

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

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

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

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

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

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

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

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

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

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

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

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

รหัสโพสต์ (เลิกใช้งานแล้ว)

ค่า postId คือตัวระบุของโพสต์ (ประกาศ งานในหลักสูตร หรือเนื้อหางานของหลักสูตร) ที่มีการแนบไฟล์แนบนี้

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

รหัสสินค้า

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

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

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

ค่า itemType ระบุประเภททรัพยากรที่มีการแนบไฟล์แนบนี้ ค่าสตริงที่ส่งคือ "announcements", "courseWork" หรือ "courseWorkMaterials"

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

รหัสไฟล์แนบ

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

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

รหัสการส่ง

ค่า submissionId เป็นตัวระบุงานของนักเรียน แต่ควรใช้ร่วมกับ attachmentId เพื่อระบุงานของนักเรียนจากงานชิ้นหนึ่งๆ

ซึ่งรวมอยู่ในstudentWorkReviewUri

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

ค่า addOnToken เป็นโทเค็นการให้สิทธิ์ที่ใช้เรียก addOnAttachments.create เพื่อสร้างส่วนเสริม

รวมอยู่ใน iframe Discovery ไฟล์แนบ และ iframe อัปเกรดลิงก์

URL ที่จะอัปเกรด

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

รวมอยู่ใน iframe การอัปเกรดลิงก์

พารามิเตอร์การค้นหา login_hint จะให้ข้อมูลเกี่ยวกับผู้ใช้ Classroom ที่เข้าชมหน้าเว็บของส่วนเสริม พารามิเตอร์การค้นหานี้มีอยู่ใน URL src ของ iframe ซึ่งจะส่งเมื่อผู้ใช้เคยใช้ส่วนเสริมของคุณมาก่อนเพื่อช่วยลดอุปสรรคในการลงชื่อเข้าใช้ของผู้ใช้ปลายทาง คุณจะต้องจัดการพารามิเตอร์ การค้นหานี้ในการใช้งานส่วนเสริม

คำแนะนำในการเข้าสู่ระบบ

login_hint เป็นตัวระบุที่ไม่ซ้ำกันสำหรับ

การตั้งค่า หลังจากที่ผู้ใช้เข้าสู่ระบบส่วนเสริมเป็นครั้งแรกแล้ว ระบบจะส่งพารามิเตอร์ login_hint ต่อการเข้าชมส่วนเสริมของคุณแต่ละครั้งโดยผู้ใช้รายเดิม

การใช้งานพารามิเตอร์ login_hint อาจมี 2 ลักษณะ ได้แก่

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

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

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

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

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

  1. ส่วนเสริมของ Classroom ได้รับการลงทะเบียนใน Google Workspace Marketplace ด้วย URI การสำรวจไฟล์แนบเป็น https://example.com/addon
  2. ครูติดตั้งส่วนเสริมนี้และสร้างประกาศ งาน หรือสื่อการเรียนการสอนของชั้นเรียนรายการใหม่ในหลักสูตรหนึ่ง ตัวอย่างเช่น itemId=234, itemType=courseWork และ courseId=123
  3. ขณะกำหนดค่ารายการนั้น ครูจะเลือกส่วนเสริมที่ติดตั้งใหม่เป็นไฟล์แนบ
  4. Classroom จะสร้าง iframe ที่มีการตั้งค่า src URL เป็น 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, postId (เลิกใช้งานแล้ว), itemId, itemType, attachmentId และ login_hint
ส่วนสูง ความสูงของหน้าต่าง 100% ลบด้วย 140 พิกเซลสำหรับส่วนหัวด้านบน
ความกว้าง ความกว้างของหน้าต่าง 100%

iframe ของStudentWorkReviewUri

มิติข้อมูล คำอธิบาย
จำเป็น ไม่ (ตรวจสอบว่านี่เป็นไฟล์แนบประเภทกิจกรรมหรือไม่)
URI studentWorkReviewUri
พารามิเตอร์การค้นหา courseId, postId (เลิกใช้งานแล้ว), itemId, itemType, attachmentId, submissionId และ login_hint
ส่วนสูง ความสูงของหน้าต่าง 100% ลบด้วย 168px สำหรับส่วนหัวด้านบน
ความกว้าง ความกว้างหน้าต่าง 100% ลบด้วยความกว้างของแถบด้านข้าง<> แถบด้านข้างคือ 312 พิกเซล เมื่อขยายและ 56 พิกเซลเมื่อยุบ

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