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

教师向 Google 课堂添加第三方内容的一种方法是，将链接以链接附件的形式粘贴到作业创建页面中。为了基于教师已经熟悉的内容进行构建，您现在可以配置插件，允许教师将链接附件升级为插件附件。

概览

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

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

  • courseId
  • itemId（重命名自 postId）
  • itemType（新！）
  • addOnToken
  • login_hint 或 hd
  • urlToUpgrade（新！）

前四个查询参数反映了在附件发现 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/ 不匹配。

开发流程

发送电子邮件至 classroom-link-upgrade-external@google.com，发送您的测试或正式版插件的链接升级 iframe 网址格式和网址格式。

您可以先为您的专用插件以及您拥有的任何测试或开发环境提供配置。Google 课堂团队可以在启用正式版配置之前启用这些测试配置，以便您在演示网域中测试流程。启用配置后，您将收到电子邮件回复。请注意，此功能不支持使用 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：Google 课堂应检测并尝试升级的 HOST_1 关联的路径前缀。
  • HOST_2：Google 课堂应检测到的主机。 仅支持 https 架构。
  • PATH_PREFIX_3 和 PATH_PREFIX_4：Google 课堂应检测并尝试升级的与 HOST_2 关联的路径前缀。

以下是实现此功能时需要考虑的建议。

避免为教师增加额外作业

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

提供方便用户使用的访问错误消息

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