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

Giáo viên có thể thêm nội dung của bên thứ ba vào Lớp học 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. Xây dựng dựa trên các tính năng mà giáo viên đã quen thuộc, giờ đây, bạn có thể định cấu hình tiện ích bổ sung của mình để 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 chứ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 chức năng này, giáo viên sẽ được nhắc nâng cấp một đường liên kết lên tệp đính kèm bằng tiện ích bổ sung khi họ dán một đường liên kết đính kèm vào trang tạo bài tập. Giáo viên chỉ được nhắc 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 tiện ích bổ sung đính kèm, Khởi chạy iframe nâng cấp bằng các tham số truy vấn sau:

  • courseId
  • itemId
  • itemType
  • addOnToken
  • urlToUpgrade
  • login_hint (chỉ khi người dùng đã cấp 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 của chế độ 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 bằng 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 hàm 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 tiện ích bổ sung đính kèm đang được tạo.

Sau khi tạo tệp đính kèm bằng tiện ích bổ sung, 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.

Chi tiết triển khai kỹ thuật

Phần này nêu bật một số chi tiết kỹ thuật quan trọng của 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 Đường liên kết Nâng cấp iframe. Bạn phải giải mã URL để có được URL ở dạng ban đầu. Nếu bạn đang sử dụng JavaScript, ví dụ: bạn có thể sử dụng decodeURIComponent() để làm điều đó.

Để đảm bảo người dùng có trải nghiệm tối ưu khi dùng tính năng này, hãy gửi postMessage một lần tệp đính kèm của tiện ích bổ sung đã được tạo thành công. Thao tác này sẽ đóng iframe. Xem trang chi tiết triển khai iframe để biết thêm chi tiết.

Chi tiết cấu hình

Bạn phải 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 dành cho iframe nâng cấp đường liên kết: Đây là URL mở ra 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à tìm cách 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 đường dẫn tiền tố.

    • 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, mọi URL khớp với máy chủ có thể nâng cấp.
    • Bạn chỉ có thể nâng cấp các URL có giao thức https.
    • Mẫu URL không được chứa localhost.
    • Tiền tố đường dẫn không được chứa các tham số truy vấn hoặc đoạn 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ủ thì không thể:
      • example.com là máy chủ lưu trữ hợp lệ, và /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ủ lưu trữ 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 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. Xem xét mẫu URL có máy chủ lưu trữ example.com 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 URL .
      • https://example.com/bar/123/baz/456/789 là kết quả phù hợp hợp lệ cho Mẫu URL.
      • https://example.com/bar/123/456/baz không phải là kết quả phù hợp hợp lệ cho Mẫu URL do ký tự đại diện trong tiền tố đường dẫn không khớp /123/456/.

Quá trình phát triển

Gửi URL iframe của Nâng cấp đường liên kết và các mẫu URL để kiểm thử hoặc phát hành công khai 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 bất kỳ dự án nào trên Google Cloud đại diện cho Tiện ích bổ sung dành cho Lớp học. Trước tiên, bạn nên cung cấp các cấu hình của một tiện ích bổ sung có chế độ hiển thị riêng tư để bạn có thể phát triển và thử nghiệm trong miền minh hoạ mà không ảnh hưởng đến người dùng đang hoạt động.

Bạn sẽ nhận được phản hồi cho email của mình khi cấu hình đã được bật. Lưu ý rằng các mẫu URL sử dụng localhost không được hỗ trợ cho việc này của chúng tôi.

Hãy định dạng email để bao gồm các 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ế đoạn mã sau:

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

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

Tránh làm thêm việc cho giáo viên

Bạn nên sử dụng iframe để tạo điều kiện đăng nhập, nếu bắt buộc hoặc hiển thị 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 bất kỳ thông tin nào sau khi đã đồng ý nâng cấp đường liên kết được dán thành tiện ích bổ sung đính kèm. Tuy nhiên, nếu đây là không thể cho tiện ích bổ sung, bạn có thể sử dụng iframe Nâng cấp liên kết để thu thập thông tin bổ sung mà bạn cần. iframe cũng có thể được dùng để thông báo nếu không thể nâng cấp đường liên kết hoặc nếu có lỗi xảy ra.

Gửi kèm các thông báo lỗi khi truy cập theo cách 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 được vấn đề này. iframe này cũng có thể được dùng để cung cấp cho giáo viên quyền truy cập vào nội dung.