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 simples e conveniente. Há quatro tipos de iframe diferentes. Consulte as páginas de iframe no diretório de jornadas do usuário para ter uma visão geral da finalidade e da aparência de cada iframe.

Diretrizes de segurança do iframe

Os parceiros precisam seguir as práticas recomendadas do setor para proteger o iframe. Para proteger o iframe, nossa equipe de segurança recomenda o seguinte:

• HTTPS é obrigatório. É altamente recomendável usar o TLS 1.2 ou mais recente e ativar o HTTP Strict Transport Security. Consulte este artigo da MDN relacionado sobre o Strict Transport Security.

• Ative a Política estrita de segurança de conteúdo. Consulte este artigo do OWASP e este artigo da MDN sobre a Política de Segurança de Conteúdo relacionado.

• Ative o atributo de cookie seguro. Consulte o atributo HttpOnly e este artigo MDN de cookies relacionado.

Configuração de URI do iframe

O URI de configuração de anexos é carregado pelo iframe de descoberta de anexos. É nele que os professores iniciam o fluxo de criação de anexos de complementos em uma postagem do Google Sala de Aula. Ele pode ser definido no console do projeto do Google Cloud. Defina esse URI na página "API e serviço " do seu projeto do Google Cloud > SDK do Google Workspace Marketplace > Configuração do app.

Os prefixos de URI de anexo permitidos são usados para validar os URIs definidos em AddOnAttachment usando os métodos *.addOnAttachments.create e *.addOnAttachments.patch. A validação é uma correspondência de prefixo de string literal e não permite o uso de caracteres curinga no momento.

Parâmetros de consulta

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

Parâmetros relacionados a anexos

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

ID do curso

O valor courseId é um identificador para o curso.

Incluído com todos os iframes.

ID do item

O valor itemId é um identificador do Announcement,

CourseWork ou CourseWorkMaterial em que este anexo está anexado.

Incluído com todos os iframes.

Tipo de item

O valor itemType identifica o tipo de recurso em que esta

está anexado. O valor da string transmitida é "announcements", "courseWork" ou "courseWorkMaterials".

Incluído com todos os iframes.

ID do anexo

O valor attachmentId é um identificador para o anexo.

Incluído nos iframes teacherViewUri, studentViewUri e studentWorkReviewUri.

ID do envio

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

Incluído no studentWorkReviewUri.

Observação: você pode usar uma chave composta de submissionId e attachmentId para identificar o trabalho do estudante caso o mesmo anexo seja atribuído ao mesmo estudante em cursos diferentes. Para saber mais, consulte conteúdo copiado.

Token de complemento

O valor addOnToken é um token de autorização usado para fazer

addOnAttachments.create para criar o complemento.

Incluído com o iframe de descoberta de anexos e o iframe de upgrade de link.

URL para fazer upgrade

A presença do valor urlToUpgrade implica que o

professor incluiu um anexo de link na atividade e concordou em fazer upgrade dele para um anexo de complemento. Se você ainda não configurou esse recurso, consulte o guia sobre como fazer upgrade de links para anexos de complementos para saber mais.

Incluído no iframe de upgrade de link.

Parâmetros relacionados ao login

O parâmetro de consulta login_hint fornece informações sobre o usuário do Google Sala de Aula que acessa 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 seu complemento para reduzir o atrito no login. É 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 Google. Depois que o usuário fizer login no complemento pela primeira vez, o parâmetro login_hint será transmitido pelo mesmo usuário em cada visita subsequente ao complemento.

Há dois possíveis usos 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 é conectado automaticamente.
2. Depois que o usuário fizer login, use esse parâmetro para comparar o valor com qualquer usuário que você já tenha feito login no complemento. Se encontrar uma correspondência, é possível manter o usuário conectado e evitar a exibição do fluxo de login. Se o parâmetro não corresponder a nenhum dos usuários conectados, solicite que ele faça login com um botão de login com a marca do Google.

Incluído com todos os iframes.

Observação: há mais informações sobre a implementação do parâmetro login_hint e o fluxo de login no SSO, Login sem atrito e Gerenciar instruções de logins repetidos.

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% de altura da janela menos 60 px para o cabeçalho superior
Largura	Máximo de 1.600 px 90% de largura da janela quando a janela for menor que 600 px de largura 80% de largura da janela quando a janela for maior que 600 px

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 este 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 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 faz um trabalho dentro do iframe para selecionar o anexo.
5. Na seleção do anexo, o complemento envia um postMessage ao Google Sala de Aula para fechar o iframe.

Iframes professoresViewUri 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% de altura da janela menos 140 px para o cabeçalho superior
Largura	100% de largura da janela

Iframe do studentWorkReviewUri

Dimensão	Descrição
Obrigatório	Não (determina se este é um anexo do tipo de atividade)
URI	studentWorkReviewUri
Parâmetros de consulta	courseId, itemId, itemType, attachmentId, submissionId e login_hint.
Altura	100% de altura da janela menos 168 px para o cabeçalho superior
Largura	A largura de 100% da janela menos a largura da barra lateral<> é de 312 px quando expandida e 56 px quando recolhida

Observação :os professores podem abrir o iframe "Revisão dos trabalhos dos estudantes" de um estudante que não viu o anexo do complemento antes. Nesse caso, talvez o complemento ainda não conheça esse estudante e mostre uma mensagem adequada.

iframe de upgrade de link

Dimensão	Descrição
Obrigatório	Sim, se o upgrade de links para anexos de complementos for compatível com seu complemento.
URI	Fornecido nos metadados do complemento
Parâmetros de consulta	courseId, itemId, itemType, addOnToken, urlToUpgrade e login_hint.
Altura	80% de altura da janela menos 60 px para o cabeçalho superior
Largura	Máximo de 1.600 px 90% de largura da janela quando a janela for menor que 600 px de largura 80% de largura da janela quando a janela for maior que 600 px

Exemplo de cenário de upgrade de link

1. Um complemento do Google Sala de Aula está 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 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. O professor cola um link, https://example.com/quiz/5678, na caixa de diálogo "Anexo do link" que corresponde a um padrão de URL fornecido por você. O professor será solicitado a fazer upgrade do link para um anexo de complemento.

4. O Google Sala de Aula inicia o iframe do 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 pelo URI quando transmitido no iframe. Você precisa decodificar o parâmetro para recebê-lo na forma original. O JavaScript, por exemplo, oferece a função decodeURIComponent().

6. Ao criar um anexo de complemento usando um link, você envia uma 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+porta correspondente ao URI original 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

O domínio e a porta da página que envia o evento postMessage precisam ter o mesmo domínio + porta que o 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 mais do que 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 ser responsável por emitir o evento de fechamento postMessage. Como observação, o hiperlink "Abrir no nome do parceiro" será removido para que os usuários não criem guias dessa maneira 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 política de recursos a seguir

• allow="microphone *"

Bloqueio de cookies de terceiros

Lembre-se de que o bloqueio de cookies de terceiros dificulta a manutenção de uma sessão conectada em um iframe. Consulte https://www.cookiestatus.com (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 são iframe de terceiros. Muitos dos nossos parceiros já enfrentaram esse problema.

Algumas soluções gerais são:

• Abra uma nova guia para criar o cookie em um contexto próprio. Alguns navegadores concedem acesso a cookies criados em um contexto primário, enquanto em um contexto de terceiros.
• Pedir para o usuário permitir cookies de terceiros. Isso nem sempre é possível com todos os usuários.
• Crie 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 dos navegadores. Crie solicitações de recursos para enviar feedback ao Google sobre como reduzir o aumento exigido pelos parceiros.

Ativar a detecção de complementos usando expressões regulares de URL

Os professores costumam criar atividades com links anexados. Para promover o uso do seu complemento, especifique expressões regulares que correspondam aos URLs dos 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ó vai aparecer se o complemento já estiver instalado na conta.

Se você quiser aplicar esse comportamento aos professores, forneça as expressões regulares apropriadas para 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.

Figura 1. a professora selecionando um anexo com um link para uma nova atividade.

Figura 2. a professora colando um link de uma fonte de terceiros. Ela já instalou o complemento de terceiros do Google Sala de Aula.

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 o professor selecionar "Testar agora" no pop-up, como mostrado na Figura 3, ele será redirecionado para o iframe de descoberta de anexos do seu complemento.