iframe 和查询参数详情

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

iframe 安全准则

合作伙伴应遵循行业最佳做法来保护 iframe。 为了保护 iframe，我们的安全团队建议采取以下措施：

• HTTPS 为必填项。我们强烈建议您使用 TLS 1.2 或更高版本，并启用 HTTP 严格传输安全协议。请参阅这篇有关严格传输安全协议的 MDN 文章。

• 启用严格内容安全政策。请参阅这篇 OWASP 文章和这篇内容安全政策 MDN 文章。

• 启用安全 Cookie 属性。请参阅 HttpOnly 属性以及这篇相关的 Cookie MDN 文章。

iframe URI 配置

附件设置 URI 是附件发现 iframe 的加载内容，教师可在该 URI 中开始为 Google 课堂帖子创建插件附件。您可以在 Google Cloud 项目控制台中进行设置。在 Google Cloud 项目的“API 和服务”>“Google Workspace Marketplace SDK”>“应用配置”页面中设置此 URI。

允许的附件 URI 前缀用于通过 *.addOnAttachments.create 和 *.addOnAttachments.patch 方法验证 AddOnAttachment 中设置的 URI。验证是字面量字符串前缀匹配，目前不允许使用通配符。

查询参数

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

附件相关参数

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

课程 ID

courseId 值是课程的标识符。

所有 iframe 都包含。

帖子 ID（已弃用）

postId 值是附加此附件的帖子（通知、课程作业或课程作业资料）的标识符。

所有 iframe 都包含。

已弃用：帖子 ID 已弃用，请改用商品 ID。

商品 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、postId（已废弃）、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、postId（已废弃）、itemId、itemType、attachmentId 和 login_hint。
身高	顶部标题的窗口高度为 100% 减去 140 像素
宽度	100% 窗口宽度

学生 WorkReviewUri iframe

维度	说明
必需	否（确定是否为活动类型的附件）
URI	studentWorkReviewUri
查询参数	courseId、postId（已废弃）、itemId、itemType、attachmentId、submissionId 和 login_hint。
身高	顶部标题的窗口高度为 100% 减去 168 像素
宽度	100% 窗口宽度减去边栏宽度<> 边栏在展开时为 312 像素，收起时为 56 像素

注意 ：教师可以打开之前未查看过该插件附件的学生的“学生作业评价”iframe。在这种情况下，插件可能尚未发现此学生，应显示相应的消息。

链接升级 iframe

维度	说明
必需	可以，前提是您的插件支持指向插件附件的升级链接。
URI	在插件元数据中提供
查询参数	courseId、postId（已废弃）、itemId、itemType、addOnToken、urlToUpgrade 和 login_hint。
身高	顶部标题的窗口高度为 80% 减去 60 像素
宽度	窗口宽度上限为 1600 像素 窗口宽度不超过 600 像素时为 90% 窗口宽度不超过 600 像素时为窗口宽度的 80%

链接升级场景示例

1. 使用链接升级 URI 为 https://example.com/upgrade 注册的 Google 课堂插件。您为 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&postId=234&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678 的链接升级 iframe。

5. 您需要评估在 iframe 上传递的查询参数，并调用 CreateAddOnAttachment 端点。请注意，urlToUpgrade 查询参数在传入 iframe 时采用 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 事件。顺便提一下，超链接“Open in Partner Name”（在合作伙伴名称中打开）将被移除，因此用户近期不会以这种方式创建标签页。

限制

系统通过以下沙盒属性打开所有 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。