iframe 和查询参数详情

Classroom 加载项在 iframe 中加载，可为最终用户提供顺畅便捷的用户体验。iframe 类型共有五种；如需了解每种 iframe 的用途和外观，请参阅“用户体验历程”目录中的 iframe 页面。

iframe 安全准则

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

服务器应用配置

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

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

插件令牌

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。您为链接附件提供了以下主机和路径前缀模式，Classroom 应尝试将其升级为插件附件：
   • 主机为 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。 Classroom 仅接受来自与打开的原始 URI 对应的 host_name+端口的此 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 均以以下 sandbox 属性打开：

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