iframe 和查询参数详情

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

iframe 安全准则

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

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

• 启用严格的内容安全政策。请参阅这篇 OWASP 文章以及这篇相关的 Content Security Policy MDN 文章。

• 启用安全 Cookie 属性。请参阅 HttpOnly 属性以及这篇相关的 Cookies 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 中。

插件令牌

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 课堂会创建一个将 src 网址设为 https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456 的 iframe。
   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 课堂会启动网址设为 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。