Các tiện ích bổ sung của Google Lớp học được tải trong iframe để cung cấp cho người dùng cuối một 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 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:
HTTPS là bắt buộc. Bạn nên sử dụng TLS 1.2 trở lên và bật Bảo mật truyền tải nghiêm ngặt HTTP. Xem bài viết MDN liên quan này về Bảo mật truyền tải nghiêm ngặt.
Bật Chính sách bảo mật nội dung nghiêm ngặt. Vui lòng xem bài viết OWASP và bài viết về MDN trong Chính sách bảo mật nội dung có liên quan này.
Bật Thuộc tính cookie an toàn. Xem thuộc tính httpOnly và bài viết về cookie MDN liên quan này.
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 tệp đính kèm bằng tiện ích bổ sung trên bài đăng trong 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. Hãy đặt URI này trong trang API và dịch vụ của dự án trên Google Cloud > SDK trên Google Workspace Marketplace > trang Cấu hình ứng dụng.
Tiền tố URI tệp đí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à so khớp với tiền tố của chuỗi ký tự và hiện không cho phép sử dụng ký tự đại diện.
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ó 2 loại tham số: tham số liên quan đến tệp đính kèm và tham số liên quan đến đăng nhập.
Tham số liên quan đến tệp đính kèm
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 học viên đã nộp và một mã thông báo cấp phép.
- 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ủaAnnouncement
,CourseWork
hoặcCourseWorkMaterial
mà 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ứatệp đính kèm. Giá trị chuỗi đã truyền là một trong các giá trị
"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 các iframe
teacherViewUri
,studentViewUri
vàstudentWorkReviewUri
.- 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 bạn nên dùng kết hợp vớiattachmentId
để xác định bài tập của một bài tập cụ thể.Đ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ạoaddOnAttachments.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à iframe nâng cấp liên kết.
- URL cần nâng cấp
Sự hiện diện của giá trị
urlToUpgrade
ngụ ý rằnggiáo viên đã đính kè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 đó lên tệp đính kèm 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 thành tệp đính kèm tiện ích bổ sung để biết thêm thông tin.
Đi kèm với iframe khi nâng cấp liên kết.
Các thông số liên quan đến việc đăng nhập
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 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 trước đây đã sử dụng tiện ích bổ sung của bạn để giúp 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ùngTà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
:- 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 xuất hiện. Người dùng không được tự động đăng nhập. - Sau khi người dùng đăng nhập, hãy sử dụng thông số này để so sánh giá trị này 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 tìm thấy kết quả trùng khớ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 tham số này không khớp với bất kỳ người dùng đã đăng nhập nào của bạn, hãy nhắc người dùng đó đăng nhập bằng nút đăng nhập mang thương hiệu Google.
Được bao gồm trong tất cả các iframe.
- Truyền giá trị
iframe của tính năng 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 , 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 Chiều rộng cửa sổ 90% 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
- Một tiện ích bổ sung dành cho Lớp học được đăng ký trong Google Workspace Marketplace với URI Khám phá tệp đính kèm là
https://example.com/addon
. - 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 khoá học của họ. Ví dụ:
itemId=234
,itemType=courseWork
vàcourseId=123
. - 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.
- 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
.- Giáo viên thực hiện công việc trong iframe để lựa chọn tệp đính kèm.
- Khi lựa chọn tệp đính kèm, tiện ích bổ sung này sẽ gửi
postMessage
đến Lớp học để đóng iframe.
Các iframe EducationViewUri và customerViewUri
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 , 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 | 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 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 được mở rộng và 56px khi thu gọn |
iframe của đường liên kết Nâng cấp
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ợ việc nâng cấp đường liên kết thành tệp đính kèm bằng 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 | 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 Chiều rộng cửa sổ 90% 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 nâng cấp đường liên kết
- 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 đường liên kết mà Lớp học sẽ tìm cách nâng cấp lên tệp đính kèm tiện ích bổ sung:- Máy chủ lưu trữ là
example.com
và tiền tố đường dẫn là/quiz
.
- Máy chủ lưu trữ là
- 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 các khoá học của họ. Ví dụ:
itemId=234
,itemType=courseWork
vàcourseId=123
. - Giáo viên sẽ 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 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ó tiện ích bổ sung. 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
.Bạn sẽ đá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ấnurlToUpgrade
được mã hoá URI khi được chuyển trên iframe. Bạn cần giải mã thông số này để có được thông số đó ở dạng ban đầu. Ví dụ: JavaScript cung cấp hàmdecodeURIComponent()
.Khi tạo thành công tệp đính kèm bằng tiện ích bổ sung qua 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 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
Cổng miền+của trang gửi sự kiện postMessage
phải có cùng cổng+miền với cổng URI dùng để chạy iframe, nếu không, thông báo sẽ bị bỏ qua. Để khắc phục, hãy chuyển hướng trở lại một trang trên miền ban đầu. Việc này không làm gì hơn ngoài việc 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. Cách giải quyết là tự xử lý
hoạt động giao tiếp giữa iframe và thẻ mới, đồng thời để iframe cuối cùng
chịu trách nhiệm đưa ra sự kiện đóng postMessage
. Ngoài ra, xin lưu ý thêm rằng siêu liên kết "Mở trong 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.
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 *"
Chặn cookie của bên thứ ba
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ì phiên đăng nhập trong iframe. 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ỉ ảnh hưởng đến các tiện ích bổ sung của Google Lớp học mà còn ảnh hưởng đến mọi trang web sử dụng iframe của các 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 của bên thứ nhất khi ở trong 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 có thể 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. 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 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 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 trong tiện ích bổ sung của mình. Một giáo viên 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 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 danh bạ Google của bạn các biểu thức chính quy thích hợp. Nếu các 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ể bị sửa đổi để bị hạn chế hoặc khác biệt hơn.
Hình 1. Giáo viên chọn một đường liên kết đính kèm vào bài tập mới.
Hình 2. Giáo viên sẽ dán một đường liên kết từ một nguồn của 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ình 3. Hộp thoại tương tác được hiển thị cho giáo viên khi đường liên kết được dán khớp với 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, thì giáo viên sẽ được chuyển hướng đến iframe của tính năng Khám phá tệp đính kèm trong tiện ích bổ sung của bạn.