Detalles de los parámetros de consulta y iframe

Los complementos de Classroom se cargan en un iframe para brindar al usuario final una experiencia del usuario fluida y conveniente. Existen cinco tipos distintos de iframe. Consulta las páginas de iframes en el directorio de User journeys para obtener una descripción general del propósito y la apariencia de cada iframe.

Lineamientos de seguridad de iframe

Se espera que los desarrolladores sigan las prácticas recomendadas de la industria para proteger sus elementos iframe. Sin embargo, también debes incorporar ciertas interacciones de la API en tu flujo de usuarios para confirmar que tienes credenciales válidas y que puedes identificar correctamente el rol del usuario en el curso.

Configuración de la aplicación del servidor

Para proteger el iframe, recomendamos las siguientes configuraciones del servidor:

Parámetros de consulta

Los elementos iframe pasan información crítica al complemento como parámetros de consulta. Hay dos categorías de parámetros: los relacionados con los archivos adjuntos y los relacionados con el acceso.

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

ID del curso

El valor de courseId es un identificador del curso.

Se incluye con todos los iframe.

ID de artículo

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

Se incluye con todos los iframe.

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 uno de "announcements", "courseWork" o "courseWorkMaterials".

Se incluye con todos los iframe.

ID del archivo adjunto

El valor attachmentId es un identificador del adjunto.

Se incluye con los iframes de teacherViewUri, studentViewUri y studentWorkReviewUri.

ID del envío

El valor de 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 el studentWorkReviewUri.

Token del complemento

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

Se incluye con el iframe de Attachment Discovery y el iframe de Link Upgrade.

URL para actualizar

La presencia del valor urlToUpgrade implica que el profesor incluyó un adjunto de vínculo en la tarea y aceptó actualizarlo a un adjunto de complemento. Si aún no configuraste esta función, consulta la guía para actualizar vínculos y agregar archivos adjuntos de complementos para obtener más detalles.

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

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 del iframe src. Se envía cuando el usuario ya usó tu complemento para ayudar a reducir la fricción del 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 de la Cuenta de Google del usuario. Después de que el usuario accede a tu complemento por primera vez, el parámetro login_hint se pasa en cada visita posterior a tu complemento por el mismo usuario.

Existen dos usos posibles para el parámetro login_hint:

  1. Pasa el valor de 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. Después de que el usuario haya accedido, usa este parámetro para comparar el valor con los usuarios que ya hayan accedido al complemento. Si encuentras una coincidencia, puedes dejar al usuario con la sesión iniciada y evitar mostrar un flujo de acceso. Si el parámetro no coincide con ninguno de tus usuarios que accedieron, solicita al usuario que acceda con un botón de acceso con la marca de Google.

Se incluye con todos los iframe.

Iframe de Attachment Discovery

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

Ejemplo de situación de descubrimiento de adjuntos

  1. Se registra un complemento de Classroom en Google Workspace Marketplace con un URI de descubrimiento de adjuntos de https://example.com/addon.
  2. Un profesor instala este complemento y crea un anuncio, una tarea o material nuevos en uno de sus cursos. Por ejemplo, itemId=234, itemType=courseWork y courseId=123.
  3. Mientras configura ese elemento, el profesor elige el complemento recién instalado como archivo adjunto.
  4. Classroom crea un iframe con la URL de src establecida 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. Cuando se selecciona un archivo adjunto, el complemento envía un postMessage a Classroom para cerrar el iframe.

Iframes de teacherViewUri y studentViewUri

Dimensión Descripción
Obligatorio Sí
URI teacherViewUri o studentViewUri
Parámetros de consulta courseId, itemId, itemType, attachmentId y login_hint.
Altura El 100% de la 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 adjunto de tipo de actividad)
URI studentWorkReviewUri
Parámetros de consulta courseId, itemId, itemType, attachmentId, submissionId y login_hint.
Altura El 100% de la altura de la ventana menos 168 px para el encabezado superior
Ancho El 100% del ancho de la ventana menos el ancho de la barra lateral<> la barra lateral mide 312 px cuando está expandida y 56 px cuando está contraída
Dimensión Descripción
Obligatorio Sí, si tu complemento admite la actualización de vínculos a archivos adjuntos de complementos.
URI Se proporciona en los metadatos del complemento
Parámetros de consulta courseId, itemId, itemType, addOnToken, urlToUpgrade y login_hint.
Altura El 80% de la altura de la ventana menos 60 px para el encabezado superior
Ancho Máximo de 1,600 px
90% del ancho de la ventana cuando la ventana es <= 600 px de ancho
80% del ancho de la ventana cuando la ventana es > 600 px de ancho
  1. Se registró un complemento de Classroom 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 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 ruta de acceso es /quiz.
  2. Un profesor crea un anuncio, una tarea o material nuevos en uno de sus cursos. Por ejemplo, itemId=234, itemType=courseWork y courseId=123.
  3. Un profesor pega un vínculo, https://example.com/quiz/5678, en el diálogo adjunto de 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.

  4. Classroom lanza 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.

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

  6. Cuando se crea correctamente un archivo adjunto de complemento a partir de un vínculo, envías un postMessage a Classroom para cerrar el iframe.

Cierra el iframe

El iframe se puede cerrar 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>

Cerrar el iframe desde el iframe

El dominio y el puerto de la página que envía el evento postMessage deben ser los mismos que los del URI que se usa para iniciar el iframe. De lo contrario, se ignorará el mensaje. Una solución alternativa es redireccionar a una página del dominio original que no haga más que enviar el evento postMessage.

Cómo cerrar el iframe desde una pestaña nueva

Las protecciones de dominio cruzado 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 el responsable final 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 el futuro cercano.

Restricciones

Todos los elementos iframe se abren con los siguientes atributos de 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 *"

Ten en cuenta que el bloqueo de cookies de terceros dificulta mantener una sesión iniciada 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 que usan iframes de terceros. Muchos de nuestros socios ya se encontraron con este problema.

Estas son algunas soluciones alternativas generales:

  • Abre una pestaña nueva para crear la cookie en un contexto de origen. Algunos navegadores otorgan acceso a las cookies creadas en el contexto propio mientras se encuentran en un contexto de terceros.
  • Solicitar al usuario que permita las 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 esperan más restricciones de cookies en versiones futuras de los navegadores. Crea solicitudes de funciones para enviar comentarios a Google sobre cómo reducir la elevación requerida por los socios.

Habilita la detección de complementos con expresiones regulares de URL

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

Si deseas proporcionar 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.

El profesor selecciona el archivo adjunto del vínculo Figura 1: El profesor selecciona un vínculo adjunto a una tarea nueva.

Vínculo para que el profesor lo pegue Figura 2: El profesor pega un vínculo de una fuente externa. El profesor ya instaló el complemento de Classroom de terceros.

Diálogo de visibilidad de expresiones regulares Figura 3: Es 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 que se muestra en la figura 3, se lo redireccionará al iframe de Descubrimiento de archivos adjuntos de tu complemento.