教师向 Google 课堂添加第三方内容的一种方法是,将链接作为链接附件粘贴到作业创建页面中。在教师已经熟悉的基础上,您现在可以配置插件,让教师将链接附件升级为插件附件。
概览
如果您为插件配置此功能,那么在教师将链接附件粘贴到作业创建页面中时,系统会提示教师升级插件附件的链接。只有当教师已安装该插件时,系统才会提示他们执行此操作。
当教师同意将链接升级为插件附件后,系统就会启动链接升级 iframe,其中包含以下查询参数:
courseId
itemId
itemType
addOnToken
urlToUpgrade
login_hint
(仅当用户已向您的应用授权时)
前 4 个查询参数反映了在附件发现 iframe 中发布的查询参数。urlToUpgrade
查询参数是新的,可帮助您评估应如何创建插件附件。然后,您可以使用其他查询参数检查用户是否已登录,并根据 itemType
值调用 courseWork
、courseWorkMaterials
或 announcements
的 CreateAddOnAttachment
方法。在 iframe 中,您可以显示一个加载屏幕,告知教师系统正在创建插件附件。
插件附件创建好后,iframe 就会关闭,教师可以照常在作业中查看附件。
技术实现详情
本部分重点介绍了此功能的一些重要技术细节。
读取 urlToUpgrade
查询参数
urlToUpgrade
查询参数在通过链接升级 iframe 传递时是 URI 编码的。您必须对网址进行解码,以获取原始形式的网址。例如,如果您使用的是 JavaScript,则可以使用 decodeURIComponent()
函数实现此目的。
关闭链接升级 iframe
为确保此功能提供最佳用户体验,请在成功创建插件连接后发送 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_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 还可用于向教师提供访问相应内容的相应权限。