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á quatro tipos de iframe distintos. 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 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:

• O HTTPS é obrigatório. É altamente recomendável usar o TLS 1.2 ou mais recente e ativar o HTTP Strict Transport Security. Consulte este artigo MDN (em inglês) relacionado à segurança de transporte estrita.

• Ative a Política de Segurança de Conteúdo rigorosa. Consulte este artigo do OWASP e este artigo do MDN sobre a Política de Segurança de Conteúdo.

• Ative o atributo de cookie seguro. Consulte o atributo HttpOnly e este artigo do MDN sobre cookies (em inglês).

Configuração do URI do iFrame

O URI de configuração de anexo é o que o iframe de descoberta de anexos carrega e é onde os professores começam o fluxo de criação de anexos de complementos em uma postagem do Google Sala de Aula. Ela pode ser definida no console do projeto do Google Cloud. Defina esse URI na página "API e serviço " > SDK do Google Workspace Marketplace > Configuração do app do seu projeto do Google Cloud.

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 literal de prefixo de string e não permite o uso de curingas no momento.

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 a login.

Parâmetros relacionados a anexos

Os parâmetros relacionados ao anexo 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 em que o anexo está anexado.

Incluído em todos os iframes.

Tipo de item

O valor itemType identifica o tipo de recurso em que

anexo está anexado. O valor da 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 do estudante de uma atividade específica.

Incluído com o studentWorkReviewUri.

Observação: é possível 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 diferentes cursos. Para mais informações, consulte Conteúdo copiado.

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 link.

URL a ser atualizado

A presença do valor urlToUpgrade implica que o

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 upgrade de links para anexos de complementos para mais detalhes.

Incluído no iframe do upgrade do 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 visita 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 ajudar a reduzir o atrito do 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.

do Google. Depois que o usuário fizer login no seu complemento pela primeira vez, o parâmetro login_hint será transmitido em cada visita subsequente ao complemento pelo mesmo usuário.

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 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 seus usuários logados, peça que o usuário faça login com um botão de login da marca Google.

Incluído em todos os iframes.

Observação: confira mais informações sobre a implementação do parâmetro login_hint e do fluxo de login nas páginas SSO, Login sem atrito e Procedimento para lidar com 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% da altura da janela menos 60 px para o cabeçalho superior
Largura	Máximo de 1600 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 de https://example.com/addon.
2. Um professor instala esse complemento e cria um aviso, uma atividade ou um 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 de src definido como https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456.
   1. O professor realiza um trabalho no iframe para fazer uma seleção de anexos.
5. Na seleção de anexos, o complemento envia um postMessage para o 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 pixels para o cabeçalho superior
Largura	Largura da janela de 100%

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 é de 312 px quando expandida e de 56 px quando retraída

Observação: os professores podem abrir o iframe de análise do trabalho do estudante para um estudante que não tenha visualizado o anexo do complemento antes. Nesse caso, o complemento pode ainda não estar ciente desse estudante e mostrar uma mensagem adequada.

Link Upgrade iframe

Dimensão	Descrição
Obrigatório	Sim, se o complemento oferecer suporte ao upgrade de links para anexos de 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 1600 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 upgrade de link

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 precisa tentar atualizar para um anexo de complemento:
   • O host é example.com e o prefixo do caminho é /quiz.
2. Um professor cria um aviso, uma atividade ou um 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 de URL fornecido. Em seguida, o professor é instruído a fazer upgrade do link para um anexo de complemento.

4. O Google 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. Avalie os parâmetros de consulta transmitidos no iframe e faça uma chamada para o endpoint CreateAddOnAttachment. O parâmetro de consulta urlToUpgrade é codificado em URI quando transmitido no iframe. É necessário decodificar o parâmetro para extraí-lo no formato original. O JavaScript, por exemplo, oferece a função decodeURIComponent().

6. Ao criar um anexo de complemento 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 aceita apenas 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

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 aconteça. 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 responsável por emitir o evento postMessage de fechamento. Como observação, o hiperlink "Abrir no nome do parceiro" está sendo removido para que os usuários não criem guias dessa forma em breve.

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 recurso a seguir

• allow="microphone *"

Bloqueio de cookies de terceiros

O bloqueio de cookies de terceiros dificulta a manutenção de uma sessão de login em um iframe. Consulte https://www.cookiestatus.com para saber o estado atual do bloqueio de cookies em diferentes navegadores. Claro, 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 próprio. Alguns navegadores concedem acesso a cookies criados no 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 apps da Web de página única que não dependem de cookies.

Espera-se que mais restrições de cookies sejam implementadas em versões futuras do navegador. Crie solicitações de recursos para enviar feedback ao Google sobre como reduzir o aumento necessário para os parceiros.

Ativar a detectabilidade de complementos usando expressões regulares de URL

Os professores costumam criar atividades com anexos de link. Para promover o uso do complemento, especifique expressões regulares que correspondem 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 descartável que incentiva o uso do seu complemento. O usuário só vai ver a caixa de diálogo se o complemento já estiver instalado na conta dele.

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 forem muito amplas ou conflitarem com outro complemento, elas poderão ser modificadas para serem mais restritas ou distintas.

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

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

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 seu complemento.