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

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

概览

如果您为插件配置了此功能,则当教师在作业创建页面中粘贴链接附件时,系统会提示他们将链接升级为插件附件。只有在教师已安装该插件时,系统才会提示他们执行此操作。

当教师同意将链接升级为插件附件后,系统就会启动链接升级 iframe,其中包含以下查询参数:

  • courseId
  • itemId
  • itemType
  • addOnToken
  • urlToUpgrade
  • login_hint(仅当用户已向您的应用授权时)

前四个查询参数反映了在附件发现 iframe 中启动的查询参数。urlToUpgrade 查询参数是新参数,可帮助您评估应如何创建插件附件。然后,您可以使用其他查询参数检查用户是否已登录,并根据 itemType 值调用 courseWorkcourseWorkMaterialsannouncementsCreateAddOnAttachment 方法。在 iframe 中,您可以显示一个加载屏幕,告知教师系统正在创建插件附件。

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

技术实现详情

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

读取 urlToUpgrade 查询参数

在通过“链接升级”iframe 传递时,urlToUpgrade 查询参数会进行 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/ 不匹配。

开发流程

请发送电子邮件至 classroom-link-upgrade-external@google.com,将测试或正式版插件对应的“链接升级”iframe 网址和网址模式发送给我们。

您可以为代表 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_1PATH_PREFIX_2:与 HOST_1 关联的路径前缀,Google 课堂应检测并尝试升级。
  • HOST_2:Google 课堂应检测到的宿主。仅支持 https 方案。
  • PATH_PREFIX_3PATH_PREFIX_4:与 HOST_2 关联的路径前缀,Google 课堂应检测并尝试升级。

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

避免给教师增加额外工作

我们强烈建议您使用 iframe 来简化登录流程(如果需要)或显示加载指示器。为提供最佳用户体验,在教师同意将粘贴的链接升级为插件附件后,系统不应再提示他们提供任何其他信息。但是,如果您的插件无法做到这一点,您可以使用链接升级 iframe 收集所需的其他信息。iframe 还可以用于通知教师是否无法升级链接或发生错误。

包含方便用户使用的访问错误消息

如果教师粘贴并升级他们无权访问的链接,请在 iframe 中显示便于理解的错误消息,以便教师知晓此问题。 iframe 还可用于向教师提供访问内容的适当权限。