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

Uma maneira de adicionar conteúdo de terceiros ao Google Sala de Aula é colando um link como um Link anexo na página de criação da atividade. Para continuar usando os recursos que os professores já conhecem, configure seu complemento e permita que eles façam upgrade de um link para um anexo de complemento.

Visão geral

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

Depois que o professor concorda em fazer upgrade do link para um anexo de complemento, o iframe de upgrade de link é iniciado com os seguintes parâmetros de consulta:

  • courseId
  • itemId (renomeado de postId)
  • itemType (novo)
  • addOnToken
  • login_hint ou hd
  • urlToUpgrade (novo)

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 de complementos precisa ser criado. Em seguida, use 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 exibir uma tela de carregamento para indicar ao professor que o anexo de complementos 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 faria normalmente.

Detalhes da implementação técnica

Esta seção destaca alguns detalhes técnicos importantes do recurso.

Leia 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 obtê-lo em sua forma original. Se você estiver usando JavaScript, por exemplo, será possível usar a função decodeURIComponent() para fazer isso.

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

Detalhes da configuração

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

  • URL do iframe de upgrade do link: é o URL que é aberto no iframe quando um professor concorda em fazer o 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.
    • 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 nem fragmentos de URL.
    • No momento, os prefixos de caminho são compatíveis com caracteres curinga, 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 componentes de prefixo de caminho corresponde apenas a um único 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 de iframe do upgrade de link e os padrões de URL do complemento de teste ou produção pelo e-mail classroom-link-upgrade-external@google.com.

Primeiro, você pode fornecer configurações para seu complemento particular e qualquer ambiente de teste ou desenvolvimento de sua propriedade. A equipe do Google Sala de Aula pode ativar essas configurações antes de habilitar as configurações de produção para que você teste o fluxo no seu domínio de demonstração. Você vai 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 do upgrade do link.
  • HOST_1: um host que o Google Sala de Aula precisa 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 precisa detectar e tentar fazer upgrade.
  • HOST_2: um host que o Google Sala de Aula precisa 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 precisa detectar e tentar fazer upgrade.

Confira a seguir algumas sugestões que precisam ser consideradas ao implementar esse recurso.

Evite tarefas extras para os professores

Recomendamos que você use o iframe para facilitar o login, se necessário, ou para exibir um indicador de carregamento. Para melhorar a experiência do usuário, o professor não vai precisar fornecer 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 do upgrade de link para coletar as informações adicionais de que precisa. O iframe também pode ser usado para informar ao professor se não for possível fazer o upgrade do link ou se ocorrer um erro.

Incluir mensagens de erro de acesso fácil de usar

Se os professores colarem e fizerem upgrade de um link ao qual não têm acesso, exiba 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.