Chi tiết về iframe và tham số truy vấn

Các tiện ích bổ sung dành cho Lớp học được tải trong iframe để cung cấp người dùng cuối có được trải nghiệm liền mạch và thuận tiện. Có bốn điểm khác biệt loại iframe; xem các trang iframe trong thư mục Hành trình của người dùng để biết tổng quan về mục đích và hình thức của mỗi iframe.

nguyên tắc bảo mật iframe

Đối tác phải thực hiện theo các phương pháp hay nhất trong ngành để bảo mật iframe của họ. Để bảo vệ iframe, nhóm bảo mật của chúng tôi đề xuất những việc sau:

Cấu hình URI iFrame

URI thiết lập tệp đính kèm là nội dung mà iframe của tính năng Khám phá tệp đính kèm tải và là nơi giáo viên bắt đầu quy trình tạo tiện ích bổ sung tệp đính kèm trên Bài đăng trên Lớp học. Bạn có thể thiết lập thông tin này trong bảng điều khiển dự án trên Google Cloud. Đặt URI này trong API & API của dự án Google Cloud Dịch vụ > SDK trên Google Workspace Marketplace > Cấu hình ứng dụng.

Cấu hình URI iFrame

Tiền tố URI tệp đính kèm được phép được dùng để xác thực các URI được thiết lập trong AddOnAttachment bằng cách sử dụng *.addOnAttachments.create và *.addOnAttachments.patch. Xác thực là một tiền tố chuỗi ký tự và không cho phép sử dụng ký tự đại diện tại thời điểm này.

Tham số truy vấn

Iframe truyền thông tin quan trọng đến tiện ích bổ sung dưới dạng tham số truy vấn. Có hai loại thông số: thông số liên quan đến tệp đính kèm và thông số liên quan đến hoạt động đăng nhập tham số.

Các thông số liên quan đến tệp đính kèm cung cấp cho tiện ích bổ sung thông tin về khoá học, bài tập, tệp đính kèm có tiện ích bổ sung, bài tập học viên nộp và mã thông báo uỷ quyền.

Mã khoá học

Giá trị courseId là giá trị nhận dạng của khoá học.

Được bao gồm trong tất cả các iframe.

Mã mặt hàng

Giá trị itemId là mã nhận dạng của Announcement,

CourseWork hoặc CourseWorkMaterial chứa tệp đính kèm này được đính kèm.

Được bao gồm trong tất cả các iframe.

Loại mục

Giá trị itemType xác định loại tài nguyên chứa

tệp đính kèm. Giá trị chuỗi đã truyền là một trong số "announcements", "courseWork" hoặc "courseWorkMaterials".

Được bao gồm trong tất cả các iframe.

Mã tệp đính kèm

Giá trị attachmentId là giá trị nhận dạng tệp đính kèm.

Đi kèm với teacherViewUri, studentViewUri và studentWorkReviewUri iframe.

Mã bài nộp

Giá trị submissionId là giá trị nhận dạng bài tập của học viên, nhưng nên được sử dụng kết hợp với attachmentId để xác định bài tập cụ thể của học viên.

Đi kèm với studentWorkReviewUri.

Mã thông báo của tiện ích bổ sung

Giá trị addOnToken là mã thông báo uỷ quyền được dùng để tạo

addOnAttachments.create để tạo tiện ích bổ sung.

Đi kèm với iframe của tính năng Khám phá tệp đính kèm và Bản nâng cấp đường liên kết iframe.

URL cần nâng cấp

Sự hiện diện của giá trị urlToUpgrade ngụ ý rằng

giáo viên đã đính kèm một Đường liên kết đính kèm vào bài tập và đã đồng ý để nâng cấp thành tệp đính kèm chứa tiện ích bổ sung. Nếu bạn chưa có tài khoản này đã định cấu hình tính năng, hãy xem hướng dẫn về cách nâng cấp đường liên kết lên tiện ích bổ sung tệp đính kèm để biết thêm chi tiết.

Đi kèm với iframe khi nâng cấp liên kết.

Tham số truy vấn login_hint cung cấp thông tin về Người dùng trong Lớp học truy cập vào trang web tiện ích bổ sung. Tham số truy vấn này được cung cấp trên URL src của iframe. Giá trị này được gửi đi khi người dùng đã sử dụng trước đó tiện ích bổ sung của mình để giảm sự phiền hà khi đăng nhập cho người dùng cuối. Bạn phải xử lý tham số truy vấn này trong quá trình triển khai tiện ích bổ sung.

Gợi ý đăng nhập

login_hint là giá trị nhận dạng duy nhất cho quyền truy cập Google của người dùng

Tài khoản. Sau khi người dùng đăng nhập vào tiện ích bổ sung của bạn lần đầu tiên, Thông số login_hint được chuyển vào mỗi lần truy cập tiếp theo vào tiện ích bổ sung của bạn bằng cách cùng một người dùng.

Có hai cách sử dụng tiềm năng cho tham số login_hint:

  1. Truyền giá trị login_hint trong quy trình xác thực để người dùng không cần nhập thông tin đăng nhập khi hộp thoại đăng nhập sẽ xuất hiện. Người dùng không được tự động đăng nhập.
  2. Sau khi người dùng đăng nhập, hãy sử dụng thông số này để so sánh giá trị cho bất kỳ người dùng nào mà bạn có thể đã đăng nhập vào tiện ích bổ sung. Nếu bạn tìm thấy kết quả phù hợp, bạn có thể duy trì trạng thái đăng nhập của người dùng và tránh hiển thị quy trình đăng nhập. Nếu thông số đó không khớp với bất kỳ tài khoản nào mà bạn đã đăng nhập người dùng, nhắc người dùng đăng nhập bằng thông tin đăng nhập có thương hiệu Google .

Được bao gồm trong tất cả các iframe.

iframe của tính năng Khám phá tệp đính kèm

Phương diện Mô tả
Bắt buộc Có
URI Được cung cấp trong siêu dữ liệu của tiện ích bổ sung
Tham số truy vấn courseId, itemId, itemType addOnToken và login_hint.
Chiều cao Chiều cao cửa sổ 80% trừ đi 60px cho tiêu đề trên cùng
Chiều rộng Tối đa 1.600px
90% chiều rộng cửa sổ khi cửa sổ <= 600px rộng
80% chiều rộng cửa sổ khi cửa sổ > rộng 600px

Ví dụ về trường hợp khám phá tệp đính kèm

  1. Một tiện ích bổ sung của Lớp học đã được đăng ký trong Google Workspace Thị trường có URI Khám phá tệp đính kèm là https://example.com/addon.
  2. Giáo viên cài đặt tiện ích bổ sung này và tạo thông báo, bài tập hoặc tài liệu trong một khoá học của họ. Ví dụ: itemId=234, itemType=courseWork và courseId=123.
  3. Trong khi định cấu hình mục đó, giáo viên sẽ chọn tiện ích bổ sung mới được cài đặt dưới dạng tệp đính kèm.
  4. Lớp học tạo iframe với URL src được đặt thành https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456.
    1. Giáo viên thực hiện công việc trong iframe để lựa chọn tệp đính kèm.
  5. Khi lựa chọn tệp đính kèm, tiện ích bổ sung sẽ gửi postMessage đến Lớp học để đóng iframe.

Các iframe EducationViewUri và customerViewUri

Phương diện Mô tả
Bắt buộc Có
URI teacherViewUri hoặc studentViewUri
Tham số truy vấn courseId, itemId, itemType attachmentId và login_hint.
Chiều cao Chiều cao cửa sổ 100% trừ đi 140px cho tiêu đề trên cùng
Chiều rộng Chiều rộng cửa sổ 100%

iframe iframe của sinh viênWorkReviewUri

Phương diện Mô tả
Bắt buộc Không (Xác định xem đây có phải là tệp đính kèm loại hoạt động hay không)
URI studentWorkReviewUri
Tham số truy vấn courseId, itemId, itemType attachmentId, submissionId và login_hint.
Chiều cao Chiều cao cửa sổ 100% trừ đi 168px cho tiêu đề trên cùng
Chiều rộng Chiều rộng cửa sổ 100% trừ đi chiều rộng thanh bên<> thanh bên là 312px khi mở rộng và 56px khi thu gọn

Phương diện Mô tả
Bắt buộc Có, nếu bạn nâng cấp đường liên kết thành tiện ích bổ sung đính kèm mà tiện ích bổ sung của bạn hỗ trợ.
URI Được cung cấp trong siêu dữ liệu của tiện ích bổ sung
Tham số truy vấn courseId, itemId, itemType addOnToken, urlToUpgrade và login_hint.
Chiều cao Chiều cao cửa sổ 80% trừ đi 60px cho tiêu đề trên cùng
Chiều rộng Tối đa 1.600px
90% chiều rộng cửa sổ khi cửa sổ <= 600px rộng
80% chiều rộng cửa sổ khi cửa sổ > rộng 600px
  1. Một tiện ích bổ sung của Lớp học được đăng ký bằng URI nâng cấp đường liên kết là https://example.com/upgrade. Bạn đã cung cấp máy chủ và đường dẫn sau các mẫu tiền tố cho Tệp đính kèm đường liên kết mà Lớp học nên thử nâng cấp lên tệp đính kèm chứa tiện ích bổ sung:
    • Máy chủ lưu trữ là example.com và tiền tố đường dẫn là /quiz.
  2. Giáo viên tạo một thông báo, bài tập hoặc tài liệu mới trong một trong khoá học của mình. Ví dụ: itemId=234, itemType=courseWork và courseId=123.
  3. Giáo viên dán một đường liên kết https://example.com/quiz/5678 vào phần Đường liên kết hộp thoại tệp đính kèm khớp với mẫu URL bạn đã cung cấp. Giáo viên này là sau đó được nhắc nâng cấp Đường liên kết đến tiện ích bổ sung đính kèm.

  4. Lớp học chạy iframe Nâng cấp đường liên kết với tập hợp URL đến https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678.

  5. Bạn đánh giá các tham số truy vấn được chuyển qua iframe và thực hiện lệnh gọi đến điểm cuối CreateAddOnAttachment. Xin lưu ý rằng truy vấn urlToUpgrade được mã hoá URI khi được truyền trên iframe. Bạn cần giải mã để lấy tham số đó ở dạng ban đầu. JavaScript, ví dụ: ưu đãi hàm decodeURIComponent().

  6. Khi tạo thành công tệp đính kèm bằng tiện ích bổ sung từ một Đường liên kết, bạn sẽ gửi postMessage đến Lớp học để đóng iframe.

Đóng iframe

Bạn có thể đóng iframe qua công cụ học tập bằng cách gửi postMessage có tải trọng {type: 'Classroom', action: 'closeIframe'}. Lớp học chỉ chấp nhận postMessage này từ cổng host_name+ tương ứng với URI gốc đã được mở.

<button id="close">Send message to close iframe</button>
<script>
  document.querySelector('#close')
    .addEventListener('click', () => {
        window.parent.postMessage({
            type: 'Classroom',
            action: 'closeIframe',
        }, '*');
    });
</script>

Đóng iframe từ iframe

Miền+cổng của trang gửi sự kiện postMessage phải có cùng cổng+tên miền giống như cổng của URI được dùng để chạy iframe, nếu không thông báo sẽ bị bỏ qua. Một giải pháp tạm thời là chuyển hướng trở lại một trang trên miền ban đầu không làm gì hơn ngoài gửi sự kiện postMessage.

Đóng iframe từ một thẻ mới

Tính năng bảo vệ trên nhiều miền ngăn tính năng này hoạt động. Một giải pháp là xử lý tự động giao tiếp giữa iframe và thẻ mới, đồng thời cho phép iframe chịu trách nhiệm cuối cùng về việc đưa ra sự kiện đóng postMessage. Ở một bên lưu ý rằng đường siêu liên kết "Mở bằng tên đối tác" sẽ bị xoá để người dùng không tạo thẻ theo cách này trong tương lai gần.

Quy định hạn chế

Tất cả iframe đều được mở bằng các thuộc tính hộp cát sau:

  • allow-popups
  • allow-popups-to-escape-sandbox
  • allow-forms
  • allow-scripts
  • allow-storage-access-by-user-activation
  • allow-same-origin

và chính sách tính năng sau đây

  • allow="microphone *"

Xin lưu ý rằng tính năng chặn cookie của bên thứ ba sẽ gây khó khăn cho việc duy trì đã đăng nhập trong iframe. Tham khảo https://www.cookiestatus.com trên trạng thái chặn cookie hiện tại trên các trình duyệt khác nhau. Tất nhiên, điều này không phải là vấn đề riêng ở các tiện ích bổ sung của Google Lớp học và ảnh hưởng đến mọi trang web iframe của bên thứ ba. Nhiều đối tác của chúng tôi đã gặp phải vấn đề này.

Một số giải pháp chung là:

  • Mở một thẻ mới để tạo cookie trong bối cảnh bên thứ nhất. Một số trình duyệt cấp quyền truy cập vào cookie được tạo trong bối cảnh bên thứ nhất khi đang ở bối cảnh của bên thứ ba.
  • Yêu cầu người dùng cho phép cookie của bên thứ ba. Điều này không phải lúc nào cũng thực hiện được với tất cả người dùng.
  • Thiết kế các ứng dụng web trang đơn không dựa vào cookie.

Chúng tôi dự kiến sẽ có thêm các hạn chế về cookie trong các phiên bản trình duyệt trong tương lai. Sáng tạo yêu cầu về tính năng để gửi ý kiến phản hồi cho Google về cách giảm mức tăng cần thiết của các đối tác.

Cho phép phát hiện tiện ích bổ sung bằng cách sử dụng biểu thức chính quy của URL

Giáo viên thường tạo bài tập có đường liên kết đính kèm. Để quảng bá việc sử dụng của tiện ích bổ sung, bạn có thể chỉ định biểu thức chính quy khớp với URL của tài nguyên có thể truy cập được trong tiện ích bổ sung của bạn. Giáo viên đính kèm một đường liên kết khớp với một đường liên kết biểu thức chính quy của bạn sẽ thấy một hộp thoại có thể bỏ qua khuyến khích họ thử tiện ích bổ sung của mình. Họ chỉ thấy hộp thoại nếu tiện ích bổ sung đã được cài đặt cho tài khoản của mình.

Nếu bạn muốn giáo viên thực hiện hành vi này, hãy cung cấp địa chỉ liên hệ với biểu thức chính quy thích hợp. Nếu biểu thức chính quy mà bạn cung cấp quá rộng hoặc mâu thuẫn với một tiện ích bổ sung khác, thì các tiện ích đó có thể được sửa đổi để hạn chế hoặc khác biệt hơn.

Giáo viên đang chọn đường liên kết đính kèm Hình 1. Giáo viên đang chọn một đường liên kết tệp đính kèm vào một bài tập mới.

Dán đường liên kết của giáo viên Hình 2. Giáo viên đang dán một đường liên kết từ một bên thứ ba nguồn. Giáo viên đã cài đặt ứng dụng của bên thứ ba Tiện ích bổ sung dành cho Lớp học.

Hộp thoại khả năng phát hiện biểu thức chính quy Hình 3. Đã trình bày hộp thoại tương tác cho giáo viên khi đường liên kết được dán khớp với một biểu thức chính quy được chỉ định bởi với nhà phát triển bên thứ ba.

Nếu giáo viên chọn "Thử ngay" trong cửa sổ pop như trong hình 3. đã chuyển hướng đến iframe của Khám phá tệp đính kèm của tiện ích bổ sung.