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

Uma maneira de os professores adicionarem conteúdo de terceiros ao Google Sala de Aula é colando um link como um anexo de link na página de criação de atividades. Para criar com base no que os professores já conhecem, agora você pode configurar seu complemento para permitir que eles atualizem um anexo de link para um anexo de complemento.

Visão geral

Se você configurar o complemento com esse recurso, os professores vão precisar atualizar 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.

Quando o professor concorda em atualizar o link para um anexo de complemento, o iframe de atualização do 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 refletem 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 do complemento precisa ser criado. Em seguida, é possível usar os outros parâmetros de consulta para verificar se o usuário fez login e chamar o método CreateAddOnAttachment 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 do complemento está sendo criado.

Depois que o anexo do complemento é 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 em URI quando é transmitido no iframe de upgrade do link. Você precisa decodificar o URL para acessá-lo no formato original. Se você estiver usando JavaScript, por exemplo, use a função decodeURIComponent() para fazer isso.

Fechar o iframe do upgrade do link

Para garantir uma experiência ideal do usuário com esse recurso, envie um postMessage depois que o anexo do complemento for criado. Isso fecha o iframe. Consulte a página de detalhes da implementação de iframes para mais detalhes.

Detalhes da configuração

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

• URL do iframe de atualização do link: é o URL que é aberto no iframe quando um professor concorda com a atualização.

• Padrões de URL que o Google Sala de Aula precisa detectar e tentar atualizar: 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, 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 aceitar 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 curinga entre componentes de prefixo de caminho corresponde apenas a um único componente e não corresponde 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/.

Observação: os caracteres curinga entre os componentes do prefixo do caminho correspondem apenas a um único componente.

Processo de desenvolvimento

Envie o URL do iframe do Link Upgrade e os padrões de URL para seu complemento de teste ou produção. Para isso, envie um e-mail para [e-mail].

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

Você vai receber uma resposta no seu 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.

Importante: os usuários que podem instalar e usar o complemento podem atualizar os links para anexos de complemento assim que as configurações forem ativadas pela equipe do Google Sala de Aula. Por isso, é importante fornecer primeiro as configurações do complemento de teste em um ambiente de teste ou de desenvolvimento antes de fornecer qualquer configuração de produção.

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 com que o complemento está associado.
• LINK_UPGRADE_IFRAME_URL: o URL que precisa ser aberto no iframe de upgrade do link.
• HOST_1: um host que o Google Sala de Aula precisa detectar. Somente o esquema https é aceito.
• PATH_PREFIX_1 e PATH_PREFIX_2: prefixos de caminho associados a HOST_1 que o Google Sala de Aula precisa detectar e tentar atualizar.
• HOST_2: um host que o Google Sala de Aula precisa detectar. Somente o esquema https é aceito.
• PATH_PREFIX_3 e PATH_PREFIX_4: prefixos de caminho associados a HOST_2 que o Google Sala de Aula precisa detectar e tentar atualizar.

Experiência do usuário recomendada

Confira a seguir sugestões para implementar esse recurso.

Evitar trabalho extra para os professores

É altamente recomendável usar o iframe para facilitar o login, se necessário, ou mostrar um indicador de carregamento. Para oferecer a melhor experiência do usuário, o professor não deve receber solicitações de informações adicionais depois de aceitar o 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 ocorreu um erro.

Incluir mensagens de erro de acesso fáceis de entender

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