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

老師要新增第三方內容至 Classroom，有種方式是在作業建立頁面貼上連結做為連結附件。為了讓老師能繼續使用熟悉的操作方式，您現在可設定外掛程式，提示使用者將連結附件升級為外掛程式附件。

總覽

如果您為外掛程式設定這項功能，老師在作業建立頁面貼上連結附件時，系統會提示將連結升級為外掛程式附件。只有在老師已安裝外掛程式時，系統才會提示這樣做。

老師同意將連結升級為外掛程式附件後，系統會啟動 Link Upgrade 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 導入詳細資料頁面。

設定詳細資料

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

  • 連結 Link Upgrade 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，授予老師存取內容的適當權限。