iframe 和查询参数详情

Google 课堂插件会在 iframe 中加载，以便为最终用户提供顺畅便捷的用户体验。有五种不同的 iframe 类型；如需大致了解每种 iframe 的用途和外观，请参阅“用户体验历程”目录中的 iframe 页面。

要点 ：当用户打开您的某个插件视图时，您会收到各种信息。使用此信息可识别附件、验证用户的凭据和角色，以及执行某些 API 请求。

iframe 安全准则

开发者应遵循业界最佳实践来保护其 iframe。不过，您还应在用户流程中添加特定的 API 互动，以确保您拥有有效的凭据，并且能够正确识别用户在课程中的角色。

服务器应用配置

为保护 iframe，我们建议您采用以下服务器配置：

• 必须使用 HTTPS 格式的网址。我们强烈建议使用 TLS 1.2 或更高版本并启用 HTTP 严格传输安全协议 (HSTS)。请参阅这篇有关严格传输安全协议的相关 MDN 文章。
• 启用严格内容安全政策 (Strict CSP)。请参阅这篇 OWASP 文章以及这篇相关的 Content Security Policy MDN 文章。
• 启用安全 Cookie 属性。请参阅 HttpOnly 属性以及这篇相关的 Cookies MDN 文章。

查询参数

iframe 会将重要信息作为查询参数传递给插件。参数分为两类：与附件相关的参数和与登录相关的参数。

与附件相关的参数

与附件相关的参数可向插件提供有关课程、作业、插件附件、学生提交的内容和授权令牌的信息。

课程 ID

courseId 值是课程的标识符。

包含在所有 iframe 中。

商品 ID

itemId 值是 Announcement 的标识符，

CourseWork 或此附件附加到的 CourseWorkMaterial。

包含在所有 iframe 中。

项类型

itemType 值用于标识此

附件已随附。传递的字符串值为 "announcements"、"courseWork" 或 "courseWorkMaterials" 之一。

包含在所有 iframe 中。

附件 ID

attachmentId 值是附件的标识符。

包含在 teacherViewUri、studentViewUri 和 studentWorkReviewUri iframe 中。

提交内容 ID

submissionId 值是学生作业的标识符，但应与 attachmentId 结合使用，以标识学生的特定作业。

包含在 studentWorkReviewUri 中。

注意： 如果同一学生在不同课程中被分配了相同的附件，您可以使用 submissionId 和 attachmentId 的复合键来标识学生的作业。如需了解详情，请参阅复制的内容。

插件令牌

addOnToken 值是用于进行

addOnAttachments.create 调用以创建插件。

包含在附件发现 iframe 和链接升级 iframe 中。

要升级的网址

urlToUpgrade 值的存在表示

教师在作业中添加了链接附件，并同意将其升级为插件附件。如果您尚未配置此功能，请参阅有关将链接升级为插件附件的指南，了解详情。

包含在“链接升级”iframe 中。

与登录相关的参数

login_hint 查询参数提供有关访问插件网页的 Google 课堂用户的信息。此查询参数在 iframe src 网址中提供。当用户之前使用过您的插件时，系统会发送此事件，以帮助减少最终用户登录的阻碍。您必须在插件实现中处理此查询参数。

登录提示

login_hint 是用户 Google 账号的唯一标识符

账号。用户首次登录您的插件后，同一用户每次再次访问您的插件时，系统都会传递 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. 在 Google Workspace Marketplace 中注册了一个 Google 课堂插件，其附件发现 URI 为 https://example.com/addon。
2. 教师安装此插件，并在其某门课程中创建新的通知、作业或资料。例如，itemId=234、itemType=courseWork 和 courseId=123。
3. 在配置该内容时，教师选择新安装的插件作为附件。
4. Google 课堂会创建一个将 src 网址设为 https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456 的 iframe。
   1. 教师在 iframe 中执行工作，以选择附件。
5. 选择附件后，该插件会向 Google 课堂发送 postMessage 以关闭 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. 一个 Google 课堂插件已注册，其链接升级 URI 为 https://example.com/upgrade。您已为链接附件（Google 课堂应尝试将其升级为插件附件）提供了以下主机和路径前缀模式：
   • 主机为 example.com，路径前缀为 /quiz。
2. 教师在其课程中创建了新通知、作业或资料。例如，itemId=234、itemType=courseWork 和 courseId=123。
3. 教师在“链接附件”对话框中粘贴了一个网址 https://example.com/quiz/5678，该网址与您提供的网址格式匹配。然后，系统会提示教师将链接升级为插件附件。

4. Google 课堂会启动网址设为 https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678 的“链接升级”iframe。

5. 您可以评估在 iframe 上传递的查询参数，并调用 CreateAddOnAttachment 端点。请注意，在 iframe 上传递时，urlToUpgrade 查询参数会被 URI 编码。您需要对参数进行解码，才能获取其原始形式。例如，JavaScript 提供了 decodeURIComponent() 函数。

6. 通过链接成功创建插件附件后，您向 Google 课堂发送 postMessage 以关闭 iframe。

关闭 iframe

您可以通过发送包含载荷 {type: 'Classroom', action: 'closeIframe'} 的 postMessage 从学习工具关闭 iframe。Google 课堂仅接受与打开的原始 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 课堂插件独有，会影响所有使用第三方 iframe 的网站。我们的许多合作伙伴都遇到过此问题。

以下是一些常见的权宜解决方法：

• 打开一个新标签页，在第一方环境中创建 Cookie。有些浏览器会在第三方环境中授予对在第一方环境中创建的 Cookie 的访问权限。
• 要求用户允许使用第三方 Cookie。但这不一定适用于所有用户。
• 设计不依赖 Cookie 的单页 Web 应用。

未来的浏览器版本可能会对 Cookie 施加更多限制。创建功能请求，向 Google 发送有关如何降低合作伙伴所需效果提升幅度的反馈。

使用网址正则表达式提高插件可检测性

教师经常创建包含链接附件的作业。为了推广您的插件，您可以指定与可在插件中访问的资源的网址匹配的正则表达式。如果教师附加的链接与您的某个正则表达式匹配，系统会显示一个可关闭的对话框，提示教师试用您的插件。只有当其账号中已安装该插件时，用户才会看到该对话框。

如果您想向教师提供此行为，请向您的 Google 联系人提供适当的正则表达式。如果您提供的正则表达式过于宽泛或与其他插件冲突，我们可能会对其进行修改，使其更具限制性或更具区分度。

图 1. 教师为新作业选择链接附件。

图 2. 教师粘贴来自第三方来源的链接。教师已安装第三方 Google 课堂插件。

图 3. 当粘贴的链接与第三方开发者指定的正则表达式匹配时，向教师显示的互动式对话框。

如果教师在弹出式窗口中选择“立即试用”（如图 3 所示），则会被重定向到您的插件中的“发现附件”iframe。