將連結連結至 Classroom 外掛程式附件

老師可以在建立作業的頁面中，將連結貼上為連結附件，藉此將第三方內容加入 Classroom。為讓教師能運用熟悉的功能，您現在可以設定外掛程式，讓教師將連結附件升級為外掛程式附件。

總覽

如果您將這項功能納入外掛程式設定，當老師在作業建立頁面中貼上連結附件時，系統就會提示他們將連結升級為外掛程式附件。只有已安裝外掛程式的老師，才會收到安裝提示。

老師同意將連結升級為外掛程式附件後，系統會啟動連結升級 iframe，並傳送以下查詢參數：

  • courseId
  • itemId
  • itemType
  • addOnToken
  • urlToUpgrade
  • login_hint (僅限使用者已授權給您的應用程式)

前四個查詢參數會反映附件探索 iframe 上啟動的查詢參數。urlToUpgrade 查詢參數是新功能，可協助您評估如何建立外掛程式附件。接著，您可以使用其他查詢參數來檢查使用者是否已登入，並根據 itemType 值呼叫 courseWork、courseWorkMaterials 或 announcements 的 CreateAddOnAttachment 方法。您可以在 iframe 中顯示載入畫面，向老師指出附件外掛程式正在建立中。

建立外掛程式附件後，iframe 就會關閉，老師就能照常查看作業中的附件。

技術實作詳細資料

本節將說明這項功能的幾項重要技術細節。

讀取 urlToUpgrade 查詢參數

urlToUpgrade 查詢參數在傳遞至 Link Upgrade iframe 時會經過 URI 編碼。您必須解碼網址，才能取得原始網址。舉例來說，如果您使用 JavaScript，可以使用 decodeURIComponent() 函式執行這項操作。

為確保這項功能提供最佳使用者體驗，請在成功建立外掛程式附件後傳送 postMessage。這麼做會關閉 iframe。詳情請參閱 iframe 實作詳細資訊頁面。

設定詳細資料

如要將這項功能整合至外掛程式，必須進行下列設定：

  • 連結升級 iframe 的網址：這是在老師同意升級時，在 iframe 中開啟的網址。

  • Classroom 應偵測並嘗試升級的網址模式：網址模式可包含主機和多個路徑前置字串。

    • 您可以提供多個網址模式。
    • 如果您未提供任何路徑前置字串，則任何與主機相符的網址都可以升級。
    • 只有採用 https 配置的網址才能升級。
    • 網址模式不得包含 localhost。
    • 路徑前置字串不得包含查詢參數或網址片段。
    • 路徑前置字元目前支援萬用字元，但主機不支援：
      • example.com 是有效主機，/foo 和 /bar/*/baz 則是有效路徑前置字串。
      • example.*.host.com 不是有效的主機。
    • 路徑前置字元元件之間的萬用字元只會比對單一元件，不會比對以斜線分隔的多個元件。請考慮含有主機 example.com 和路徑前置字元 /bar/*/baz 的網址模式：
      • https://example.com/bar/123/baz 是網址模式的有效比對項目。
      • https://example.com/bar/123/baz/456/789 是網址模式的有效比對項目。
      • https://example.com/bar/123/456/baz 與網址模式不符，因為路徑前置字串中的萬用字元與 /123/456/ 不符。

開發流程

請傳送 Link Upgrade iframe 網址和測試或正式版外掛程式的網址模式，寄到 classroom-link-upgrade-external@google.com。

您可以為任何代表 Classroom 外掛程式的 Google Cloud 專案提供設定。建議您先為附加元件提供私人瀏覽權限的設定，這樣您就能在示範網域中進行開發和測試，而不影響實際使用者。

啟用設定後，我們會回覆您的電子郵件。請注意，這項功能不支援使用 localhost 的網址模式。

請按照下列格式撰寫電子郵件：

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

更改下列內容：

  • GCP_PROJECT_NUMBER：加購項目所關聯的 Google Cloud 專案編號。
  • LINK_UPGRADE_IFRAME_URL：應在 Link Upgrade iframe 中開啟的網址。
  • HOST_1：Classroom 應偵測的主機。僅支援 https 配置。
  • PATH_PREFIX_1 和 PATH_PREFIX_2：與 HOST_1 相關聯的路徑前置字串，Classroom 應偵測並嘗試升級。
  • HOST_2：Classroom 應偵測的主機。僅支援 https 配置。
  • PATH_PREFIX_3 和 PATH_PREFIX_4：與 HOST_2 相關聯的路徑前置字串，Classroom 應偵測並嘗試升級。

以下是實作這項功能時的建議。

避免教師額外負擔工作

強烈建議您使用 iframe 來協助登入 (如有需要)，或顯示載入指標。為了提供最佳使用者體驗，老師同意將貼上的連結升級為外掛程式附件後，系統不應再提示他們提供其他資訊。不過，如果無法在外掛程式中執行這項操作，您可以使用 Link Upgrade iframe 收集所需的其他資訊。如果無法升級連結或發生錯誤，您也可以使用 iframe 通知老師。

加入使用者友善的存取錯誤訊息

如果老師貼上無法存取的連結並升級，請在 iframe 中顯示友善的錯誤訊息，讓老師瞭解問題。iframe 也可以用來為老師提供存取內容的適當權限。