老師要在 Classroom 中新增第三方內容的方法之一,就是在作業建立頁面中以「連結附件」的形式貼上連結。為了建立老師熟悉的應用,您現在可以設定外掛程式,讓老師將連結附件升級為外掛程式附件。
總覽
如果您是利用這項功能設定外掛程式,當老師在作業建立頁面中貼上連結附件時,系統會提示老師升級外掛程式附件的連結。系統只會提示已安裝外掛程式的老師。
一旦老師同意將連結升級為外掛程式附件,系統就會以下列查詢參數啟動連結升級 iframe:
courseId
itemId
itemType
addOnToken
urlToUpgrade
login_hint
(使用者必須已授權您的應用程式)
前四個查詢參數會反映在附件探索 iframe 上啟動的查詢參數。urlToUpgrade
是新的查詢參數,可協助您評估如何建立外掛程式連結。接著,您就可以使用其他查詢參數檢查使用者是否已登入,並根據 itemType
值呼叫 courseWork
、courseWorkMaterials
或 announcements
的 CreateAddOnAttachment
方法。您可以在 iframe 中顯示載入畫面,向老師說明外掛程式附件正在建立中。
建立外掛程式附件後,iframe 就會關閉,老師也可以照常查看作業中的附件。
技術實作詳情
本節重點介紹這項功能的部分重要技術細節。
讀取 urlToUpgrade
查詢參數
urlToUpgrade
查詢參數透過連結升級 iframe 傳送時,會經過 URI 編碼。您必須將網址解碼,以取得原始格式的網址。舉例來說,如果您使用 JavaScript,可以使用 decodeURIComponent()
函式來完成這項操作。
關閉連結升級 iframe
為確保這項功能提供最佳使用者體驗,請在外掛程式連結成功建立後傳送 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/
不符。
-
開發流程
傳送電子郵件至 classroom-link-upgrade-external@google.com,傳送測試或正式版外掛程式的連結升級 iframe 網址和網址模式。
您可以為任何代表 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:應在連結升級 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 協助登入 (如有需要) 或顯示載入指標。為確保最佳使用者體驗,在老師同意將貼上的連結升級至外掛程式附件後,不應提示他們提供額外資訊。不過,如果您的外掛程式無法執行此操作,您可以使用連結升級 iframe 收集所需的其他資訊。如果連結無法升級或發生錯誤時,也可以使用 iframe 通知老師。
附上適合使用者存取的錯誤訊息
如果老師貼上並升級無法存取的連結,請在 iframe 中顯示容易理解的錯誤訊息,讓老師知道這個問題。iframe 也可用來為老師提供存取內容的適當權限。