iframe 和查詢參數詳細資料

Classroom 外掛程式會在 iframe 內載入，為使用者提供流暢便利的使用者體驗。有兩種不同的 iframe 類型；請參閱「使用者歷程」目錄中的 iframes 網頁，瞭解每個 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 (已淘汰)

postId 值是這個連結所附加文章 (公告、課程作業或課程作業教材) 的 ID。

與所有 iframe 皆包含在內。

已淘汰：貼文 ID 已淘汰，請改用項目 ID。

項目 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 皆包含在內。

注意： 如需在 SSO、順暢登入和處理重複登入操作逐步操作頁面中實作 login_hint 參數和登入流程的相關資訊，請查詢相關資訊。

附件探索 iframe

維度	說明
必要	是
URI	由外掛程式中繼資料提供
查詢參數	courseId、postId (已淘汰)、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、postId (已淘汰)、itemId、itemType、attachmentId 和 login_hint。
身高	頂端標頭高度為 100% 減 140 像素
寬度	100% 視窗寬度

StudentWorkReviewUri iframe

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

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

連結升級 iframe

維度	說明
必要	可以，如果您的外掛程式支援升級外掛程式附件的連結。
URI	由外掛程式中繼資料提供
查詢參數	courseId、postId (已淘汰)、itemId、itemType、addOnToken、urlToUpgrade 和 login_hint。
身高	頂端標頭高度為 80% 減 60 像素
寬度	最大 1600 像素 當視窗寬度小於 600 像素時，視窗寬度為 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&postId=234&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 只接受與已開啟原始 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。