iframe 和查詢參數詳細資料

Classroom 外掛程式會在 iframe 中載入，為使用者提供流暢便利的使用者體驗。iframe 類型共有四種，請參閱「使用者歷程」目錄中的 iframe 頁面，以瞭解每個 iframe 的用途和外觀。

iframe 安全性指南

合作夥伴必須遵循業界最佳做法，確保 iframe 安全無虞。 為保護 iframe，我們的安全團隊建議採取下列做法：

• 必須使用 HTTPS。強烈建議您使用 TLS 1.2 以上版本，並啟用 HTTP 嚴格傳輸安全性。請參閱這篇有關嚴格傳輸安全性的 MDN 文章。

• 啟用「嚴格內容安全政策」。請參閱這篇 OWASP 文章和這篇內容安全政策 MDN 文章。

• 啟用安全 Cookie 屬性。請參閱 HttpOnly 屬性和這篇 Cookie MDN 文章。

iframe URI 設定

「附件設定 URI」是附件探索 iframe 載入的內容，也是老師在 Classroom 貼文中建立外掛程式附件的流程。你可以在 Google Cloud 專案控制台中設定這項設定。 在 Google Cloud 專案的「API 和服務」>「Google Workspace Marketplace SDK」>「應用程式設定」頁面設定這個 URI。

允許的附件 URI 前置字串會透過 *.addOnAttachments.create 和 *.addOnAttachments.patch 方法，驗證在 AddOnAttachment 中設定的 URI。驗證是常值字串前置字串比對，目前不允許使用萬用字元。

查詢參數

iframe 會將重要資訊以查詢參數的形式傳送至外掛程式。參數有兩種：附件相關與登入相關參數。

附件相關參數

附件相關參數可為外掛程式提供課程、作業、外掛程式附件、學生提交內容及授權權杖等相關資訊。

課程 ID

courseId 值是課程的 ID。

包含所有 iframe。

項目 ID

itemId 值是 Announcement 的 ID。

CourseWork 或附加此連結的 CourseWorkMaterial。

包含所有 iframe。

項目類型

itemType 值代表要在哪種資源類型上

已附加附件。傳遞的字串值會是 "announcements"、"courseWork" 或 "courseWorkMaterials" 其中之一。

包含所有 iframe。

附件 ID

attachmentId 值是附件的 ID。

包含在 teacherViewUri、studentViewUri 和 studentWorkReviewUri iframe 中。

提交內容 ID

submissionId 值是學生作業的 ID，但應與 attachmentId 搭配使用，以便識別特定作業的學生作業。

包含在 studentWorkReviewUri 中。

注意： 在可供不同課程的相同附件指派給同一學生的情況下，您可以使用 submissionId 和 attachmentId 的複合鍵來識別學生的作業。詳情請參閱「複製的內容」。

外掛程式權杖

addOnToken 值是

addOnAttachments.create 呼叫，以便建立外掛程式。

包含在附件探索 iframe 和連結升級 iframe 中。

要升級的網址

出現 urlToUpgrade 值表示

老師在作業中加入連結附件，並同意將附件升級為外掛程式附件。如果您尚未設定此功能，請參閱升級外掛程式連結的連結指南，瞭解更多資訊。

隨附於連結升級 iframe。

登入相關參數

login_hint 查詢參數可提供造訪外掛程式網頁的 Classroom 使用者相關資訊。這個查詢參數是在 iframe src 網址提供。如果使用者先前使用過您的外掛程式，系統就會傳送此憑證，以協助減少使用者的登入問題。您必須在外掛程式實作中處理這個查詢參數。

登入提示

login_hint 是使用者的 Google 專屬 ID

。使用者首次登入外掛程式後，每次造訪同一個外掛程式時，系統都會將 login_hint 參數傳遞給同一個使用者。

login_hint 參數有兩個可能的用途：

1. 在驗證流程期間傳遞 login_hint 值，這樣使用者在顯示登入對話方塊時，就不必輸入憑證。使用者不會自動登入。
2. 使用者登入後，使用這個參數將值與您可能已登入外掛程式的任何使用者進行比較。如果找到相符項目，可以讓使用者保持登入狀態，避免顯示登入流程。如果該參數與任何已登入的使用者均不相符，請使用 Google 品牌登入按鈕提示使用者登入。

包含所有 iframe。

注意： 如需有關實作 login_hint 參數和登入流程的更多資訊，請參閱 SSO、簡易登入功能和處理重複登入的逐步操作說明頁面。

附件探索 iframe

維度	說明
需要	可
URI	透過外掛程式中繼資料提供
查詢參數	courseId、itemId、itemType、addOnToken 和 login_hint。
身高	頂端標頭的視窗高度減 60 像素
寬度	最大為 1600px 當視窗寬度 <= 600px 時，視窗寬度為 90% 當視窗寬度大於 600 像素時，視窗寬度為 80%

附件探索情境範例

1. Classroom 外掛程式已在 Google Workspace Marketplace 中註冊，附件探索 URI 為 https://example.com/addon。
2. 老師安裝這個外掛程式，並在其中一個課程中建立新的公告、作業或教材。例如 itemId=234、itemType=courseWork 和 courseId=123。
3. 設定該項目時，老師會選擇新安裝的外掛程式做為附件。
4. Classroom 會建立 iframe，並將 src 網址設為 https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456。
   1. 老師會在 iframe 中工作，選取附件。
5. 選取附件後，外掛程式會將 postMessage 傳送至 Classroom 以關閉 iframe。

adminViewUri 和 StudentViewUri iframe

維度	說明
需要	可
URI	teacherViewUri 或 studentViewUri
查詢參數	courseId、itemId、itemType、attachmentId 和 login_hint。
身高	頂端標頭的視窗高度減 140 像素
寬度	視窗寬度 100%

學生 WorkReviewUri iframe

維度	說明
需要	否 (判斷這是活動類型的附件)
URI	studentWorkReviewUri
查詢參數	courseId、itemId、itemType、attachmentId、submissionId 和 login_hint。
身高	頂端標頭的視窗高度減 168 像素
寬度	100% 的視窗寬度減去側欄寬度<> 側欄展開時為 312px，收合時為 56px

注意： 老師可以為先前未查看外掛程式附件的學生開啟學生作業審查 iframe。在這種情況下，外掛程式可能尚未註意到這個學生，因此應顯示適當的訊息。

連結升級 iframe

維度	說明
必要	可以，如果您的外掛程式支援升級外掛程式附件的連結，
URI	透過外掛程式中繼資料提供
查詢參數	courseId、itemId、itemType、addOnToken、urlToUpgrade 和 login_hint。
身高	頂端標頭的視窗高度減 60 像素
寬度	最大為 1600px 當視窗寬度 <= 600px 時，視窗寬度為 90% 當視窗寬度大於 600 像素時，視窗寬度為 80%

連結升級情境示例

1. Classroom 外掛程式是透過 https://example.com/upgrade 的連結升級 URI 註冊。您為連結附件提供了以下主機和路徑前置字串模式，Classroom 應嘗試升級為外掛程式附件：
   • 主機為 example.com，路徑前置字串為 /quiz。
2. 老師在其中一個課程中建立新的公告、作業或教材。例如 itemId=234、itemType=courseWork 和 courseId=123。
3. 老師在 [連結連結] 對話方塊中貼上與您提供的網址模式相符的連結 https://example.com/quiz/5678，隨後，系統會提示老師將連結升級為外掛程式附件。

4. Classroom 會啟動連結升級 iframe，並將網址設為 https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678。

5. 您可以評估在 iframe 上傳遞的查詢參數，並呼叫 CreateAddOnAttachment 端點。請注意，urlToUpgrade 查詢參數在傳遞至 iframe 時會經過 URI 編碼。您必須解碼參數，才能取得原始格式。例如，JavaScript 提供 decodeURIComponent() 函式。

6. 成功透過連結建立外掛程式附件後，請傳送 postMessage 至 Classroom 來關閉 iframe。

關閉 iframe

如要在學習工具中關閉 iframe，請傳送含有酬載 {type: 'Classroom', action: 'closeIframe'} 的 postMessage。Classroom 只接受與開啟的原始 URI 相對應的 host_name+port 此 postMessage。

<button id="close">Send message to close iframe</button>
<script>
  document.querySelector('#close')
    .addEventListener('click', () => {
        window.parent.postMessage({
            type: 'Classroom',
            action: 'closeIframe',
        }, '*');
    });
</script>

關閉 iframe

傳送 postMessage 事件的頁面網域 + 通訊埠，必須與用於啟動 iframe 的 URI 網域+通訊埠相同，否則系統會忽略訊息。解決方法是重新導向至原始網域上，其中僅傳送 postMessage 事件的網頁。

從新分頁關閉 iframe

跨網域保護措施會使這項功能無法運作。解決方法是自行處理 iframe 和新分頁之間的通訊，並讓 iframe 最終負責發出關閉的 postMessage 事件。另外也請注意，我們將移除「在合作夥伴名稱中開啟」超連結，因此使用者不久後便無法以這種方式建立分頁。

限制

所有 iframe 都會透過以下沙箱屬性開啟：

• allow-popups
• allow-popups-to-escape-sandbox
• allow-forms
• allow-scripts
• allow-storage-access-by-user-activation
• allow-same-origin

和下列功能政策

• allow="microphone *"

第三方 Cookie 封鎖功能

請注意，第三方 Cookie 封鎖功能會讓使用者難以在 iframe 中維護已登入的工作階段。如要瞭解不同瀏覽器封鎖 Cookie 的目前狀態，請參閱 https://www.cookiestatus.com。當然，這個問題不是 Google Classroom 外掛程式特有的問題，且會影響使用 iframe 第三方的所有網站。我們的許多合作夥伴都碰過此問題。

部分一般解決方法如下：

• 開啟新分頁，在第一方情境中建立 Cookie。有些瀏覽器會授權存取在第三方情境下建立的 Cookie。
• 要求使用者允許第三方 Cookie。並非所有使用者都能做到這點
• 設計不需仰賴 Cookie 的單頁網頁應用程式。

未來的瀏覽器版本預計有更多 Cookie 限制。建立功能要求，向 Google 提供意見回饋，瞭解如何減少合作夥伴要求的升幅。

允許透過網址規則運算式搜尋外掛程式

老師經常建立含有連結附件的作業。如要提升外掛程式的使用效率，您可以指定規則運算式，比對外掛程式中可存取的資源網址。老師在附加與任一規則運算式相符的連結時，會看到可關閉的對話方塊，鼓勵他們試用您的外掛程式。只有帳戶已安裝外掛程式的情況下，使用者才會看到對話方塊。

如果您想提供老師這種行為，請為您的 Google 聯絡人提供適當的規則運算式。如果您提供的規則運算式過於廣泛或與其他外掛程式相衝突，則系統可能會加以修改，使其更加受限或有所區別。

圖 1.老師選取了新作業的連結附件

圖 2.老師貼上第三方來源的連結。老師已安裝第三方的 Classroom 外掛程式。

圖 3.貼上的連結與第三方開發人員指定的規則運算式相符時，會向老師顯示互動式對話方塊。

如果老師在圖 3 所示的彈出式視窗中選取「立即試用」，系統會將他們重新導向至外掛程式的「附件探索 iframe」。