Detalhes de iframe e parâmetro de consulta

Os complementos do Google Sala de Aula são carregados em um iframe para fornecer ao usuário final uma experiência integrada e conveniente. Há quatro tipos de iframes. Consulte as páginas de iframe no diretório de jornadas do usuário para ter uma visão geral do propósito 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:

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

• Ative a Política de Segurança de Conteúdo Estrita. Consulte este artigo do OWASP e este artigo relacionado da MDN sobre a Política de Segurança de Conteúdo (links em inglês).

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

Configuração do URI de 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 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 curingas 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 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 da postagem (descontinuado)

O valor postId é um identificador da postagem (comunicado, trabalho ou material do curso) em que o anexo está anexado.

Incluído em todos os iframes.

Descontinuado:o ID da postagem foi descontinuado. Use o ID do item.

ID do item

O valor itemId é um identificador do Announcement, CourseWork ou CourseWorkMaterial em que 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 transmitido é "announcements", "courseWork" ou "courseWorkMaterials".

Incluído em todos os iframes.

ID do anexo

O valor attachmentId é um identificador do anexo.

Incluído com os iframes teacherViewUri, studentViewUri e studentWorkReviewUri.

ID de envio

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

Incluído no 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 de complemento

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

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

URL para upgrade

A presença do valor urlToUpgrade indica 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 mais detalhes.

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 do iframe src. Ele é enviado quando o usuário já usou seu complemento para ajudar a 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 Google. Depois que o usuário fizer login no seu complemento pela primeira vez, o parâmetro login_hint será transmitido em cada acesso 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 é conectado automaticamente.
2. Depois que o usuário fizer login, use esse parâmetro para comparar o valor com os usuários que você já fez login no complemento. Se encontrar uma correspondência, você poderá deixar o usuário conectado e evitar a exibição de um fluxo de login. Se o parâmetro não corresponder a nenhum dos seus usuários conectados, solicite que ele faça login com um botão de login da marca do Google.

Incluído em todos os iframes.

Observação: saiba 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 Tutorial sobre como processar logins repetidos.

Iframe Discovery de anexo

Dimensão	Descrição
Obrigatório	Sim
URI	Fornecidos nos metadados do complemento
Parâmetros de consulta	courseId, postId (descontinuados), itemId, itemType, addOnToken e login_hint.
Altura	80% da altura da janela menos 60px para o cabeçalho superior
Largura	Máximo de 1600 px 90% de largura da janela quando a janela <= 600 px de largura 80% da largura da 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 novo aviso, tarefa 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 faz um trabalho no iframe para selecionar um anexo.
5. Quando o anexo é selecionado, 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, postId (descontinuados), 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 de tipo de atividade)
URI	studentWorkReviewUri
Parâmetros de consulta	courseId, postId (descontinuado), 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 é 312 px quando expandida e 56 px quando recolhida

Observação: os professores podem abrir o iframe de avaliação dos trabalhos dos alunos que não tenham visto o anexo de complemento. Nesse caso, talvez o complemento ainda não conheça o estudante e mostre uma mensagem adequada.

Vincular o iframe do upgrade

Dimensão	Descrição
Obrigatório	Sim, se o complemento permitir o upgrade de links para anexos.
URI	Fornecidos nos metadados do complemento
Parâmetros de consulta	courseId, postId (descontinuado), itemId, itemType, addOnToken, urlToUpgrade e login_hint.
Altura	80% da altura da janela menos 60px para o cabeçalho superior
Largura	Máximo de 1600 px 90% de largura da janela quando a janela <= 600 px de largura 80% da largura da 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ê informou os seguintes padrões de prefixo de host e caminho para Anexos de link e o Google Sala de Aula vai 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, tarefa 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 "Anexo de link" que corresponde a um padrão de URL que você forneceu. O professor é 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&postId=234&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 por URI quando transmitido no iframe. Você precisa decodificar o parâmetro para obtê-lo em sua forma original. O JavaScript, por exemplo, oferece a função decodeURIComponent().

6. Após a criação de 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 pela ferramenta de aprendizado enviando um postMessage com o payload {type: 'Classroom', action: 'closeIframe'}. O Google Sala de Aula só aceita essa postMessage do host_name+porta 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 iframe do iframe

O domínio + a porta da página que envia o evento postMessage precisa ter o mesmo domínio e porta que o URI usado para iniciar o iframe. Caso contrário, a mensagem será ignorada. Uma solução alternativa é redirecionar para uma página no domínio original que não faz nada mais do que 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 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 maneira 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 seguinte política de recursos

• allow="microphone *"

Bloqueio de cookies de terceiros

O bloqueio de cookies de terceiros dificulta a manutenção de uma sessão conectada em um iframe. Consulte https://www.cookiestatus.com para saber o estado atual do bloqueio de cookies em diferentes navegadores. Obviamente, 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 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 uma única página que não dependem 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 detecção de complementos usando expressões regulares de URL

Os professores frequentemente criam tarefas com anexos de link. Para promover o uso do complemento, especifique expressões regulares que correspondam aos URLs dos recursos que podem ser acessados no complemento. Um professor anexando um link que corresponde a uma das suas expressões regulares vai encontrar uma caixa de diálogo que pode ser dispensada, incentivando-o a testar o complemento. Ele só verá a caixa de diálogo se o complemento já estiver instalado na conta.

Se você quiser apresentar esse comportamento aos professores, ofereça as expressões regulares adequadas 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 seleciona um anexo de link para uma nova atividade.

Figura 2. um professor colando um link de uma fonte de terceiros. o professor já tiver instalado o complemento 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 um professor selecionar "Testar agora" na janela pop-up, como mostrado na Figura 3, ele será redirecionado para o iframe de descoberta de anexos do complemento.