Detalhes de iframe e parâmetro de consulta

Os complementos do Google Sala de Aula são carregados em um iframe para oferecer ao usuário final uma experiência perfeita e conveniente. Há cinco tipos diferentes de iframe. Consulte as páginas de iframes no diretório "Jornadas do usuário" para ter uma visão geral da finalidade e da aparência de cada iframe.

Diretrizes de segurança de iframe

Os desenvolvedores precisam seguir as práticas recomendadas do setor para proteger o iframe. No entanto, também é necessário incorporar determinadas interações da API no fluxo de usuários para confirmar que você tem credenciais válidas e pode identificar corretamente a função do usuário no curso.

Configuração do aplicativo de servidor

Para proteger o iframe, recomendamos as seguintes configurações de servidor:

Parâmetros de consulta

Os iframes transmitem informações importantes para o complemento como parâmetros de consulta. Há duas categorias de parâmetros: relacionados a anexos e relacionados a login.

Os parâmetros relacionados a anexos fornecem ao complemento informações sobre o curso, a atividade, o anexo do complemento, o envio do estudante e um token de autorização.

ID do curso

O valor courseId é um identificador do curso.

Incluído em todos os iframes.

ID do item

O valor itemId é um identificador do Announcement, CourseWork ou CourseWorkMaterial a que este anexo está vinculado.

Incluído em todos os iframes.

Tipo de item

O valor itemType identifica o tipo de recurso a que este anexo está associado. O valor de string transmitido é "announcements", "courseWork" ou "courseWorkMaterials".

Incluído em todos os iframes.

ID do anexo

O valor attachmentId é um identificador do anexo.

Incluído nos iframes teacherViewUri, studentViewUri e studentWorkReviewUri.

ID do envio

O valor submissionId é um identificador do trabalho do estudante, mas precisa ser usado em combinação com o attachmentId para identificar o trabalho de um estudante em uma atividade específica.

Incluído no studentWorkReviewUri.

Token de complemento

O valor addOnToken é um token de autorização usado para fazer chamadas addOnAttachments.create e criar o complemento.

Incluído no iframe de descoberta de anexos e no iframe de upgrade de links.

URL a ser atualizado

A presença do valor urlToUpgrade implica que o professor incluiu um anexo de link na atividade e concordou em fazer upgrade para um anexo de complemento. Se você ainda não tiver esse recurso configurado, consulte o guia sobre como fazer upgrade de links para adicionar anexos para mais detalhes.

Incluído no iframe de upgrade de link.

O parâmetro de consulta login_hint fornece informações sobre o usuário do Google Sala de Aula que está acessando a página da Web do complemento. Esse parâmetro de consulta é fornecido no URL do iframe src. Ele é enviado quando o usuário já usou seu complemento para reduzir o atrito no login do usuário final. É necessário processar esse parâmetro de consulta na implementação do complemento.

Dica de login

O login_hint é um identificador exclusivo da Conta do Google do usuário. Depois que o usuário fizer login no complemento pela primeira vez, o parâmetro login_hint será transmitido em cada visita subsequente ao complemento pelo mesmo usuário.

Há dois usos possíveis para o parâmetro login_hint:

  1. Transmita o valor login_hint durante o fluxo de autenticação para que o usuário não precise inserir as credenciais quando a caixa de diálogo de login aparecer. O usuário não está conectado automaticamente.
  2. Depois que o usuário fizer login, use esse parâmetro para comparar o valor com os usuários que já fizeram login no complemento. Se você encontrar uma correspondência, deixe o usuário conectado e evite mostrar um fluxo de login. Se o parâmetro não corresponder a nenhum dos seus usuários conectados, peça que o usuário faça login com um botão de login da marca Google.

Incluído em todos os iframes.

iframe de descoberta de anexos

Dimensão Descrição
Obrigatório Sim
URI Fornecido nos metadados do complemento
Parâmetros de consulta courseId, itemId, itemType, addOnToken e login_hint.
Altura 80% da altura da janela menos 60 px para o cabeçalho superior
Largura Máximo de 1.600 px
90% da largura da janela quando a janela <= 600 px de largura
80% da largura da janela quando a janela > 600 px de largura

Exemplo de cenário de descoberta de anexos

  1. Um complemento do Google Sala de Aula é registrado no Google Workspace Marketplace com um URI de descoberta de anexos https://example.com/addon.
  2. Um professor instala esse complemento e cria um novo aviso, atividade ou material em um dos cursos. Por exemplo, itemId=234, itemType=courseWork e courseId=123.
  3. Ao configurar esse item, o professor escolhe o complemento recém-instalado como um anexo.
  4. O Google Sala de Aula cria um iframe com o URL src definido como https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456.
    1. O professor trabalha no iframe para fazer uma seleção de anexos.
  5. Ao selecionar um anexo, o complemento envia um postMessage para o Google Sala de Aula e fecha o iframe.

iframes teacherViewUri e studentViewUri

Dimensão Descrição
Obrigatório Sim
URI teacherViewUri ou studentViewUri
Parâmetros de consulta courseId, itemId, itemType, attachmentId e login_hint.
Altura 100% da altura da janela menos 140 px para o cabeçalho superior
Largura 100% da largura da janela

iframe studentWorkReviewUri

Dimensão Descrição
Obrigatório Não (determina se este é um anexo do tipo atividade)
URI studentWorkReviewUri
Parâmetros de consulta courseId, itemId, itemType, attachmentId, submissionId e login_hint.
Altura 100% da altura da janela menos 168 px para o cabeçalho superior
Largura 100% da largura da janela menos a largura da barra lateral<> a barra lateral tem 312 px quando expandida e 56 px quando recolhida
Dimensão Descrição
Obrigatório Sim, se o complemento for compatível com o upgrade de links para anexos de complementos.
URI Fornecido nos metadados do complemento
Parâmetros de consulta courseId, itemId, itemType, addOnToken, urlToUpgrade e login_hint.
Altura 80% da altura da janela menos 60 px para o cabeçalho superior
Largura Máximo de 1.600 px
90% da largura da janela quando a janela <= 600 px de largura
80% da largura da janela quando a janela > 600 px de largura
  1. Um complemento do Google Sala de Aula é registrado com um URI de upgrade de link de https://example.com/upgrade. Você forneceu os seguintes padrões de prefixo de host e caminho para Anexos de link que o Google Sala de Aula deve tentar atualizar para um anexo de complemento:
    • O host é example.com e o prefixo do caminho é /quiz.
  2. Um professor cria um novo aviso, atividade ou material em um dos cursos dele. Por exemplo, itemId=234, itemType=courseWork e courseId=123.
  3. Um professor cola um link, https://example.com/quiz/5678, na caixa de diálogo "Anexo de link" que corresponde a um padrão de URL fornecido por você. O professor recebe uma solicitação para fazer upgrade do link para um anexo de complemento.

  4. A Sala de Aula inicia o iframe de upgrade de link com o URL definido como https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678.

  5. Você avalia os parâmetros de consulta transmitidos no iframe e faz uma chamada para o endpoint CreateAddOnAttachment. O parâmetro de consulta urlToUpgrade é codificado por URI quando transmitido no iframe. É necessário decodificar o parâmetro para obtê-lo na forma original. O JavaScript, por exemplo, oferece a função decodeURIComponent().

  6. Se um anexo de complemento for criado com sucesso de um link, envie um postMessage para o Google Sala de Aula e feche o iframe.

Fechar o iframe

O iframe pode ser fechado na ferramenta de aprendizado enviando um postMessage com o payload {type: 'Classroom', action: 'closeIframe'}. O Google Sala de Aula só aceita esse postMessage do host_name+port correspondente ao URI original que foi aberto.

<button id="close">Send message to close iframe</button>
<script>
  document.querySelector('#close')
    .addEventListener('click', () => {
        window.parent.postMessage({
            type: 'Classroom',
            action: 'closeIframe',
        }, '*');
    });
</script>

Fechar o iframe no próprio iframe

O domínio+porta da página que envia o evento postMessage precisa ser o mesmo do URI usado para iniciar o iframe. Caso contrário, a mensagem será ignorada. Uma solução alternativa é redirecionar de volta para uma página no domínio original que não faz nada além de enviar o evento postMessage.

Fechar iframe em uma nova guia

As proteções entre domínios impedem que isso funcione. Uma solução alternativa é processar as comunicações entre o iframe e a nova guia por conta própria e deixar que o iframe seja o responsável por emitir o evento de fechamento postMessage. Como observação, o hiperlink "Abrir em [Nome do parceiro]" será removido para que os usuários não criem guias dessa forma no futuro próximo.

Restrições

Todos os iframes são abertos com os seguintes atributos de sandbox:

  • allow-popups
  • allow-popups-to-escape-sandbox
  • allow-forms
  • allow-scripts
  • allow-storage-access-by-user-activation
  • allow-same-origin

e a seguinte política de recursos:

  • allow="microphone *"

O bloqueio de cookies de terceiros dificulta a manutenção de uma sessão conectada em um iframe. Consulte https://www.cookiestatus.com (link em inglês) para saber o estado atual do bloqueio de cookies em diferentes navegadores. É claro que esse problema não é exclusivo dos complementos do Google Sala de Aula e afeta todos os sites que usam iframes de terceiros. Muitos dos nossos parceiros já enfrentaram esse problema.

Algumas soluções alternativas gerais:

  • Abra uma nova guia para criar o cookie em um contexto de terceiros. Alguns navegadores concedem acesso a cookies criados em um contexto próprio enquanto estão em um contexto de terceiros.
  • Peça ao usuário para permitir cookies de terceiros. Isso nem sempre é possível com todos os usuários.
  • Projete aplicativos da Web de uma só página que não dependam de cookies.

Mais restrições de cookies são esperadas em versões futuras do navegador. Crie solicitações de recursos para enviar feedback ao Google sobre como reduzir o aumento exigido pelos parceiros.

Ativar a capacidade de descoberta de complementos usando expressões regulares de URL

Os professores costumam criar atividades com anexos de links. Para promover o uso do seu complemento, especifique expressões regulares que correspondam aos URLs de recursos que podem ser acessados no complemento. Um professor que anexa um link que corresponde a uma das suas expressões regulares vê uma caixa de diálogo dispensável incentivando a testar seu complemento. A caixa de diálogo só aparece se o complemento já estiver instalado na conta.

Se você quiser oferecer esse comportamento aos professores, forneça aos seus contatos do Google as expressões regulares adequadas. Se as expressões regulares fornecidas forem muito amplas ou entrarem em conflito com outro complemento, elas poderão ser modificadas para serem mais restritas ou distintas.

Professor selecionando um anexo de link Figura 1. Professor selecionando um anexo de link para uma nova atividade.

Professor colando o link Figura 2. O professor cola um link de uma fonte de terceiros. O professor já instalou o complemento do Google Sala de Aula de terceiros.

Caixa de diálogo de capacidade de descoberta de regex Figura 3. A caixa de diálogo interativa apresentada ao professor quando o link colado corresponde a uma expressão regular especificada pelo desenvolvedor terceirizado.

Se um professor selecionar "Testar agora" no pop-up, como mostrado na figura 3, ele será redirecionado para o iframe de descoberta de anexos do complemento.