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 加载的内容，教师可在此处启动在 Google 课堂帖子中创建插件附件的流程。您可以在 Google Cloud 项目控制台中对其进行设置。在 Google Cloud 项目的“API 和服务”>“Google Workspace Marketplace SDK”>“应用配置”页面中设置此 URI。

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

查询参数

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 中。

注意： 如需详细了解如何在 SSO、顺畅登录和处理重复登录演示页面中实现 login_hint 参数和登录流程。

附件发现 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 课堂会创建一个 iframe，并将 src 网址设置为 https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456。
   1. 教师在 iframe 内执行操作以选择附件。
5. 选择附件时，该插件会向 Google 课堂发送 postMessage 以关闭 iframe。

TeacherViewUri 和 studentViewUri iframes

维度	说明
必需	是
URI	teacherViewUri或studentViewUri
查询参数	courseId、itemId、itemType、attachmentId 和 login_hint。
身高	100% 的窗口高度减去 140 像素的顶部页眉
宽度	100% 窗口宽度

studentWorkReviewUri iframe

维度	说明
必需	否（确定这是否为活动类型的附件）
URI	studentWorkReviewUri
查询参数	courseId、itemId、itemType、attachmentId、submissionId 和 login_hint。
身高	100% 窗口高度减去 168px 顶部标头
宽度	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 端点。请注意，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 事件。顺便提一下，我们将移除“在合作伙伴名称中打开”超链接，以便用户在不久的将来不再以这种方式创建标签页。

限制

所有 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.教师正在粘贴第三方来源的链接教师已经安装了第三方的“课堂”插件。

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

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