iframe 和查詢參數詳細資料

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

iframe 安全性指南

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

伺服器應用程式設定

為保護 iframe，建議採用下列伺服器設定：

• 必須使用 HTTPS。強烈建議使用 TLS 1.2 以上版本，並啟用 HTTP 嚴格傳輸安全性 (HSTS)。請參閱這篇相關的 MDN 文章，瞭解嚴格傳輸安全性。
• 啟用嚴格內容安全政策 (嚴格 CSP)。請參閱這篇 OWASP 文章 和這篇相關的 內容安全政策 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。

外掛程式權杖

addOnToken 值是授權權杖，用於發出 addOnAttachments.create 呼叫，以建立外掛程式。

隨附於附件探索 iframe 和連結升級 iframe。

要升級的網址

如果存在 urlToUpgrade 值，表示老師已在作業中加入連結附件，並同意將其升級為外掛程式附件。如果尚未設定這項功能，請參閱這份指南，瞭解如何升級連結以新增附件。

隨附於 Link Upgrade iframe。

登入相關參數

login_hint 查詢參數提供造訪外掛程式網頁的 Classroom 使用者相關資訊。這個查詢參數會提供在 iframe src 網址中。如果使用者先前曾使用外掛程式，系統就會傳送這項事件，以減少使用者登入時遇到的阻礙。您必須在外掛程式實作中處理這個查詢參數。

登入提示

login_hint 是使用者 Google 帳戶的專屬 ID。使用者首次登入外掛程式後，每次造訪外掛程式時，系統都會傳遞 login_hint 參數。

login_hint 參數有兩種潛在用途：

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

所有 iframe 皆包含這項屬性。

附件探索 iframe

附件探索情境範例

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

studentWorkReviewUri iframe

Link Upgrade iframe

連結升級情境範例

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 會啟動 Link Upgrade 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

您可以從學習工具傳送含有酬載 {type: 'Classroom', action: 'closeIframe'} 的 postMessage，關閉 iframe。Classroom 只會接受來自 host_name+port 的 postMessage，且該 host_name+port 對應於開啟的原始 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 關閉 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。