iframe 和查詢參數詳細資料

系統會在 iframe 中載入 Classroom 外掛程式， 為使用者提供順暢便利的使用者體驗。這裡有四種 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 中設定這個 URI，並服務 > Google Workspace Marketplace SDK >「App Configuration」(應用程式設定) 頁面。

允許的附件 URI 前置字串可用來驗證 使用 *.addOnAttachments.create 和 AddOnAttachment *.addOnAttachments.patch 方法。驗證為常值字串前置字串 因此目前無法使用萬用字元。

查詢參數

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 當視窗小於 600 像素時，視窗寬度為 90% 寬 視窗寬度 80% (當視窗寬度) >600 像素寬

附件探索情境範例

1. 已在 Google Workspace 中註冊 Classroom 外掛程式 附件探索 URI 為 https://example.com/addon 的 Marketplace。
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% 視窗寬度減去側欄寬度<>側欄為 312 像素 展開時為 56 像素

注意： 老師可以為符合以下條件的學生開啟學生作業審查 iframe 使用者未查看外掛程式附件。在這種情況下，外掛程式可能會 還不知道這位學生，這時應該會顯示適當的訊息。

連結升級 iframe

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

連結升級情境示例

1. Classroom 外掛程式所註冊的連結升級 URI 為 https://example.com/upgrade。您已提供下列主機和路徑 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，請傳送 postMessage 酬載 {type: 'Classroom', action: 'closeIframe'} Classroom 只接受來自 host_name+port 的postMessage 與開啟的原始 URI 對應

<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 封鎖功能 登入工作階段。請參閱 https://www.cookiestatus.com 的 各瀏覽器封鎖 Cookie 目前的狀態當然 問題並不是 Google Classroom 外掛程式特有的問題，而且會影響到 iframe 第三方。我們的許多合作夥伴都碰過此問題。

部分一般解決方法如下：

• 開啟新分頁，在第一方情境中建立 Cookie。部分瀏覽器 授予存取在第一方情境下建立的 Cookie 以及第三方內容
• 要求使用者允許第三方 Cookie。系統有時可能無法執行這項作業 以及所有使用者
• 設計不需仰賴 Cookie 的單頁網頁應用程式。

未來的瀏覽器版本預計有更多 Cookie 限制。創作 功能要求，以便向 Google 提供意見，瞭解如何減少所需升幅 依合作夥伴分類

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

老師經常建立含有連結附件的作業。為了推廣使用 ，您就能指定比對資源網址的規則運算式 也能使用外掛程式老師附加與課程相符的連結 您的規則運算式看到可關閉的對話方塊，鼓勵他們嘗試 您的外掛程式。使用者必須安裝外掛程式， 他們的帳戶。

如果您想讓老師瞭解運作情形，請提供您的 Google 與適當規則運算式的聯絡人聯繫。如果規則運算式 過於廣泛或與其他附加元件相衝突 提高限製或明確性

圖 1.老師選取連結 附加至新作業。

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

圖 3.畫面上顯示的互動式對話方塊 即可將貼上的連結與 第三方開發人員。

如果老師選取「立即試用」如圖 3 所示 重新導向至外掛程式的附件探索 iframe。