将链接附件升级为 Google 课堂插件附件

教师向 Google 课堂添加第三方内容的一种方式是 在作业创建页面中粘贴链接作为链接附件。为了让教师能够使用他们已经熟悉的功能，您现在可以配置插件，让教师将链接附件升级为插件附件。

概览

如果您为插件配置了此功能，那么当教师在作业创建页面中粘贴链接附件时，系统会提示他们将链接升级为插件附件。只有在教师已安装插件的情况下，系统才会提示他们这样做。

教师同意将链接升级为插件附件后，系统会启动“链接升级”iframe，并使用以下查询参数：

  • courseId
  • itemId
  • itemType
  • addOnToken
  • urlToUpgrade
  • login_hint（仅当用户已授权您的应用时）

前四个查询参数与在 “附件发现”iframe中启动的查询参数相同。urlToUpgrade 查询参数是新参数，可帮助您评估应如何创建插件附件。然后，您可以使用 其他查询参数检查用户是否已登录，并根据 itemType 值调用 courseWork、courseWorkMaterials 或 announcements 的 CreateAddOnAttachment 方法。在 iframe 中，您可以显示加载屏幕，向教师表明插件附件正在创建中。

插件附件创建完毕后，iframe 会关闭，教师可以像往常一样在作业中查看附件。

技术实现详情

本部分重点介绍此功能的一些重要技术细节。

读取 urlToUpgrade 查询参数

urlToUpgrade 查询参数在“链接升级”iframe 中传递时会进行 URI 编码。您必须对网址进行解码，才能获取其原始形式。例如，如果您使用的是 JavaScript，则可以使用 decodeURIComponent() 函数来执行此操作。

为了确保此功能提供最佳用户体验，请在插件附件成功创建后发送 postMessage。这会关闭 iframe。如需了解详情，请参阅 iframe 实现详情页面。

配置详情

如需将此功能集成到插件中，您需要进行以下配置：

  • “链接升级”iframe 的网址：这是当教师同意升级时在 iframe 中打开的网址。

  • Google 课堂应检测并尝试 升级的网址格式：网址格式可以包含一个主机和多个路径 前缀。

    • 您可以提供多个网址格式。
    • 如果您未提供任何路径前缀，则可以升级与主机匹配的任何网址。
    • 只有采用 https 架构的网址才能升级。
    • 网址格式不得包含 localhost。
    • 路径前缀不得包含查询参数或网址片段。
    • 路径前缀目前支持通配符，但主机不支持：
      • example.com 是有效的主机，/foo 和 /bar/*/baz 是有效的路径前缀。
      • example.*.host.com 不是有效的主机。
    • 路径前缀组件之间的通配符仅与单个组件匹配，而不与以斜杠分隔的多个组件匹配。 假设网址格式的主机为 example.com，路径前缀为 /bar/*/baz：
      • https://example.com/bar/123/baz 与网址格式有效匹配。
      • https://example.com/bar/123/baz/456/789 与网址格式有效匹配。
      • https://example.com/bar/123/456/baz 与 网址格式不匹配，因为路径前缀中的通配符与 /123/456/ 不匹配。

开发流程

如需获取测试或生产 插件的“链接升级”iframe 网址和网址格式，请发送电子邮件至 classroom-link-upgrade-external@google.com。

您可以为代表 Google 课堂插件的任何 Google Cloud 项目提供配置。我们建议您先为具有私密可见性的插件提供配置，以便您可以在演示网域中进行开发和测试，而不会影响实际用户。

配置启用后，您会收到电子邮件回复。请注意，此功能不支持使用 localhost 的网址格式。

请按以下格式编写电子邮件：

Google Cloud Project number: GCP_PROJECT_NUMBER

Link Upgrade iframe URL: LINK_UPGRADE_IFRAME_URL

URL Patterns:
-   Host:HOST_1
-   Path prefixes:
  -   PATH_PREFIX_1
  -   PATH_PREFIX_2

-   Host:HOST_2
-   Path prefixes:
  -   PATH_PREFIX_3
  -   PATH_PREFIX_4

// add more hosts and path prefixes as needed

替换以下内容：

  • GCP_PROJECT_NUMBER：与插件关联的 Google Cloud 云项目的编号。
  • LINK_UPGRADE_IFRAME_URL：应在 “链接升级”iframe 中打开的网址。
  • HOST_1：Google 课堂应检测的主机。仅支持 https 架构。
  • PATH_PREFIX_1 和 PATH_PREFIX_2：与 HOST_1 关联的路径前缀，Google 课堂应检测并尝试升级。
  • HOST_2：Google 课堂应检测的主机。仅支持 https 架构。
  • PATH_PREFIX_3 和 PATH_PREFIX_4：与 HOST_2 关联的路径前缀，Google 课堂应检测并尝试升级。

以下是在实现此功能时可以考虑的建议。

避免教师进行额外操作

我们强烈建议您使用 iframe 来帮助用户登录（如果需要），或显示加载指示器。为了提供最佳用户体验，教师在同意将粘贴的链接升级为插件附件后，不应被要求提供任何其他信息。但是，如果您的插件无法做到这一点，您可以使用“链接升级”iframe 来收集所需的其他信息。如果无法升级链接或发生错误，您还可以使用 iframe 通知教师。

提供清晰易懂的访问错误消息

如果教师粘贴并升级了他们无权访问的链接，请在 iframe 中显示清晰易懂的错误消息，以便教师了解问题。 您还可以使用 iframe 为教师提供访问相应内容的适当权限。