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 distintos de iframe. Consulte as páginas de iframes no diretório Jornadas do usuário para 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, você também precisa incorporar determinadas interações de API no fluxo do usuário para confirmar que tem credenciais válidas e pode identificar corretamente o papel do usuário no curso.

Configuração do aplicativo do servidor

Para proteger o iframe, recomendamos as seguintes configurações do 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 aluno 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 ao qual esse anexo está anexado.

Incluído em todos os iframes.

Tipo de item

O valor itemType identifica o tipo de recurso ao qual esse anexo está anexado. O valor da string transmitida é "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 aluno, mas precisa ser usado em combinação com o attachmentId para identificar o trabalho do aluno de uma atividade específica.

Incluído no studentWorkReviewUri.

Token do complemento

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

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

URL para upgrade

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 este recurso configurado, consulte o guia sobre como fazer upgrade de links para anexos de complementos para mais detalhes.

Incluído no iframe de upgrade de links.

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 src do iframe. Ele é enviado quando o usuário já usou o complemento para ajudar a reduzir o atrito de 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 faz login no complemento pela primeira vez, o parâmetro login_hint é 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 faz login 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, poderá deixar o usuário conectado e evitar mostrar um fluxo de login. Se o parâmetro não corresponder a nenhum dos usuários conectados, peça que o usuário faça login com um botão de login com a 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 tem <= 600 px de largura
80% da largura da janela quando a janela tem > 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 de 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 realiza o trabalho no iframe para fazer uma seleção de anexos.
  5. Na seleção de anexos, o complemento envia um postMessage ao Google Sala de Aula para fechar 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 é 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 upgrade de links para anexos de complementos for compatível com o complemento.
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 tem <= 600 px de largura
80% da largura da janela quando a janela tem > 600 px de largura
  1. Um complemento do Google Sala de Aula é registrado com um URI de upgrade de links de https://example.com/upgrade. Você forneceu os seguintes padrões de prefixo de host e caminho para anexos de links que o Google Sala de Aula precisa tentar fazer upgrade 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. 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 de anexo de link que corresponde a um padrão do URL fornecido. Em seguida, o professor é solicitado a fazer upgrade do link para um anexo de complemento.

  4. O Google Sala de Aula inicia o iframe de upgrade de links 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 CreateAddOnAttachment endpoint. O parâmetro de consulta urlToUpgrade é codificado por URI quando transmitido no iframe. É necessário decodificar o parâmetro para recebê-lo no formato original. O JavaScript, por exemplo, oferece a função decodeURIComponent().

  6. Após a criação de um anexo de complemento a partir de um link, você envia um postMessage ao Google Sala de Aula para fechar 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 do iframe

O domínio + porta da página que envia o evento postMessage precisa ter o mesmo domínio + porta 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 o 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 o iframe responsável por emitir o evento postMessage de fechamento. Como uma observação, o hiperlink "Abrir no nome do parceiro" está sendo 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 sobre 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á encontraram esse problema.

Algumas soluções alternativas gerais são:

  • Abra uma nova guia para criar o cookie em um contexto primário. Alguns navegadores concedem acesso a cookies criados no contexto primário 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.
  • Crie aplicativos da Web de página única 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 esforço 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 complemento, você pode especificar expressões regulares que correspondam a 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-o a testar o complemento. A caixa de diálogo só aparece se o complemento já estiver instalado na conta.

Se você quiser fornecer esse comportamento aos professores, forneça as expressões regulares adequadas aos seus contatos do Google. 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. Professor colando 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 de terceiros.

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