iframe 和查询参数详情

iframe 安全准则

开发者应遵循行业最佳实践来保护 iframe。不过，您还应在用户流程中加入某些 API 互动，以确认您拥有有效的凭据，并且可以正确识别用户在课程中的角色。

服务器应用配置

为了保护 iframe，我们建议您进行以下服务器配置：

• 必须使用 HTTPS 格式的网址 。我们强烈建议您使用 TLS 1.2 或更高版本，并启用 HTTP 严格传输安全协议 (HSTS)。请参阅这篇关于严格传输安全协议的相关 MDN 文章。
• 启用严格内容安全政策 (Strict CSP)。请参阅这篇 OWASP 文章 和这篇相关的 内容安全政策 MDN 文章。
• 启用安全 Cookie 属性。请参阅 HttpOnly 属性和这篇 相关的 Cookie 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 中。

插件令牌

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

附件探索 iframe

附件探索场景示例

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 iframe

studentWorkReviewUri iframe

链接升级 iframe

链接升级场景示例

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 课堂会启动链接升级 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. 成功从链接创建插件附件后，您会向 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。