Los complementos de Classroom se cargan dentro de un iframe para proporcionar al usuario final una experiencia del usuario fluida y conveniente. Existen cuatro tipos de iframe diferentes. Consulta las páginas de iframes en el directorio Recorridos del usuario para obtener una descripción general del propósito y la apariencia de cada iframe.
Lineamientos de seguridad de iframe
Se espera que los socios sigan las prácticas recomendadas de la industria para proteger su iframe. Para proteger el iframe, nuestro equipo de seguridad recomienda lo siguiente:
Se requiere HTTPS. Recomendamos enfáticamente usar TLS 1.2 o superior y habilitar HTTP con Seguridad de Transporte Estricta. Consulta este artículo de MDN relacionado sobre la seguridad de transporte estricta.
Habilita la Política de Seguridad del Contenido Estricta. Consulta este artículo de OWASP y este artículo de MDN de la Política de Seguridad del Contenido relacionado.
Habilita el atributo Secure cookie. Consulta el atributo HttpOnly y este artículo relacionado con las cookies de MDN.
Configuración del URI de iframe
El URI de configuración de archivos adjuntos es lo que carga el iframe de descubrimiento de archivos adjuntos y es donde los profesores comienzan el flujo de creación de archivos adjuntos de complementos en una publicación de Classroom. Se puede configurar en la consola del proyecto de Google Cloud. Configura este URI en la página API y servicio de tu proyecto de Google Cloud > SDK de Google Workspace Marketplace > Configuración de la app.
Los prefijos de URI de archivos adjuntos permitidos se usan para validar los URI establecidos en AddOnAttachment mediante los métodos *.addOnAttachments.create
y *.addOnAttachments.patch
. La validación es una coincidencia de prefijo de string literal y no permite el uso de comodines en este momento.
Parámetros de consulta
Los iframes pasan información crítica al complemento como parámetros de consulta. Existen dos categorías de parámetros: los relacionados con archivos adjuntos y los relacionados con el acceso.
Parámetros relacionados con los archivos adjuntos
Los parámetros relacionados con los archivos adjuntos proporcionan al complemento información sobre el curso, la tarea, el archivo adjunto, la entrega del estudiante y un token de autorización.
- ID del curso
El valor
courseId
es un identificador del curso.Se incluye con todos los iframes.
- ID de artículo
El valor
itemId
es un identificador deAnnouncement
.CourseWork
oCourseWorkMaterial
en los que está adjunto este adjunto.Se incluye con todos los iframes.
- Tipo de artículo
El valor
itemType
identifica el tipo de recurso en el que estese adjuntó un archivo adjunto. El valor de cadena que se pasa es
"announcements"
,"courseWork"
o"courseWorkMaterials"
.Se incluye con todos los iframes.
- ID del archivo adjunto
El valor
attachmentId
es un identificador del adjunto.Se incluye con los iframes de
teacherViewUri
,studentViewUri
ystudentWorkReviewUri
.- ID de envío
El valor
submissionId
es un identificador del trabajo del estudiante, pero se debe usar en combinación conattachmentId
para identificar el trabajo de un estudiante en una tarea en particular.Se incluye con
studentWorkReviewUri
.
- Token de complemento
El valor
addOnToken
es un token de autorización que se usa para haceraddOnAttachments.create
llama para crear el complemento.Se incluye en el iframe de descubrimiento de archivos adjuntos y el iframe de actualización de vínculos.
- URL que se actualizará
La presencia del valor
urlToUpgrade
implica que elel profesor incluyó un Archivo adjunto de vínculo en la tarea y aceptó actualizarlo a un archivo adjunto de complemento. Si aún no tienes esta función configurada, consulta la guía sobre cómo actualizar vínculos a adjuntos de complementos para obtener más detalles.
Se incluye con el iframe de actualización de vínculos.
Parámetros relacionados con el acceso
El parámetro de búsqueda login_hint
proporciona información sobre el usuario de Classroom que visita la página web del complemento. Este parámetro de consulta se proporciona en la URL src
de iframe. Se envía cuando el usuario ya usó el complemento para ayudar a reducir la fricción de acceso del usuario final. Debes controlar este parámetro de consulta en la implementación de tu complemento.
- Sugerencia de acceso
El
login_hint
es un identificador único del servicio de Googlede Google. Después de que el usuario accede al complemento por primera vez, se pasa el parámetro
login_hint
en cada visita posterior al complemento por parte del mismo usuario.Hay dos usos posibles para el parámetro
login_hint
:- Pasa el valor
login_hint
durante el flujo de autenticación para que el usuario no tenga que ingresar sus credenciales cuando aparezca el diálogo de acceso. El usuario no accedió automáticamente. - Después de que el usuario acceda, usa este parámetro para comparar el valor con el de cualquier usuario con el que hayas accedido al complemento. Si encuentras una coincidencia, puedes permitir que el usuario acceda sin que se muestre un flujo de acceso. Si el parámetro no coincide con ninguno de los usuarios que accedieron a sus cuentas, solicítale que acceda con un botón de acceso con la marca de Google.
Se incluye con todos los iframes.
- Pasa el valor
iframe de descubrimiento de archivos adjuntos
Dimensión | Descripción |
---|---|
Obligatorio | Sí |
URI | Proporcionado en los metadatos del complemento |
Parámetros de consulta | courseId , itemId , itemType , addOnToken y login_hint . |
Altura | Altura de la ventana del 80% menos 60 px para el encabezado superior |
Ancho | Un máximo de 1600 px 90% de ancho de ventana cuando la ventana tiene un ancho de <= 600 px 80% de ancho de ventana cuando la ventana es de más de 600 px de ancho |
Situación de ejemplo de descubrimiento de archivos adjuntos
- Un complemento de Classroom se registra en Google Workspace Marketplace con un URI de descubrimiento de archivos adjuntos de
https://example.com/addon
. - Un profesor instala este complemento y crea un nuevo anuncio, tarea o material dentro de uno de sus cursos. Por ejemplo,
itemId=234
,itemType=courseWork
ycourseId=123
. - Durante la configuración de ese elemento, el profesor elige el complemento recién instalado como un adjunto.
- Classroom crea un iframe con la URL src configurada en
https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456
.- El profesor realiza tareas dentro del iframe para seleccionar los archivos adjuntos.
- Cuando se selecciona el archivo adjunto, el complemento envía un
postMessage
a Classroom para cerrar el iframe.
iframes de profesorViewUri y studentViewUri
Dimensión | Descripción |
---|---|
Obligatorio | Sí |
URI | teacherViewUri o studentViewUri |
Parámetros de consulta | courseId , itemId , itemType , attachmentId y login_hint . |
Altura | Altura de la ventana del 100% menos 140 px para el encabezado superior |
Ancho | Ancho de la ventana al 100% |
Iframe de studentWorkReviewUri
Dimensión | Descripción |
---|---|
Obligatorio | No (determina si se trata de un adjunto de tipo de actividad) |
URI | studentWorkReviewUri |
Parámetros de consulta | courseId , itemId , itemType , attachmentId , submissionId y login_hint . |
Altura | Altura de la ventana del 100% menos 168 px para el encabezado superior |
Ancho | El ancho de la ventana 100% menos el ancho de la barra lateral<> es de 312 px cuando se expande y de 56 px cuando se contrae. |
iframe de actualización del vínculo
Dimensión | Descripción |
---|---|
Obligatorio | Sí, si tu complemento admite la actualización de vínculos a archivos adjuntos de complementos. |
URI | Proporcionado en los metadatos del complemento |
Parámetros de consulta | courseId , itemId , itemType , addOnToken , urlToUpgrade y login_hint . |
Altura | Altura de la ventana del 80% menos 60 px para el encabezado superior |
Ancho | Un máximo de 1600 px 90% de ancho de ventana cuando la ventana tiene un ancho de <= 600 px 80% de ancho de ventana cuando la ventana es de más de 600 px de ancho |
Ejemplo de situación de actualización de vínculo
- Un complemento de Classroom se registra con un URI de actualización de vínculo de
https://example.com/upgrade
. Proporcionaste los siguientes patrones de prefijo de host y ruta de acceso para los adjuntos de vínculos que Classroom debería intentar actualizar a un archivo adjunto de complemento:- El host es
example.com
y el prefijo de ruta de acceso es/quiz
.
- El host es
- Un profesor crea un nuevo anuncio, tarea o material dentro de uno de sus cursos. Por ejemplo,
itemId=234
,itemType=courseWork
ycourseId=123
. - Un profesor pega un vínculo,
https://example.com/quiz/5678
, en el diálogo Archivo adjunto del vínculo que coincide con un patrón de URL que proporcionaste. Luego, se le solicita al profesor que actualice el vínculo a un archivo adjunto del complemento. Classroom inicia el iframe de actualización de vínculos con la URL establecida en
https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678
.Debes evaluar los parámetros de búsqueda que se pasaron en el iframe y realizar una llamada al extremo
CreateAddOnAttachment
. Ten en cuenta que el parámetro de consultaurlToUpgrade
tiene codificación de URI cuando se pasa en el iframe. Debes decodificar el parámetro para obtener su formato original. JavaScript, por ejemplo, ofrece la funcióndecodeURIComponent()
.Cuando se crea correctamente un archivo adjunto de complemento desde un vínculo, debes enviar una
postMessage
a Classroom para cerrar el iframe.
Cerrar el iframe
Es posible que se cierre el iframe desde la herramienta de aprendizaje enviando un postMessage
con la carga útil {type: 'Classroom', action: 'closeIframe'}
.
Classroom solo acepta este postMessage
del host_name + port
correspondiente al URI original que se abrió.
<button id="close">Send message to close iframe</button>
<script>
document.querySelector('#close')
.addEventListener('click', () => {
window.parent.postMessage({
type: 'Classroom',
action: 'closeIframe',
}, '*');
});
</script>
Cómo cerrar iframe desde el iframe
El dominio y el puerto de la página que envía el evento postMessage
deben tener el mismo dominio y puerto que el URI que se usó para iniciar el iframe. De lo contrario, se ignorará el mensaje. Una solución alternativa es redireccionar a una página en el dominio original que no haga nada más que enviar el evento postMessage
.
Cerrar el iframe desde una pestaña nueva
Las protecciones multidominio impiden que esto funcione. Una solución alternativa es controlar
las comunicaciones entre el iframe y la pestaña nueva por tu cuenta y dejar que el iframe
sea, en última instancia, responsable de emitir el evento postMessage
de cierre. Como nota al margen, se quitará el hipervínculo “Abrir en nombre del socio” para que los usuarios no creen pestañas de esta manera en un futuro cercano.
Restricciones
Todos los iframes se abren con los siguientes atributos de la zona de pruebas:
allow-popups
allow-popups-to-escape-sandbox
allow-forms
allow-scripts
allow-storage-access-by-user-activation
allow-same-origin
y la siguiente política de funciones
allow="microphone *"
Bloqueo de cookies de terceros
Ten en cuenta que el bloqueo de cookies de terceros dificulta el mantenimiento de una sesión de acceso en un iframe. Consulta https://www.cookiestatus.com para obtener más información sobre el estado actual del bloqueo de cookies en diferentes navegadores. Por supuesto, este problema no es exclusivo de los complementos de Google Classroom y afecta a todos los sitios web que iframen a terceros. Muchos de nuestros socios ya se encontraron con este problema.
Estas son algunas soluciones generales:
- Abre una pestaña nueva para crear la cookie en un contexto propio. Algunos navegadores otorgan acceso a cookies creadas en un contexto propio mientras están en un contexto de terceros.
- Pídele al usuario que permita las cookies de terceros. Esto no siempre puede ser posible con todos los usuarios.
- Diseña aplicaciones web de una sola página que no dependan de cookies.
Se prevén más restricciones de cookies en futuras versiones de los navegadores. Crea solicitudes de funciones para enviar comentarios a Google sobre cómo reducir la efectividad que requieren los socios.
Habilitar la visibilidad de complementos usando expresiones regulares de URL
A menudo, los profesores crean tareas con vínculos adjuntos. Para promover el uso de tu complemento, puedes especificar expresiones regulares que coincidan con las URL de los recursos a los que se puede acceder en el complemento. Un profesor que adjunta un vínculo que coincide con una de tus expresiones regulares ve un diálogo descartable que los invita a probar el complemento. Solo ven el diálogo si el complemento ya está instalado para su cuenta.
Si deseas proporcionar este comportamiento a los profesores, proporciona las expresiones regulares adecuadas a tus contactos de Google. Si las expresiones regulares que proporcionas son demasiado amplias o entran en conflicto con otro complemento, es posible que se modifiquen para que sean más restringidas o distintas.
Figura 1: El profesor selecciona un vínculo adjunto a una nueva tarea.
Figura 2: El profesor pega un vínculo de una fuente de terceros. El profesor ya instaló el complemento de Classroom de terceros.
Figura 3: El diálogo interactivo que se presenta al profesor cuando el vínculo pegado coincide con una expresión regular especificada por el desarrollador externo.
Si un profesor selecciona "Probar ahora" en la ventana emergente, como se ve en la Figura 3, se lo redireccionará al iframe de descubrimiento de archivos adjuntos de tu complemento.