Detalles de los parámetros de consulta y iframe

Los complementos de Classroom se cargan dentro de un iframe para brindar 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:

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.

Configuración del URI de iframe

Los prefijos de URI de archivos adjuntos permitidos se usan para validar los URIs establecidos en AddOnAttachment con los métodos *.addOnAttachments.create y *.addOnAttachments.patch. La validación es una coincidencia literal de prefijo de cadena y, por el momento, no permite el uso de comodines.

Parámetros de consulta

Los iframes pasan información esencial al complemento como parámetros de consulta. Hay dos categorías de parámetros: parámetros relacionados con los archivos adjuntos y 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, 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 de Announcement.

CourseWork o CourseWorkMaterial en el que se adjunta este archivo.

Se incluye con todos los iframes.

Tipo de artículo

El valor itemType identifica el tipo de recurso en el que este

archivo adjunto. El valor de cadena pasado es uno de "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 y studentWorkReviewUri.

ID de envío

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

Se incluye con studentWorkReviewUri.

Token de complemento

El valor addOnToken es un token de autorización que se usa para realizar

Llamadas a addOnAttachments.create para crear el complemento

Se incluye con 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 el

el 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.

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 consulta se proporciona en la URL src del 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 del complemento.

Sugerencia de acceso

El login_hint es un identificador único del servicio 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.

Existen dos posibles usos para el parámetro login_hint:

  1. 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.
  2. Después de que el usuario haya accedido, usa este parámetro para comparar el valor con los usuarios con los que ya accediste al complemento. Si encuentras una coincidencia, puedes dejar que el usuario acceda y evitar mostrar 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.

Se incluye con todos los iframes.

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 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
80% del ancho de la ventana cuando la ventana es > 600 px

Situación de ejemplo de descubrimiento de archivos adjuntos

  1. Un complemento de Classroom se registra 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 anuncio, una tarea o un material nuevo en uno de sus cursos. Por ejemplo, itemId=234, itemType=courseWork y courseId=123.
  3. Durante la configuración de ese elemento, el profesor elige el complemento recién instalado como un 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 tareas 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 100% de la altura de la ventana menos 140 px para el encabezado superior
Ancho Ancho de la ventana del 100%

Iframe de studentWorkReviewUri

Dimensión Descripción
Obligatorio No (Determina si se trata de un archivo 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 100% del ancho de la ventana menos el ancho de la barra lateral<> la barra lateral es de 312 px cuando está expandida y de 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 Proporcionado en los metadatos del complemento
Parámetros de consulta courseId, itemId, itemType, addOnToken, urlToUpgrade y login_hint.
Altura 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
80% del ancho de la ventana cuando la ventana es > 600 px
  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 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.
  2. Un profesor crea un anuncio, una tarea o un 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 de archivo 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 de complemento.

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

  5. 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 consulta urlToUpgrade está codificado en URI cuando se pasa al iframe. Debes decodificar el parámetro para obtener su formato original. JavaScript, por ejemplo, ofrece la función decodeURIComponent().

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

Cierra 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 nombre_host+puerto 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 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 del dominio original que no haga nada más que enviar el evento postMessage.

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 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 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 atributos

  • allow="microphone *"

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 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 generales:

  • Abre una pestaña nueva para crear la cookie en un contexto propio. Algunos navegadores otorgan acceso a las cookies creadas en el contexto propio mientras se encuentran en un contexto de terceros.
  • Pídele al usuario que permita las cookies de terceros. Es posible que esto no siempre sea posible con todos los usuarios.
  • Diseña aplicaciones web de una sola página que no dependan de las cookies.

Se espera que haya más restricciones de cookies en versiones futuras del navegador. Crea solicitudes de funciones para enviar comentarios a Google sobre cómo reducir la efectividad que requieren los socios.

Habilita la visibilidad de los complementos con expresiones regulares de URL

Los profesores suelen crear tareas con archivos adjuntos de vínculos. 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 tu 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 verán el diálogo si el complemento ya está instalado en 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.

Profesor que selecciona un archivo adjunto de vínculo Figura 1: Un profesor selecciona un archivo adjunto de vínculo para una tarea nueva.

El profesor está pegando el vínculo Figura 2: Profesor que pega un vínculo de una fuente externa El profesor ya instaló el complemento de Classroom de terceros.

Diálogo de visibilidad de la regex 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, como se ve en la figura 3, se lo redirecciona al iframe de descubrimiento de archivos adjuntos de tu complemento.