Một cách để giáo viên thêm nội dung của bên thứ ba vào Lớp học là dán đường liên kết dưới dạng Tệp đính kèm của đường liên kết trên trang tạo bài tập. Để xây dựng dựa trên những gì giáo viên đã quen thuộc, giờ đây, bạn có thể định cấu hình tiện ích bổ sung để cho phép giáo viên nâng cấp tệp đính kèm Đường liên kết thành tệp đính kèm của tiện ích bổ sung.
Tổng quan
Nếu bạn định cấu hình tiện ích bổ sung bằng tính năng này, 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 khi họ dán tệp đính kèm Đường liên kết vào trang tạo bài tập. Giáo viên chỉ được nhắc thực hiện thao tác này nếu đã cài đặt tiện ích bổ sung.
Sau khi giáo viên đồng ý nâng cấp đường liên kết thành tệp đính kèm của tiện ích bổ sung, iframe Liên kết nâng cấp sẽ được chạy với các tham số truy vấn sau:
courseId
itemId
(đã đổi tên từpostId
)itemType
(mới!)addOnToken
login_hint
hoặchd
urlToUpgrade
(mới!)
Bốn tham số truy vấn đầu tiên phản ánh các tham số truy vấn đã khởi chạy trên iframe Khám phá tệp đính kèm. Tham số truy vấn urlToUpgrade
là mới và có thể giúp bạn đánh giá cách tạo tệp đính kèm của tiện ích bổ sung. Sau đó, bạn có thể sử dụng các tham số truy vấn khác để kiểm tra xem người dùng đã đăng nhập hay chưa và gọi phương thức CreateAddOnAttachment
của courseWork
, courseWorkMaterials
hoặc announcements
dựa trên giá trị itemType
. Trong iframe, bạn có thể hiển thị một màn hình tải để cho giáo viên biết rằng tệp đính kèm của tiện ích bổ sung đang được tạo.
Sau khi tệp đính kèm của tiện ích bổ sung được tạo, iframe sẽ đóng và giáo viên có thể xem tệp đính kèm trong bài tập như bình thường.
Thông tin kỹ thuật triển khai
Phần này nêu bật một số chi tiết kỹ thuật quan trọng cho tính năng.
Đọc tham số truy vấn urlToUpgrade
Tham số truy vấn urlToUpgrade
được mã hoá URI khi được truyền vào iframe Liên kết nâng cấp. Bạn phải giải mã URL để có được URL ở dạng ban đầu. Chẳng hạn nếu đang sử dụng JavaScript, bạn có thể sử dụng hàm decodeURIComponent()
để thực hiện việc này.
Đóng iframe Nâng cấp đường liên kết
Để đảm bảo người dùng có trải nghiệm tối ưu cho tính năng này, hãy gửi postMessage
sau khi đã tạo thành công tệp đính kèm của tiện ích bổ sung. Thao tác này sẽ đóng iframe. Hãy xem trang chi tiết về cách triển khai iframe để biết thêm thông tin.
Chi tiết cấu hình
Bạn cần có các cấu hình sau để tích hợp tính năng này vào tiện ích bổ sung:
URL cho iframe nâng cấp đường liên kết: Đây là URL mở trong iframe khi giáo viên đồng ý nâng cấp.
Các mẫu URL mà Lớp học sẽ phát hiện và cố gắng nâng cấp: Các mẫu URL có thể bao gồm một máy chủ lưu trữ và nhiều tiền tố đường dẫn.
- Bạn có thể cung cấp nhiều mẫu URL.
- Nếu không cung cấp tiền tố đường dẫn nào, bạn có thể nâng cấp mọi URL khớp với máy chủ lưu trữ.
- Bạn chỉ có thể nâng cấp các URL có lược đồ
https
. - Mẫu URL không được chứa
localhost
. - Tiền tố đường dẫn không được chứa tham số truy vấn hoặc mảnh URL.
- Hiện tại, tiền tố đường dẫn có thể hỗ trợ ký tự đại diện, nhưng máy chủ lưu trữ thì không:
-
example.com
là máy chủ lưu trữ hợp lệ, còn/foo
và/bar/*/baz
là các tiền tố đường dẫn hợp lệ. -
example.*.host.com
không phải là máy chủ hợp lệ.
-
- Ký tự đại diện giữa các thành phần trong tiền tố đường dẫn chỉ khớp với một thành phần duy nhất và không khớp với nhiều thành phần được phân tách bằng dấu gạch chéo.
Hãy xem xét một mẫu URL có
example.com
máy chủ lưu trữ và tiền tố đường dẫn/bar/*/baz
:-
https://example.com/bar/123/baz
là kết quả phù hợp hợp lệ cho mẫu URL. -
https://example.com/bar/123/baz/456/789
là kết quả khớp hợp lệ cho mẫu URL. -
https://example.com/bar/123/456/baz
không phải là kết quả khớp hợp lệ cho mẫu URL vì ký tự đại diện trong tiền tố đường dẫn không khớp với/123/456/
.
-
Quá trình phát triển
Gửi URL iframe của bản nâng cấp Link Upgrade và các mẫu URL cho tiện ích bổ sung thử nghiệm hoặc chính thức của bạn bằng cách gửi email đến địa chỉ classroom-link-upgrade-external@google.com.
Trước tiên, bạn có thể cung cấp cấu hình cho tiện ích bổ sung riêng tư của mình và bất kỳ môi trường kiểm thử hoặc phát triển nào mà bạn sở hữu. Nhóm Lớp học có thể bật các cấu hình kiểm thử này trước khi bật cấu hình phát hành chính thức để bạn có thể kiểm thử quy trình trong miền minh hoạ của mình. Bạn sẽ nhận được email phản hồi khi các cấu hình đã được bật. Xin lưu ý rằng những mẫu URL sử dụng localhost
không được hỗ trợ cho tính năng này.
Định dạng email để cung cấp những thông tin sau:
Google Cloud Project number: GCP_PROJECT_NUMBER
Link Upgrade iframe URL: LINK_UPGRADE_IFRAME_URL
URL Patterns:
- Host:HOST_1
- Path prefixes:
- PATH_PREFIX_1
- PATH_PREFIX_2
- Host:HOST_2
- Path prefixes:
- PATH_PREFIX_3
- PATH_PREFIX_4
// add more hosts and path prefixes as needed
Thay thế các đoạn mã sau:
- GCP_PROJECT_NUMBER: số dự án Google Cloud liên kết với tiện ích bổ sung.
- LINK_UPGRADE_IFRAME_URL URL sẽ mở trong iframe Nâng cấp liên kết.
- HOST_1: một máy chủ mà Lớp học sẽ phát hiện.
Chỉ hỗ trợ lược đồ
https
. - PATH_PREFIX_1 và PATH_PREFIX_2: tiền tố đường dẫn liên kết với
HOST_1
mà Lớp học sẽ phát hiện và tìm cách nâng cấp. - HOST_2: một máy chủ mà Lớp học sẽ phát hiện.
Chỉ hỗ trợ lược đồ
https
. - PATH_PREFIX_3 và PATH_PREFIX_4:
các tiền tố đường dẫn liên kết với
HOST_2
mà Lớp học sẽ phát hiện và tìm cách nâng cấp.
Trải nghiệm người dùng được đề xuất
Sau đây là các đề xuất cần cân nhắc khi triển khai tính năng này.
Tránh làm thêm cho giáo viên
Bạn nên sử dụng iframe để hỗ trợ việc đăng nhập (nếu bắt buộc) hoặc để hiện chỉ báo đang tải. Để có trải nghiệm người dùng tốt nhất, giáo viên không nên được nhắc cung cấp thêm thông tin sau khi đồng ý nâng cấp đường liên kết đã dán thành một tệp đính kèm của tiện ích bổ sung. Tuy nhiên, nếu không thể thực hiện việc này đối với tiện ích bổ sung của bạn, bạn có thể sử dụng iframe Nâng cấp liên kết để thu thập thêm thông tin mà bạn cần. Bạn cũng có thể dùng iframe này để thông báo cho giáo viên nếu không thể nâng cấp đường liên kết hoặc nếu đã xảy ra lỗi.
Bao gồm thông báo lỗi về quyền truy cập thân thiện với người dùng
Nếu giáo viên dán và nâng cấp một đường liên kết mà họ không có quyền truy cập, hãy cho thấy thông báo lỗi về nội dung thân thiện với người dùng trong iframe để giáo viên biết được vấn đề. Bạn cũng có thể dùng iframe để cấp cho giáo viên quyền thích hợp để truy cập vào nội dung.