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:
HTTPS é obrigatório. É altamente recomendável usar o TLS 1.2 ou mais recente e ativar o HTTP Strict Transport Security. Ver este MDN relacionado artigo sobre o Strict Transport Security.
Ative a Política estrita de segurança de conteúdo. Confira este OWASP artigo e este artigo MDN sobre a Política de Segurança de Conteúdo.
Ative o atributo de cookie seguro. Veja o atributo HttpOnly e este artigo MDN sobre cookies relacionado.
Configuração de URI do iframe
O URI de configuração de anexos é carregado pelo iframe de descoberta de anexos. é quando os professores começam 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.
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.
Parâmetros relacionados a anexos
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 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
teacherViewUri
,studentViewUri
e IframesstudentWorkReviewUri
.- ID do envio
O valor
submissionId
é um identificador do trabalho do estudante. mas deve ser usado em combinação comattachmentId
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 fazeraddOnAttachments.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 oprofessor 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.
Parâmetros relacionados ao login
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 Googledo 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
:- 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. - 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.
.
- 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 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
- 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
. - Um professor instala este complemento e cria um novo aviso, atividade ou
em um dos cursos. Por exemplo,
itemId=234
,itemType=courseWork
ecourseId=123
. - Ao configurar o item, o professor escolhe o complemento recém-instalado. como um 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
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 |
iframe de upgrade de link
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 |
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 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
.
- O host é
- Um professor cria um novo aviso, atividade ou material em um dos
nos cursos. Por exemplo,
itemId=234
,itemType=courseWork
ecourseId=123
- 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. 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
:Você avalia os parâmetros de consulta passados no iframe e faz uma chamada para o endpoint
CreateAddOnAttachment
. Observe que a consultaurlToUpgrade
é codificado na URI quando transmitido no iframe. Você precisa decodificar para obtê-lo em sua forma original. JavaScript, por exemplo, oferece a funçãodecodeURIComponent()
.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 é 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 *"
Bloqueio de cookies de terceiros
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.
Figura 1. Professor selecionando um link
anexo a uma nova atividade.
Figura 2. Professor colando um link de terceiros
fonte. O professor já instalou o app de terceiros
como complemento do Google Sala de Aula.
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.