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

Tiện ích bổ sung dành cho Lớp học được tải trong iframe để mang lại cho người dùng cuối trải nghiệm liền mạch và thuận tiện. Có 4 loại iframe riêng biệt; hãy xem các trang iframe trong thư mục Hành trình của người dùng để biết thông tin tổng quan về mục đích và giao diện của từng iframe.

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

Đối tác phải tuân thủ 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 khuyến nghị như sau:

Cấu hình URI iFrame

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

Cấu hình URI iFrame

Tiền tố URI đính kèm được phép dùng để xác thực các URI được đặt trong AddOnAttachment bằng phương thức *.addOnAttachments.create và *.addOnAttachments.patch. Quy trình xác thực là kết quả so khớp tiền tố chuỗi cố định 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 tới tiện ích bổ sung dưới dạng tham số truy vấn. Có hai loại tham số: tham số liên quan đến tệp đính kèm và tham số liên quan đến việc đăng nhập.

Các tham 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ủa tiện ích bổ sung, bài tập mà 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.

Đi kèm với tất cả iframe.

Mã bài đăng (không dùng nữa)

Giá trị postId là giá trị nhận dạng của bài đăng (thông báo, bài tập trong khoá học hoặc tài liệu bài tập trong khoá học) có đính kèm tệp đính kèm này.

Đi kèm với tất cả iframe.

Mã mặt hàng

Giá trị itemId là giá trị nhận dạng của Announcement, CourseWork hoặc CourseWorkMaterial mà tệp đính kèm này được đính kèm.

Đi kèm với tất cả iframe.

Loại mục

Giá trị itemType xác định loại tài nguyên có đính kèm tệp đính kèm này. Giá trị chuỗi đã chuyển là một trong các giá trị "announcements", "courseWork" hoặc "courseWorkMaterials".

Đi kèm với tất cả iframe.

Mã tệp đính kèm

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

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

Mã của bài tập đã nộp

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

Đi kèm với studentWorkReviewUri.

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

Giá trị addOnToken là mã thông báo uỷ quyền dùng để thực hiện lệnh gọi addOnAttachments.create nhằm tạo tiện ích bổ sung.

Đi kèm với iframe Khám phá tệp đính kèm và iframe Nâng cấp liên kết.

URL cần nâng cấp

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

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

Tham số truy vấn login_hint cung cấp thông tin về việc người dùng 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. Thông báo này được gửi khi người dùng trước đây đã sử dụng tiện ích bổ sung của bạn để giúp giảm những bước 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 tài khoản 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, tham số login_hint sẽ được chính người dùng đó 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.

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 xác thực của họ khi hộp thoại đăng nhập xuất hiện. Người dùng không được đăng nhập tự động.
  2. Sau khi người dùng đã đăng nhập, hãy sử dụng tham số này để so sánh giá trị với 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 thấy kết quả trùng khớp, bạn có thể giữ nguyên 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 tham số này không khớp với bất kỳ người dùng đã đăng nhập nào, hãy nhắc người dùng đăng nhập bằng nút đăng nhập có thương hiệu Google.

Đi kèm với tất cả iframe.

iframe khám phá tệp đính kèm

Phương diện Nội dung 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, postId (không dùng nữa), itemId, itemType, addOnToken và login_hint.
Chiều cao 80% chiều cao cửa sổ trừ 60px cho tiêu đề trên cùng
Chiều rộng Tối đa 1600px
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ổ > 600px

Ví dụ về tình huống 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 Marketplace có URI phát hiện tệp đính kèm là https://example.com/addon.
  2. Một 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 mới trong một trong các 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ài đặt làm tệp đính kèm.
  4. Lớp học sẽ tạo một 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 sẽ thực hiện công việc trong iframe để lựa chọn tệp đính kèm.
  5. Khi bạn chọn tệp đính kèm, tiện ích bổ sung sẽ gửi postMessage đến Lớp học để đóng iframe.

Khung nội tuyến merchantViewUri vàstudentViewUri

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

Khung iframe của sinh viênWorkReviewUri

Phương diện Nội dung 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 không)
URI studentWorkReviewUri
Tham số truy vấn courseId, postId (không dùng nữa), itemId, itemType, attachmentId, submissionId và login_hint.
Chiều cao 100% chiều cao cửa sổ trừ đi 168px cho tiêu đề trên cùng
Chiều rộng 100% chiều rộng cửa sổ 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 Nội dung mô tả
Bắt buộc Có, nếu tiện ích bổ sung của bạn hỗ trợ đường liên kết đến tệp đính kèm.
URI Được cung cấp trong siêu dữ liệu của tiện ích bổ sung
Tham số truy vấn courseId, postId (không dùng nữa), itemId, itemType, addOnToken, urlToUpgrade và login_hint.
Chiều cao 80% chiều cao cửa sổ trừ 60px cho tiêu đề trên cùng
Chiều rộng Tối đa 1600px
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ổ > 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 các mẫu tiền tố đường dẫn và máy chủ lưu trữ sau đây cho Tệp đính kèm của đường liên kết mà Lớp học sẽ cố gắng nâng cấp lên tệp đính kèm củ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 thông báo, bài tập hoặc tài liệu mới trong một trong các khoá học của họ. 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 hộp thoại Tệp đính kèm đường liên kết khớp với mẫu URL mà bạn đã cung cấp. Sau đó, giáo viên sẽ được nhắc nâng cấp Đường liên kết thành tệp đính kèm của tiện ích bổ sung.

  4. Lớp học sẽ chạy iframe Link Upgrade với URL được đặt thành https://example.com/upgrade?courseId=123&postId=234&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678.

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

  6. Khi tạo thành công một tệp đính kèm bằng tiện ích bổ sung 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 khỏi công cụ học tập bằng cách gửi một postMessage với tải trọng {type: 'Classroom', action: 'closeIframe'}. Lớp học chỉ chấp nhận postMessage này từ host_name+cổng tương ứng với URI ban đầu đã đượ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 khỏi iframe

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

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

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

Các 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 việc chặn cookie của bên thứ ba khiến bạn khó duy trì phiên đăng nhập trong iframe. Hãy tham khảo https://www.cookiestatus.com để biết trạng thái hiện tại của tính năng chặn cookie trên các trình duyệt khác nhau. Tất nhiên, vấn đề này không phải là vấn đề riêng của các tiện ích bổ sung của Google Lớp học và ảnh hưởng đến tất cả các trang web đặt nội tuyến cho 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 của 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 ngữ cảnh bên thứ nhất khi ở trong ngữ cảnh bên thứ ba.
  • Hãy yêu cầu người dùng cho phép cookie của bên thứ ba. Không phải lúc nào điều này cũng có thể áp dụng với tất cả người dùng.
  • Thiết kế các ứng dụng web một trang không dựa vào cookie.

Chúng tôi dự kiến sẽ có nhiều hạn chế cookie hơn trong các phiên bản trình duyệt sau này. 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 mà đối tác yêu cầu.

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 URL

Giáo viên thường tạo bài tập bằng các tệp đính kèm đường liên kết. Để khuyến khích việc sử dụng 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 các tài nguyên có thể truy cập được trong tiện ích bổ sung của mình. Một giáo viên đính kèm đường liên kết khớp với một trong các biểu thức chính quy của bạn sẽ thấy một hộp thoại có thể đóng, khuyến khích họ dùng thử tiện ích bổ sung của bạn. 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 họ.

Nếu bạn muốn cung cấp hành vi này cho giáo viên, hãy cung cấp cho người liên hệ của Google các 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 xung đột với một tiện ích bổ sung khác, thì bạn có thể sửa đổi các biểu thức đó cho bị 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 chọn một tệp đính kèm đường liên kết vào bài tập mới.

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

Hộp thoại phát hiện Regex Hình 3. Hộp thoại tương tác mà giáo viên sẽ thấy khi đường liên kết được dán khớp với một biểu thức chính quy do nhà phát triển bên thứ ba chỉ định.

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