Os complementos do Google Sala de Aula já estão disponíveis para desenvolvedores. Consulte a documentação sobre complementos para mais informações.

Faça upgrade dos anexos de link para anexos de complementos do Google Sala de Aula

Uma das maneiras de os professores adicionarem conteúdo de terceiros ao Google Sala de Aula é colando um link como anexo de link na página de criação de atividades. Para aproveitar o que os professores já conhecem, agora é possível configurar seu complemento para que eles possam fazer upgrade de um anexo de link para um anexo de complemento.

Visão geral

Se você configurar seu complemento com esse recurso, os professores vão receber uma solicitação para fazer upgrade de um link para um anexo de complemento quando colarem um anexo de link na página de criação de atividades. Os professores só vão receber essa solicitação se já tiverem o complemento instalado.

Depois que o professor concordar em fazer upgrade do link para um anexo de complemento, o iframe de upgrade de link será aberto com os seguintes parâmetros de consulta:

courseId
itemId
itemType
addOnToken
urlToUpgrade
login_hint (somente se o usuário já tiver autorizado seu app)

Os quatro primeiros parâmetros de consulta espelham os parâmetros de consulta iniciados no iframe de descoberta de anexos. O parâmetro de consulta urlToUpgrade é novo e pode ajudar você a avaliar como o anexo de complemento deve ser criado. Em seguida, você pode usar os outros parâmetros de consulta para verificar se o usuário fez login e chamar o CreateAddOnAttachment método de courseWork, courseWorkMaterials ou announcements com base no valor itemType. No iframe, você pode mostrar uma tela de carregamento para indicar ao professor que o anexo de complemento está sendo criado.

Depois que o anexo de complemento for criado, o iframe será fechado e o professor poderá ver o anexo na atividade como de costume.

Detalhes da implementação técnica

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. Você precisa decodificar o URL para recebê-lo no formato 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 complemento for criado. Isso fecha o iframe. Consulte a página de detalhes da implementação do iframe para mais informações.

Detalhes da configuração

As configurações a seguir são necessárias para integrar esse recurso ao seu complemento:

URL do iframe de upgrade de link: é o URL que é aberto no iframe quando um professor concorda em fazer upgrade.
Padrões de URL que o Google Sala de Aula deve detectar e tentar fazer upgrade: os padrões de URL podem consistir em um host e vários prefixos de caminho.
- É possível fornecer vários padrões de URL.
- Se você não fornecer nenhum prefixo de caminho, qualquer URL que corresponda ao host poderá ser atualizado.
- Somente URLs com um esquema https podem ser atualizados.
- 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 podem oferecer suporte a caracteres curinga no momento, mas os hosts não podem:
  - 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 os componentes do prefixo de caminho só corresponde a um único componente e não corresponde a vários componentes separados por barras. Considere um padrão do 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 do URL.
  - https://example.com/bar/123/456/baz não é uma correspondência válida para o padrão do URL porque o caractere curinga no prefixo de 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.

Você pode fornecer configurações para qualquer projeto na nuvem do Google que represente um complemento do Google Sala de Aula. Recomendamos que você primeiro forneça configurações para um complemento com visibilidade privada para que possa desenvolver e testar em um domínio de demonstração sem afetar os usuários ativos.

Você vai receber uma resposta ao seu e-mail quando as configurações forem ativadas. Observação: 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 na nuvem do Google Cloud ao qual o complemento está associado.
LINK_UPGRADE_IFRAME_URL: o URL que deve ser aberto no iframe de upgrade de link.
HOST_1: um host que o Google Sala de Aula deve detectar. Somente 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 deve detectar e tentar fazer upgrade.
HOST_2: um host que o Google Sala de Aula deve detectar. Somente 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 deve detectar e tentar fazer upgrade.

Experiência do usuário recomendada

Confira a seguir algumas sugestões a serem consideradas ao implementar esse recurso.

Evitar trabalho extra para professores

Recomendamos que você use o iframe para facilitar o login, se necessário, ou mostrar um indicador de carregamento. Para a melhor experiência do usuário, o professor não deve receber uma solicitação de mais informações depois de concordar em fazer upgrade do link colado para um anexo de complemento. No entanto, se isso não for possível para seu complemento, você poderá usar o iframe de upgrade de link para coletar mais informações necessárias. O iframe também pode ser usado para informar o professor se não for possível fazer upgrade do link ou se ocorrer um erro.

Incluir mensagens de erro de acesso fáceis de usar

Se os professores colarem e fizerem upgrade de um link ao qual não têm acesso, mostre uma mensagem de erro fácil de usar no iframe para que eles saibam do problema. O iframe também pode ser usado para fornecer ao professor as permissões adequadas para acessar o conteúdo.