iframe 和查詢參數詳細資料

Classroom 外掛程式會在 iframe 中載入，為使用者提供流暢便利的使用體驗。共有五種不同的 iframe 類型；如要瞭解各個 iframe 的用途和外觀，請參閱「User journeys」目錄中的 iframe 頁面。

重點： 使用者開啟其中一個外掛程式檢視畫面時，您會收到各種資訊。使用這項資訊識別附件、驗證使用者的憑證和角色，以及執行特定 API 要求。

iframe 安全性指南

開發人員應遵循業界最佳做法，確保 iframe 安全無虞。不過，您也應在使用者流程中加入特定 API 互動，確認您擁有有效憑證，且能正確識別使用者在課程中的角色。

伺服器應用程式設定

為保護 iframe，建議您進行下列伺服器設定：

• 必須使用 HTTPS。強烈建議使用 TLS 1.2 以上版本，並啟用 HTTP 嚴格傳輸安全性 (HSTS)。請參閱這篇相關的 MDN 文章，瞭解嚴格傳輸安全性。
• 啟用嚴格內容安全政策 (嚴格 CSP)。請參閱這篇 OWASP 文章 和這篇相關的 Content Security Policy MDN 文章。
• 啟用安全 Cookie 屬性。請參閱「HttpOnly 屬性」和這篇相關的 Cookies MDN 文章。

查詢參數

iframe 會以查詢參數的形式，將重要資訊傳遞至外掛程式。 參數分為兩類：附件相關參數和登入相關參數。

附件相關參數

外掛程式可透過附件相關參數，取得課程、作業、外掛程式附件、學生提交內容和授權權杖的相關資訊。

課程 ID

courseId 值是課程的 ID。

所有 iframe 皆包含這項屬性。

項目 ID

itemId 值是這個附件所附加的 Announcement、CourseWork 或 CourseWorkMaterial 的 ID。

所有 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。
高度	視窗高度的 80% 減去頂端標題的 60 像素
寬度	最大 1600 像素 視窗寬度小於或等於 600 像素時，圖片寬度為視窗寬度的 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。

teacherViewUri 和 studentViewUri iframe

維度	說明
必填	是
URI	teacherViewUri 或 studentViewUri
查詢參數	courseId、itemId、itemType、attachmentId 和 login_hint。
高度	視窗高度的 100% 減去頂端標題的 140 像素
寬度	100% 視窗寬度

studentWorkReviewUri iframe

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

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

連結升級 iframe

維度	說明
必要	可以，前提是外掛程式支援將連結升級為外掛程式附件。
URI	在外掛程式中繼資料中提供
查詢參數	courseId、itemId、itemType、addOnToken、urlToUpgrade 和 login_hint。
高度	視窗高度的 80% 減去頂端標題的 60 像素
寬度	最大 1600 像素 視窗寬度小於或等於 600 像素時，圖片寬度為視窗寬度的 90% 視窗寬度大於 600 像素時，圖片寬度為視窗寬度的 80%

連結升級情境範例

1. Classroom 外掛程式已註冊，且連結升級 URI 為 https://example.com/upgrade。您已為 Classroom 提供下列連結附件的主機和路徑前置字元模式，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 端點。請注意，在 iframe 上傳遞 urlToUpgrade 查詢參數時，系統會對該參數進行 URI 編碼。您需要解碼參數，才能取得原始形式。舉例來說，JavaScript 提供 decodeURIComponent() 函式。

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

關閉 iframe

從學習工具傳送含有酬載 {type: 'Classroom', action: 'closeIframe'} 的 postMessage，即可關閉 iframe。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 關閉 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。