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

Các tiện ích bổ sung của Lớp học được tải trong một iframe để mang đến cho người dùng cuối trải nghiệm liền mạch và thuận tiện. Có 4 loại khung hiển thị nội tuyến (iframe) khác nhau; 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 iframe

Đối tác cần tuâ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 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 tệp đính kèm tiện ích bổ sung trên bài đăng trong Lớp học. Bạn có thể đặt giá trị này trong bảng điều khiển dự án Google Cloud. Đặt URI này trong trang API & Dịch vụ > SDK Google Workspace Marketplace > Cấu hình ứng dụng của dự án Google Cloud.

Cấu hình URI iFrame

Tiền tố URI của tệp đính kèm được phép được dùng để xác thực các URI được đặt trong AddOnAttachment bằng các phương thức *.addOnAttachments.create và *.addOnAttachments.patch. Quy trình xác thực là một kiểu khớp tiền tố chuỗi cố định và hiện không cho phép sử dụng ký tự đại diện.

Tham số truy vấn

Các 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 danh mục 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 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ủa tiện ích bổ sung, bài tập mà học viên đã gửi và mã thông báo uỷ quyền.

Mã khoá học

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

Đ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 mà thuộc tính này

tệp đính kèm. Giá trị chuỗi đã truyề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.

Có trong các iframe teacherViewUri, studentViewUri và studentWorkReviewUri.

Mã bài 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 bạn nên sử 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ể.

Có trong 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 để tạo

Các lệnh gọi addOnAttachments.create để 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 đường liên kết.

URL cần nâng cấp

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

đã thêm một Tệp đính kèm đường liên kết vào bài tập và đồng ý nâng cấp tệp đính kèm đó thành tiện ích bổ sung đính kèm. 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 thành tệp đính kèm của tiện ích bổ sung để biết thêm thông tin chi tiết.

Có trong iframe Nâng cấp đường 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 đang truy cập vào trang web của 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 đã sử dụng tiện ích bổ sung của bạn trước đó để giúp giảm sự phiền hà khi người dùng cuối đăng nhập. Bạn bắt buộc 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, thông số login_hint sẽ được truyền trong mỗi lần truy cập tiếp theo vào tiện ích bổ sung của bạn bởi 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 xác thực khi hộp thoại đăng nhập 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 tham số này để so sánh giá trị với mọi người dùng mà bạn có thể đã đăng nhập vào tiện ích bổ sung. Nếu tìm thấy kết quả trùng khớp, bạn có thể để người dùng đăng nhập và tránh hiển thị quy trình đăng nhập. Nếu tham số không khớp với bất kỳ người dùng nào đã đăng nhập, hãy nhắc người dùng đăng nhập bằng nút đăng nhập mang thương hiệu Google.

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

Khung hiển thị 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 80% chiều cao cửa sổ trừ đi 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 rộng

Ví dụ về trường hợp sử dụng tính năng Khám phá tệp đính kèm

  1. Tiện ích bổ sung cho Lớp học được đăng ký trong Google Workspace Marketplace bằng 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 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 tạo một iframe có 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 để 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 teacherViewUri và studentViewUri

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 100% chiều cao cửa sổ trừ đi 140px cho tiêu đề trên cùng
Chiều rộng Chiều rộng cửa sổ 100%

iframe studentWorkReviewUri

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 thuộc 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 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ừ 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 tiện ích bổ sung của bạn hỗ trợ tính năng nâng cấp đường liên kết thành tệp đính kèm tiện ích bổ sung.
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 80% chiều cao cửa sổ trừ đi 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 rộng
  1. 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ố máy chủ lưu trữ và đường dẫn sau đây cho Tệp đính kèm đường liên kết mà Lớp học sẽ cố gắng nâng cấp lên tiện ích bổ sung đính kèm:
    • 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 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 tiện ích bổ sung.

  4. Lớp học sẽ chạy iframe Nâng cấp đường liên kết với URL được đặt thành 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 truyền trên iframe và thực hiện lệnh gọi đến điểm cuối CreateAddOnAttachment. Xin 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ã thông số để lấy thông số đó ở dạng ban đầu. Ví dụ: JavaScript cung cấp hàm decodeURIComponent().

  6. Khi tạo thành công tệp đính kèm 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 từ 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ừ host_name+port tương ứng với URI ban đầu đã 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 miền+cổng với URI dùng để khởi chạy iframe, nếu không, thông báo sẽ bị bỏ qua. Một giải pháp là chuyển hướng lại đến một trang trên miền ban đầu chỉ gửi sự kiện postMessage.

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

Các biện pháp bảo vệ trên nhiều miền sẽ ngăn chặn việc này. Một giải pháp là tự xử lý giao tiếp giữa iframe và thẻ mới, đồng thời để iframe chịu trách nhiệm phát hành sự kiện đóng postMessage. Ngoài ra, chúng tôi sẽ xoá siêu liên kết "Mở trong Tên đối tác" để 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 sau đây về tính năng

  • 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 một iframe. Hãy tham khảo https://www.cookiestatus.com để biết trạng thái hiện tại của việc chặn cookie trên các trình duyệt. Tất nhiên, vấn đề này không chỉ xảy ra với các tiện ích bổ sung của Google Lớp học mà còn ảnh hưởng đến tất cả các trang web có 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.

Sau đây là một số giải pháp chung:

  • Mở một thẻ mới để tạo cookie trong ngữ 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 bối cảnh bên thứ nhất trong khi ở bối cảnh bên thứ ba.
  • 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 bạn cũng có thể làm được điều này với tất cả người dùng.
  • Thiết kế ứng dụng web một trang không dựa vào cookie.

Các phiên bản trình duyệt trong tương lai dự kiến sẽ có thêm nhiều quy định hạn chế về cookie. 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 người dùng tìm thấy 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 có đường liên kết đính kèm. Để khuyến khích việc sử dụng tiện ích bổ sung, bạn có thể chỉ định các 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. Khi đính kèm một đườ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, giáo viên sẽ thấy một hộp thoại có thể đóng được, 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ày 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 biểu thức chính quy thích hợp cho danh bạ của bạn trên Google. 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ì các biểu thức đó có thể được sửa đổi để hạn chế hoặc khác biệt hơn.

Giáo viên chọn tệp đính kèm đường liên kết Hình 1. Giáo viên chọn một tệp đính kèm là đường liên kết cho 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 đường liên kết từ một nguồn bên thứ ba. Giáo viên đã cài đặt tiện ích bổ sung của bên thứ ba cho Lớp học.

Hộp thoại khám phá biểu thức chính quy Hình 3. Hộp thoại tương tác được trình bày 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 do nhà phát triển bên thứ ba chỉ định.

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