Para adicionar conteúdo de terceiros ao Google Sala de Aula, os professores podem colar um link como Anexo de link na página de criação de atividades. Agora você pode configurar seu complemento para que eles façam upgrade de um anexo de link para um anexo de complemento.
Visão geral
Se você configurar seu complemento com esse recurso, os professores precisarão fazer upgrade de um link para um anexo ao colar o link na página de criação da atividade. Os professores só são solicitados a fazer isso se já tiverem o complemento instalado.
Quando o professor concorda em fazer upgrade do link para um anexo de complemento, o iframe "Upgrade de link" é iniciado com os seguintes parâmetros de consulta:
courseId
itemId
itemType
addOnToken
urlToUpgrade
login_hint
(somente se o usuário já tiver autorizado o app)
Os quatro primeiros parâmetros de consulta espelham os parâmetros de consulta iniciados no
iframe de descoberta de anexos (link em inglês). O parâmetro de consulta urlToUpgrade
é novo e pode
ajudar você a avaliar como o anexo de complementos precisa ser criado. Em seguida, é possível usar os outros parâmetros de consulta para verificar se o usuário está conectado e chamar o método CreateAddOnAttachment
de courseWork
, courseWorkMaterials
ou announcements
com base no valor itemType
. No iframe, é possível mostrar uma tela de carregamento para indicar ao professor que o anexo de complementos está sendo criado.
Depois que o anexo de complementos é criado, o iframe é fechado, e o professor pode acessar o anexo na atividade normalmente.
Detalhes técnicos da implementação
Esta seção destaca alguns detalhes técnicos importantes do recurso.
Ler o parâmetro de consulta urlToUpgrade
O parâmetro de consulta urlToUpgrade
é codificado por URI quando é transmitido no iframe de upgrade de link. É necessário decodificar o URL para obtê-lo na forma original. Se
você estiver usando JavaScript, por exemplo, poderá usar a função
decodeURIComponent()
para fazer isso.
Fechar o iframe de upgrade de link
Para garantir uma experiência do usuário ideal para esse recurso, envie uma postMessage
assim
que o anexo de complementos for criado. Isso fecha o iframe. Consulte a página de detalhes da implementação de iframe para mais informações.
Detalhes da configuração
As configurações abaixo são necessárias para integrar esse recurso ao complemento:
URL do iframe de upgrade de link: é o URL que abre no iframe quando um professor concorda em fazer upgrade.
Padrões de URL que o Google Sala de Aula precisa detectar e tentar fazer upgrade: os padrões de URL podem consistir em um host e vários prefixos de caminho.
- Você pode fornecer vários padrões de URL.
- Se você não fornecer prefixos de caminho, será possível fazer upgrade de qualquer URL que corresponda ao host.
- Só é possível fazer upgrade de URLs com um esquema
https
. - Os padrões de URL não podem conter
localhost
. - Os prefixos de caminho não podem conter parâmetros de consulta ou fragmentos de URL.
- Os prefixos de caminho aceitam caracteres curinga no momento, mas os hosts não:
-
example.com
é um host válido, e/foo
e/bar/*/baz
são prefixos de caminho válidos. -
example.*.host.com
não é um host válido.
-
- Um caractere curinga entre componentes de prefixo de caminho corresponde apenas a um
componente e não a vários componentes separados por barras.
Considere um padrão de URL com o host
example.com
e o prefixo de caminho/bar/*/baz
:-
https://example.com/bar/123/baz
é uma correspondência válida para o padrão de URL. -
https://example.com/bar/123/baz/456/789
é uma correspondência válida para o padrão de URL. -
https://example.com/bar/123/456/baz
não é uma correspondência válida para o padrão de URL porque o caractere curinga no prefixo do caminho não corresponde a/123/456/
.
-
Processo de desenvolvimento
Envie o URL do iframe de upgrade de link e os padrões de URL para seu complemento de teste ou produção enviando um e-mail para classroom-link-upgrade-external@google.com.
É possível fornecer configurações para qualquer projeto do Google Cloud que represente um complemento do Google Sala de Aula. Recomendamos que você primeiro forneça as configurações de um complemento com visibilidade particular para que possa desenvolver e testar em um domínio de demonstração sem afetar os usuários ativos.
Você receberá uma resposta por e-mail quando as configurações forem ativadas. Os padrões de URL que usam localhost
não são compatíveis com esse
recurso.
Formate o e-mail para incluir o seguinte:
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
Substitua:
- GCP_PROJECT_NUMBER: o número do projeto do Google Cloud a que o complemento está associado.
- LINK_UPGRADE_IFRAME_URL: o URL que será aberto no iframe de upgrade de link.
- HOST_1: um host que o Google Sala de Aula precisa detectar. Apenas o
esquema
https
é compatível. - PATH_PREFIX_1 e PATH_PREFIX_2: prefixos
de caminho associados a
HOST_1
que o Google Sala de Aula precisa detectar e tentar fazer upgrade. - HOST_2: um host que o Google Sala de Aula precisa detectar. Apenas o
esquema
https
é compatível. - PATH_PREFIX_3 e PATH_PREFIX_4: prefixos
de caminho associados a
HOST_2
que o Google Sala de Aula precisa detectar e tentar fazer upgrade.
Experiência do usuário recomendada
Considere as sugestões a seguir ao implementar esse recurso.
Evite o trabalho extra dos professores
É altamente recomendável usar o iframe para facilitar o login, se necessário, ou mostrar um indicador de carregamento. Para uma melhor experiência do usuário, o professor não deve receber solicitações de mais informações após concordar em fazer upgrade do link colado para um anexo de complemento. No entanto, se isso não for possível para seu complemento, use o iframe de upgrade de link para coletar outras informações necessárias. O iframe também pode ser usado para informar ao professor se não for possível fazer upgrade do link ou se ocorrer um erro.
Incluir mensagens de erro de acesso fácil de usar
Se os professores colarem e atualizarem um link a que não têm acesso, exiba uma mensagem de erro fácil de usar no iframe para que eles fiquem cientes do problema. O iframe também pode ser usado para fornecer ao professor as permissões adequadas para acessar o conteúdo.