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 doAnnouncement
,CourseWork
ouCourseWorkMaterial
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 estaestá 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
estudentWorkReviewUri
.- ID do envio
O valor
submissionId
é um identificador do trabalho do estudante, mas deve ser usado em combinação comattachmentId
para identificar o trabalho do estudante em uma atividade específica.Incluído no
studentWorkReviewUri
.
- Token de complemento
O valor
addOnToken
é um token de autorização usado para fazeraddOnAttachments.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 oprofessor 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 Googledo 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
:- 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. - 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.
- Transmita o valor
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
- Um complemento do Google Sala de Aula é registrado no Google Workspace
Marketplace com um URI de descoberta de anexos de
https://example.com/addon
. - Um professor instala este complemento e cria um novo aviso, atividade ou material em um dos cursos. Por exemplo,
itemId=234
,itemType=courseWork
ecourseId=123
. - Ao configurar esse item, o professor escolhe o complemento recém-instalado como anexo.
- 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
.- O professor faz um trabalho dentro do iframe para selecionar o anexo.
- 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 |
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
- 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
.
- O host é
- Um professor cria um novo aviso, atividade ou material em um dos cursos. Por exemplo,
itemId=234
,itemType=courseWork
ecourseId=123
. - 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. 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
.Você avalia os parâmetros de consulta transmitidos no iframe e faz uma chamada para o endpoint
CreateAddOnAttachment
. O parâmetro de consultaurlToUpgrade
é 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çãodecodeURIComponent()
.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.