Detalhes de iframe e parâmetro de consulta

Os complementos do Google Sala de Aula são carregados em um iframe para fornecer para o usuário final com uma experiência do usuário simples e conveniente. Há quatro tipos Tipos de iframe consultar as páginas de iframe no diretório de jornadas do usuário para 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:

Configuração de URI do iframe

O URI de configuração de anexos é carregado pelo iframe de descoberta de anexos. é quando os professores iniciam o fluxo de criação de anexos de complementos em um Postagem no Google Sala de Aula. Ele pode ser definido no console do projeto do Google Cloud. Defina esse URI na API do projeto do Google Cloud e Serviço > SDK do Google Workspace Marketplace > página Configuração do aplicativo.

Configuração de URI do iframe

Os Prefixos URI de anexo permitidos são usados para validar os URIs definidos em AddOnAttachment usando os métodos *.addOnAttachments.create e métodos *.addOnAttachments.patch. A validação é um 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. Existem duas categorias de parâmetros: relacionados a anexos e relacionados ao login parâmetros.

Os parâmetros relacionados ao anexo fornecem ao complemento informações sobre a a atividade, o anexo de complementos, o envio do estudante 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 teacherViewUri, studentViewUri e Iframes 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 o trabalho de um estudante em uma tarefa específica.

Incluído no studentWorkReviewUri.

.
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 upgrade de link iframe.

URL para fazer upgrade

A presença do valor urlToUpgrade implica que o

professor incluiu um anexo de link na tarefa e concordou para fazer upgrade para um anexo de complemento. Caso ainda não tenha configurado, consulte o guia sobre como fazer upgrade de links para complementos anexos para mais detalhes.

Incluído no iframe de upgrade de link.

O parâmetro de consulta login_hint fornece informações sobre a Usuário do Google Sala de Aula acessando a página da Web do complemento. Esse parâmetro de consulta é fornecido no URL src de iframe. Ele é enviado quando o usuário já usou seu complemento para reduzir o atrito no login do usuário final. Você precisa gerenciar 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 em seu complemento pela primeira vez, o O parâmetro login_hint é transmitido em cada visita subsequente ao complemento por: ao 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 o usuário não precisa inserir as credenciais na caixa de diálogo de login. aparece. O usuário não é conectado automaticamente.
  2. Depois que o usuário fizer login, use esse parâmetro para comparar a para os usuários que já devem ter feito login no complemento. Se encontrar uma correspondência, deixe o usuário conectado e evite mostrar uma fluxo de login. Se o parâmetro não corresponder a nenhuma das opções usuários, solicite que eles façam login com um login com a marca do Google botão.

Incluído com 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 e 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 largura
80% da largura da janela quando a janela for > 600px de largura

Exemplo de cenário de descoberta de anexos

  1. Um complemento do Google Sala de Aula está 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 em um dos cursos. Por exemplo, itemId=234, itemType=courseWork e courseId=123.
  3. Ao configurar o 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 dentro do iframe para selecionar o anexo.
  5. Na seleção do anexo, o complemento envia um postMessage para 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 e 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 e itemType. attachmentId, submissionId e login_hint.
Altura 100% de 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 expandido e 56px quando recolhido

Dimensão Descrição
Obrigatório Sim, se o upgrade de links para anexos de complementos for compatíveis com seu complemento.
URI Fornecido nos metadados do complemento
Parâmetros de consulta courseId, itemId e 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 largura
80% da largura da janela quando a janela for > 600px de largura
  1. Um complemento do Google Sala de Aula está registrado com um URI de upgrade de link de https://example.com/upgrade: Você forneceu o seguinte host e caminho padrões de prefixo para anexos de links que o Google Sala de Aula precisa tentativa de 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 nos cursos. Por exemplo, itemId=234, itemType=courseWork e courseId=123
  3. Um professor cola um link, https://example.com/quiz/5678, no link caixa de diálogo de anexo que corresponda a um padrão de URL fornecido por você. O professor é será solicitado a atualizar o link para um anexo de complemento.

  4. O Google Sala de Aula inicia o iframe de upgrade de link com o URL definido. para 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 passados no iframe e faz uma chamada para o endpoint CreateAddOnAttachment. Observe que a consulta urlToUpgrade é codificado na URI quando transmitido no iframe. Você precisa decodificar para obtê-lo em sua forma original. 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 no Google Sala de Aula para fechar o iframe.

Fechar o iframe

O iframe pode ser fechado na ferramenta de aprendizado enviando um postMessage com do payload {type: 'Classroom', action: 'closeIframe'}. O Google Sala de Aula só aceita postMessage de 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 e a porta da página que envia o evento postMessage precisam ter o mesmo domínio+porta como o URI usado para iniciar o iframe. Caso contrário, a mensagem é ignorado. 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 é lidar com comunicações entre o iframe e a nova guia por conta própria e deixar que o iframe será responsável por emitir o evento de fechamento postMessage. Como um lado o hiperlink "Abrir em Nome do parceiro" está sendo removido para que os usuários não criar 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 recursos a seguir

  • allow="microphone *"

Esteja ciente de que o bloqueio de cookies de terceiros dificulta a manutenção de uma conectada em um iframe. Consulte https://www.cookiestatus.com no o estado atual do bloqueio de cookies em diferentes navegadores. Claro, isso não é exclusivo dos complementos do Google Sala de Aula e afeta todos os sites que 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 no contexto primário enquanto contexto de terceiros.
  • Pedir para o usuário permitir cookies de terceiros. Nem sempre isso é 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. Criar solicitações de recursos para enviar feedback ao Google sobre como reduzir o aumento necessário 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 complemento, especifique expressões regulares que correspondam aos URLs dos recursos que pode ser acessado no seu complemento. um professor anexa um link que corresponde a um. das expressões regulares vê uma caixa de diálogo dispensável incentivando-os a tentar seu complemento. Eles só verão a caixa de diálogo se o complemento já estiver instalado para a conta.

Para informar os professores sobre este comportamento, informe sua contatos com as expressões regulares apropriadas. Se as expressões regulares que você fornecer forem excessivamente abrangentes ou entrarem em conflito com outro complemento, eles podem modificados para serem mais restritos ou distintos.

O professor seleciona o anexo de link Figura 1. Professor selecionando um link anexo a uma nova atividade.

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

Caixa de diálogo de detecção de regex Figura 3. A caixa de diálogo interativa apresentada para o professor quando o link colado corresponder a uma expressão regular especificada por desenvolvedor terceirizado.

Se um professor selecionar "Testar agora" no pop, como mostrado na figura 3, eles redirecionado para o iframe de descoberta de anexos do seu complemento.