Detalles de los parámetros de consulta y iframe

Los complementos de Classroom se cargan dentro de un iframe para proporcionar la para el usuario final con una experiencia fluida y conveniente. Existen cuatro estrategias diferentes tipos de iframe; consulta las páginas iframes en el directorio Recorridos del usuario de un 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:

Configuración del URI de iframe

El URI de configuración de archivos adjuntos es lo que carga el iframe de detección de adjuntos. donde los profesores comienzan el flujo de creación de archivos adjuntos de complementos en un Publicación de Classroom. Se puede configurar en la consola del proyecto de Google Cloud. Configura este URI en la API de tu proyecto de Google Cloud y Servicio > SDK de Google Workspace Marketplace > Página Configuración de la app

Configuración del URI de iframe

Los prefijos de URI de archivos adjuntos permitidos se usan para validar los URI establecidos en AddOnAttachment con *.addOnAttachments.create y *.addOnAttachments.patch. La validación es un prefijo de string literal coinciden y, por el momento, no se permite el uso de comodines.

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: relacionados con archivos adjuntos y relacionados con el acceso. parámetros.

Los parámetros relacionados con los archivos adjuntos le proporcionan al complemento información sobre la curso, la tarea, el archivo adjunto del complemento, la entrega del estudiante y un el 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 los que se encuentra este archivo adjunto que se adjuntan.

Se incluye con todos los iframes.

Tipo de artículo

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

se adjuntó un 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 teacherViewUri, studentViewUri y iframes de studentWorkReviewUri.

ID de envío

El valor submissionId es un identificador del trabajo del estudiante, pero debe usarse en combinación con el attachmentId para identificar la 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 hacer

addOnAttachments.create llama para crear el complemento.

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

URL que se actualizará

La presencia del valor urlToUpgrade implica que el

el profesor incluyó un Vínculo adjunto en la tarea y aceptó para actualizarlo a un archivo adjunto de complemento. Si aún no tienes configuración de la función, consulta la guía sobre cómo actualizar vínculos a complementos adjuntos 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 Un usuario de Classroom 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 lo usó. tu complemento para ayudar a reducir la fricción de acceso del usuario final. Es necesario que manejes 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 El parámetro login_hint se pasa en cada visita posterior a tu complemento por el mismo usuario.

Hay dos usos posibles para el parámetro login_hint:

  1. Pasa el valor login_hint durante el flujo de autenticación para que la el usuario no necesita ingresar sus credenciales cuando aparece el diálogo de acceso . El usuario no accedió automáticamente.
  2. Después de que el usuario accede, usa este parámetro para comparar el valor a los usuarios a los que ya hayas accedido con el complemento. Si para encontrar una coincidencia, puedes dejar acceder al usuario y evitar mostrar un flujo de acceso. Si el parámetro no coincide con ninguno de los parámetros usuarios, solicítales que accedan con un acceso con la marca de Google de la aplicación.

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 y itemType addOnToken y login_hint.
Altura Altura de la ventana del 80% menos 60 px para el encabezado superior
Ancho Máximo de 1600 px
90% de ancho de ventana cuando la ventana es de 600 px o menos ancho
80% del ancho de la ventana cuando la ventana > 600 px de ancho

Situación de ejemplo de descubrimiento de archivos adjuntos

  1. Se registró un complemento de Classroom 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 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 archivo adjunto.
  4. Classroom crea un iframe con la URL 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 los archivos adjuntos.
  5. 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 y 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 y 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 se expande y de 56 px cuando se contrae

Dimensión Descripción
Obligatorio Sí, si la actualización de vínculos a archivos adjuntos de complementos es compatible con tu complemento.
URI Proporcionado en los metadatos del complemento
Parámetros de consulta courseId, itemId y itemType addOnToken, urlToUpgrade y login_hint.
Altura Altura de la ventana del 80% menos 60 px para el encabezado superior
Ancho Máximo de 1600 px
90% de ancho de ventana cuando la ventana es de 600 px o menos ancho
80% del ancho de la ventana cuando la ventana > 600 px de ancho
  1. Se registró un complemento de Classroom con el URI de actualización de vínculo de https://example.com/upgrade Proporcionaste el siguiente host y ruta de acceso patrones de prefijo de los Archivos adjuntos de vínculos que Classroom debe intenta 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 nuevo anuncio, tarea o material 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 vínculo. un diálogo de archivo adjunto que coincida con un patrón de URL que hayas proporcionado. El profesor es y, luego, se te pide que actualices el vínculo a un archivo adjunto del complemento.

  4. Classroom inicia el iframe de actualización de vínculos con la URL configurada. a 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 consulta pasados en el iframe y llamas el extremo CreateAddOnAttachment Ten en cuenta que la consulta urlToUpgrade es un URI codificado cuando se pasa en el iframe. Es necesario decodificar para obtenerlo en su forma original. Por ejemplo, JavaScript ofrece la función decodeURIComponent().

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

Cerrar el iframe

Se puede cerrar el iframe desde la herramienta de aprendizaje enviando un postMessage con la carga útil {type: 'Classroom', action: 'closeIframe'}. Classroom solo acepta este postMessage desde 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 valor dominio+puerto como el del URI usado para iniciar el iframe; de lo contrario, el mensaje se ignora. Una solución alternativa es redireccionar a una página en el dominio original que no hace 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 la comunicación entre el iframe y la nueva pestaña por tu cuenta y permite que el iframe será responsable en última instancia de la emisión del evento de cierre postMessage. Como complemento nota que el hipervínculo "Abrir en el nombre del socio" se está quitando para que los usuarios no y crear pestañas así próximamente.

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 *"

Ten en cuenta que el bloqueo de cookies de terceros dificulta mantener a las que se accedió en un iframe. Consulta https://www.cookiestatus.com en la el estado actual del bloqueo de cookies en distintos navegadores. Por supuesto, esta problema no es exclusivo de los complementos de Google Classroom y afecta a todos los sitios web que iframe 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 otorgar acceso a las cookies creadas en un contexto propio mientras se encuentra contexto de terceros.
  • Pídele al usuario que permita las cookies de terceros. Quizás no siempre sea 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 necesaria. 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 las que se puede acceder en el complemento. Un profesor adjunta un vínculo que coincide con uno de tus expresiones regulares ve un diálogo descartable que los invita a probar tu complemento. Solo ven el diálogo si el complemento ya está instalado para a su cuenta.

Si quieres proporcionarles este comportamiento a los profesores, proporciona tu contactos con las expresiones regulares adecuadas. Si las expresiones regulares que proporcionas son demasiado amplios o entran en conflicto con otro complemento, pueden modificarse para que sean más restringidas o distintas.

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

El profesor está pegando el vínculo Figura 2: Un profesor pega un vínculo de un tercero fuente. El profesor ya instaló el dispositivo de terceros complemento de Classroom.

Diálogo de visibilidad de regex Figura 3: El diálogo interactivo que se presentó 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 el pop, como se ve en la figura 3, son se te redireccionará al iframe de Descubrimiento de archivos adjuntos del complemento.