Hiện tại, các nhà phát triển đã có thể sử dụng rộng rãi tiện ích bổ sung của Google Lớp học! Vui lòng xem tài liệu về tiện ích bổ sung để biết thêm thông tin.

Nâng cấp tệp đính kèm trong Link lên tiện ích bổ sung của Lớp học đính kèm

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à bằng cách dán một đường liên kết dưới dạng Tệp đính kèm đường liên kết trên trang tạo bài tập. Để tận dụng những nội dung mà 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 tiện ích bổ sung.

Tổng quan

Nếu bạn định cấu hình tiện ích bổ sung có tính năng này, thì khi giáo viên dán Tệp đính kèm đường liên kết trên trang tạo bài tập, hệ thống sẽ nhắc giáo viên nâng cấp đường liên kết thành tệp đính kèm tiện ích bổ sung. Hệ thống chỉ nhắc giáo viên làm như vậy nếu họ đã 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 tiện ích bổ sung, iframe Nâng cấp đường liên kết sẽ được khởi chạy với các tham số truy vấn sau:

courseId
itemId
itemType
addOnToken
urlToUpgrade
login_hint (chỉ khi người dùng đã uỷ quyền cho ứng dụng của bạn)

Bốn tham số truy vấn đầu tiên phản ánh các tham số truy vấn được khởi chạy trên iframe Khám phá tệp đính kèm. Tham số truy vấn urlToUpgrade là tham số mới và có thể giúp bạn đánh giá cách tạo tệp đính kèm 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àn hình tải để cho giáo viên biết rằng tệp đính kèm tiện ích bổ sung đang được tạo.

Sau khi tệp đính kèm 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 chi tiết về cách triển khai kỹ thuật

Phần này nêu bật một số thông tin chi tiết kỹ thuật quan trọng cho tính năng này.

Đọc tham số truy vấn `urlToUpgrade`

Tham số truy vấn urlToUpgrade được mã hoá URI khi được truyền trên iframe Nâng cấp đường liên kết. Bạn phải giải mã URL để lấy URL ở dạng ban đầu. Ví dụ: nếu đang sử dụng JavaScript, bạn có thể 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 mang lại trải nghiệm tối ưu cho người dùng đối với tính năng này, hãy gửi postMessage sau khi tệp đính kèm tiện ích bổ sung được tạo thành công. Thao tác này sẽ đóng iframe. Xem trang thông tin chi tiết về cách triển khai iframe để biết thêm thông tin.

Thông tin chi tiết về cấu hình

Bạn phải định cấu hình 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 cần 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ủ và nhiều tiền tố đường dẫn.
- Bạn có thể cung cấp nhiều mẫu URL.
- Nếu bạn không cung cấp tiền tố đường dẫn nào, thì mọi URL khớp với máy chủ đều có thể được nâng cấp.
- Chỉ những URL có lược đồ https mới có thể được nâng cấp.
- Các 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 đoạn URL.
- Tiền tố đường dẫn có thể hỗ trợ ký tự đại diện tại thời điểm này, nhưng máy chủ thì không:
  - example.com là một máy chủ 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ột máy chủ hợp lệ.
- Ký tự đại diện giữa các thành phần tiền tố đường dẫn chỉ khớp với một thành phần 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ó máy chủ example.com và tiền tố đường dẫn /bar/*/baz:
  - https://example.com/bar/123/baz là một kết quả khớp hợp lệ cho mẫu URL.
  - https://example.com/bar/123/baz/456/789 là một kết quả khớp hợp lệ cho mẫu URL.
  - https://example.com/bar/123/456/baz không phải là một 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/.

Quy trình phát triển

Gửi URL iframe Nâng cấp đường liên kết và các mẫu URL cho tiện ích bổ sung thử nghiệm hoặc sản xuất của bạn bằng cách gửi email đến classroom-link-upgrade-external@google.com.

Bạn có thể cung cấp cấu hình cho mọi dự án trên đám mây của Google Cloud đại diện cho một tiện ích bổ sung của Lớp học. Trước tiên, bạn nên cung cấp cấu hình cho một tiện ích bổ sung có chế độ hiển thị riêng tư để có thể phát triển và thử nghiệm trong một miền bản minh hoạ mà không ảnh hưởng đến người dùng thực.

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 tính năng này không hỗ trợ các mẫu URL sử dụng localhost.

Định dạng email để bao gồm những nội dung 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ế nội dung sau:

GCP_PROJECT_NUMBER: Số của dự án trên đám mây của Google Cloud mà tiện ích bổ sung được liên kết.
LINK_UPGRADE_IFRAME_URL: URL sẽ mở trong iframe Nâng cấp đường liên kết.
HOST_1: Một máy chủ mà Lớp học cần phát hiện. Chỉ hỗ trợ lược đồ https.
PATH_PREFIX_1 và PATH_PREFIX_2: Các tiền tố đường dẫn được liên kết với HOST_1 mà Lớp học cần phát hiện và cố gắng nâng cấp.
HOST_2: Một máy chủ mà Lớp học cần 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 được liên kết với HOST_2 mà Lớp học cần phát hiện và cố gắng nâng cấp.

Trải nghiệm người dùng được đề xuất

Sau đây là những đề xuất bạn nên cân nhắc khi triển khai tính năng này.

Tránh để giáo viên phải làm thêm việc

Bạn nên sử dụng iframe để tạo điều kiện đăng nhập (nếu cần) hoặc hiển thị chỉ báo tải. Để mang lại trải nghiệm tốt nhất cho người dùng, giáo viên không nên được nhắc cung cấp thêm thông tin nào sau khi họ đồng ý nâng cấp đường liên kết đã dán thành tệp đính kèm tiện ích bổ sung. Tuy nhiên, nếu không thể thực hiện việc này cho tiện ích bổ sung của bạn, thì bạn có thể sử dụng iframe Nâng cấp đường liên kết để thu thập thêm thông tin cần thiết. Bạn cũng có thể sử dụng iframe để 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.

Đưa vào thông báo lỗi 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 hiển thị thông báo lỗi thân thiện với người dùng trong iframe để giáo viên biết về vấn đề này. Bạn cũng có thể sử dụng iframe để cấp cho giáo viên các quyền phù hợp nhằm truy cập vào nội dung.