Detalles de los parámetros de consulta y iframe

Los complementos de Classroom se cargan en un iframe para ofrecer al usuario final una experiencia del usuario sencilla y conveniente. Existen cuatro tipos distintos de iframes. Consulta las páginas de iframes en el directorio User trips para obtener una descripción general del propósito y el aspecto 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. Te recomendamos usar TLS 1.2 o una versión posterior 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 relacionado con MDN sobre la Política de Seguridad del Contenido.

• Habilita el atributo de cookie segura. Consulta el atributo HttpOnly y este artículo MDN sobre cookies relacionado.

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 inician 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 > página Configuración de la app.

Los prefijos de URI de archivo adjunto permitidos se usan para validar los URIs configurados en AddOnAttachment con 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. Hay dos categorías de parámetros: los relacionados con adjuntos y los relacionados con el acceso.

Parámetros relacionados con archivos adjuntos

Los parámetros relacionados con los archivos adjuntos proporcionan al complemento información sobre el curso, la tarea, el archivo adjunto del complemento, la entrega del estudiante y un token de autorización.

ID del curso

El valor courseId es un identificador del curso.

Incluido con todos los iframes.

ID de publicación (obsoleto)

El valor postId es un identificador de la publicación (anuncio, trabajo del curso o material de trabajo del curso) en la que se adjunta este archivo adjunto.

Incluido con todos los iframes.

Obsoleto: El ID de la publicación dejó de estar disponible. En su lugar, usa el ID de artículo.

ID de artículo

El valor itemId es un identificador de Announcement, CourseWork o CourseWorkMaterial al que se adjunta este archivo adjunto.

Incluido con todos los iframes.

Tipo de elemento

El valor itemType identifica el tipo de recurso al que se adjunta este adjunto. El valor de cadena que se pasa es "announcements", "courseWork" o "courseWorkMaterials".

Incluido con todos los iframes.

ID del archivo adjunto

El valor attachmentId es un identificador del adjunto.

Se incluye con los iframes teacherViewUri, studentViewUri y studentWorkReviewUri.

ID del envío

El valor submissionId es un identificador del trabajo del estudiante, pero debe usarse en combinación con attachmentId para identificar el trabajo del estudiante de una tarea en particular.

Se incluye con studentWorkReviewUri.

Nota: Puedes usar una clave compuesta de submissionId y attachmentId para identificar el trabajo del estudiante en caso de que se asigne el mismo archivo adjunto al mismo estudiante en diferentes cursos. Para obtener más información, consulta el contenido copiado.

Token de complemento

El valor addOnToken es un token de autorización que se usa para realizar llamadas addOnAttachments.create a fin de crear el complemento.

Se incluye con el iframe de descubrimiento de archivos adjuntos y el iframe de actualización de vínculos.

URL para actualizar

La presencia del valor urlToUpgrade implica que el profesor incluyó un vínculo adjunto 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 para actualizar vínculos a archivos adjuntos de complementos para obtener más detalles.

Se incluye en el iframe de actualización de vínculos.

Parámetros relacionados con el acceso

El parámetro de consulta login_hint proporciona información sobre el usuario de Classroom que visita la página web del complemento. Este parámetro de búsqueda se proporciona en la URL src del iframe. Se envía cuando el usuario ya usa el complemento para ayudar a reducir las dificultades de acceso del usuario final. Debes controlar este parámetro de consulta en la implementación del complemento.

Sugerencia de acceso

login_hint es un identificador único para la cuenta de Google

de Google. Después de que el usuario accede a tu complemento por primera vez, el mismo usuario pasa el parámetro login_hint en cada visita posterior al complemento.

El parámetro login_hint podría tener dos usos posibles:

1. Pasar 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 accede automáticamente.
2. Una vez que el usuario haya accedido, usa este parámetro para comparar el valor con cualquier usuario que ya hayas accedido al complemento. Si encuentras una coincidencia, puedes dejar que el usuario acceda sin que se le muestre un flujo de acceso. Si el parámetro no coincide con ninguno de los usuarios que accedieron, pídele que acceda con un botón de acceso de marca de Google.

Incluido con todos los iframes.

Nota: Puedes encontrar información adicional sobre la implementación del parámetro login_hint y el flujo de acceso en las páginas de SSO, Acceso sin inconvenientes y Cómo administrar accesos repetidos.

Iframe de descubrimiento de archivos adjuntos

Dimensión	Descripción
Obligatorio	Sí
URI	Proporcionados en los metadatos del complemento
Parámetros de consulta	courseId, postId (obsoleto), itemId, itemType, addOnToken y login_hint.
Altura	80% de altura de la ventana menos 60 px para el encabezado superior
Ancho	Máximo de 1,600 px 90% de ancho de la ventana cuando la ventana es <= 600 px de ancho 80% de ancho de la ventana cuando la ventana es superior a 600 px de ancho

Situación de ejemplo de descubrimiento de archivos adjuntos

1. Un complemento de Classroom está registrado en Google Workspace Marketplace con un URI de descubrimiento de archivos adjuntos de https://example.com/addon.
2. 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 y courseId=123.
3. Mientras configura ese elemento, el profesor elige el complemento instalado recientemente como archivo adjunto.
4. Classroom crea un iframe con la URL src configurada en https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456.
   1. El profesor realiza el trabajo dentro del iframe para seleccionar un archivo adjunto.
5. En la selección de archivos adjuntos, 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, postId (obsoleto), itemId, itemType, attachmentId y login_hint.
Altura	100% de altura de la ventana menos 140 px para el encabezado superior
Ancho	100% del ancho de la ventana

Iframe de studentWorkReviewUri

Dimensión	Descripción
Obligatorio	No (determina si se trata de un archivo adjunto de tipo actividad)
URI	studentWorkReviewUri
Parámetros de consulta	courseId, postId (obsoleto), itemId, itemType, attachmentId, submissionId y login_hint.
Altura	100% de altura de la ventana menos 168 px para el encabezado superior
Ancho	100% del ancho de la ventana menos el ancho de la barra lateral<> la barra lateral es de 312 px cuando se expande y de 56 px cuando se contrae.

Nota: Los profesores pueden abrir el iframe de Revisión del trabajo de los estudiantes que no hayan visto antes el archivo adjunto del complemento. En ese caso, es posible que el complemento aún no esté al tanto de este estudiante y deba mostrar un mensaje adecuado.

Iframe de actualización de vínculos

Dimensión	Descripción
Obligatorio	Sí, si tu complemento admite la actualización de vínculos a archivos adjuntos de complementos.
URI	Proporcionados en los metadatos del complemento
Parámetros de consulta	courseId, postId (obsoleto), itemId, itemType, addOnToken, urlToUpgrade y login_hint.
Altura	80% de altura de la ventana menos 60 px para el encabezado superior
Ancho	Máximo de 1,600 px 90% de ancho de la ventana cuando la ventana es <= 600 px de ancho 80% de ancho de la ventana cuando la ventana es superior a 600 px de ancho

Ejemplo de situación de actualización de vínculos

1. 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 prefijos de host y ruta de acceso para Archivos 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 la ruta de acceso es /quiz.
2. Un profesor crea un anuncio, una tarea o material nuevo dentro de uno de sus cursos. Por ejemplo, itemId=234, itemType=courseWork y courseId=123.
3. El profesor pega un vínculo, https://example.com/quiz/5678, en el diálogo Adjuntar vínculo que coincide con el patrón de URL que proporcionaste. Luego, se le solicita al profesor que actualice el vínculo a un archivo adjunto del complemento.

4. Classroom inicia el iframe de actualización de vínculos con la URL configurada en https://example.com/upgrade?courseId=123&postId=234&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678.

5. Evalúa los parámetros de consulta que se pasaron en el iframe y realizas una llamada al extremo CreateAddOnAttachment. Ten en cuenta que el parámetro de búsqueda urlToUpgrade está codificado en el URI cuando se pasa en el iframe. Debes decodificar el parámetro para obtenerlo en su formato original. JavaScript, por ejemplo, ofrece la función decodeURIComponent().

6. Si creaste correctamente un archivo adjunto del complemento desde un vínculo, enviarás un postMessage a Classroom para cerrar el iframe.

Cerrar el iframe

Para cerrar el iframe desde la herramienta de aprendizaje, se debe enviar un objeto 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 el 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 el mismo puerto que el del 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 hace más que enviar el evento postMessage.

Cómo cerrar 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 permitir que el iframe sea responsable de emitir el evento de cierre postMessage. 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 abierta en un iframe. Consulta https://www.cookiestatus.com para conocer 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 con iframes de terceros. Muchos de nuestros socios ya tienen 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 el contexto propio en un contexto de terceros.
• Pídele al usuario que permita cookies de terceros. Esto no siempre es posible con todos los usuarios.
• Diseña aplicaciones web de una sola página que no dependan de cookies.

Se prevé que haya más restricciones de cookies en las versiones futuras 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 los complementos con expresiones regulares de URL

Los profesores suelen crear tareas con vínculos adjuntos. Para promover el uso de tu complemento, puedes especificar expresiones regulares que coincidan con las URLs de los recursos a los que se puede acceder en el complemento. Si un profesor adjunta un vínculo que coincide con una de tus expresiones regulares, verá un diálogo descartable que lo alentará a probar tu complemento. Solo ve el diálogo si el complemento ya está instalado en su cuenta.

Si quieres manifestar este comportamiento a los profesores, proporciona a tus contactos de Google las expresiones regulares adecuadas. 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 enlace adjunto a una nueva tarea.

Figura 2: El profesor pega un vínculo desde 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.