Actualizar archivos adjuntos de vínculos a archivos adjuntos de complementos de Classroom

Para agregar contenido de terceros a Classroom, los profesores pueden pegar un vínculo como Archivo adjunto en la página de creación de tareas. Para mejorar la experiencia de los profesores, ahora puedes configurar el complemento y permitir que los profesores actualicen un vínculo adjunto a un archivo adjunto de complemento.

Descripción general

Si configuras tu complemento con esta función, se les solicitará a los profesores que actualicen un vínculo a un archivo adjunto del complemento cuando peguen un archivo adjunto de vínculo en la página de creación de tareas. Solo se les solicita a los profesores que lo hagan si ya tienen el complemento instalado.

Una vez que el profesor acepta actualizar el vínculo a un archivo adjunto de complemento, el iframe de actualización de vínculos se inicia con los siguientes parámetros de consulta:

• courseId
• itemId (cambió el nombre de postId)
• itemType (nuevo)
• addOnToken
• login_hint o hd
• urlToUpgrade (nuevo)

Los primeros cuatro parámetros de búsqueda reflejan los parámetros iniciados en el iframe de descubrimiento de archivos adjuntos. El parámetro de consulta urlToUpgrade es nuevo y puede ayudarte a evaluar cómo se debe crear el archivo adjunto del complemento. Luego, puedes usar los otros parámetros de búsqueda para verificar si el usuario accedió y llamar al método CreateAddOnAttachment de courseWork, courseWorkMaterials o announcements según el valor itemType. Dentro del iframe, puedes mostrar una pantalla de carga para indicarle al profesor que se está creando el archivo adjunto del complemento.

Una vez creado el archivo adjunto del complemento, se cierra el iframe y el profesor puede ver el archivo adjunto en la tarea como lo haría normalmente.

Detalles técnicos de la implementación

En esta sección, se destacan algunos detalles técnicos importantes sobre la función.

Lee el parámetro de consulta urlToUpgrade.

El parámetro de consulta urlToUpgrade está codificado en URI cuando se pasa en el iframe Actualización de vínculos. Debes decodificar la URL para obtenerla en su formato original. Si usas JavaScript, por ejemplo, puedes usar la función decodeURIComponent() para hacerlo.

Cerrar el iframe de actualización de vínculos

Para garantizar una experiencia del usuario óptima con esta función, envía un postMessage una vez que el archivo adjunto del complemento se haya creado correctamente. Esto cierra el iframe. Para obtener más información, consulta la página de detalles de la implementación de iframe.

Detalles de configuración

Se requieren los siguientes parámetros de configuración para integrar esta función en tu complemento:

• URL del iframe de actualización de vínculos: Es la URL que se abre en el iframe cuando un profesor acepta realizar la actualización.

• Patrones de URL que Classroom debe detectar y tratar de actualizar: Los patrones de URL pueden constar de un host y varios prefijos de ruta de acceso.

  • Puedes proporcionar varios patrones de URL.
  • Si no proporcionas prefijos de ruta de acceso, se puede actualizar cualquier URL que coincida con el host.
  • Solo se pueden actualizar las URLs con un esquema https.
  • Los patrones de URL no deben incluir localhost.
  • Los prefijos de ruta de acceso no deben contener parámetros de consulta ni fragmentos de URL.
  • Los prefijos de ruta de acceso pueden admitir comodines en este momento, pero los hosts no pueden hacer lo siguiente:
    • example.com es un host válido, y /foo y /bar/*/baz son prefijos de ruta de acceso válidos.
    • example.*.host.com no es un host válido.
  • Un comodín entre componentes del prefijo de ruta de acceso solo coincide con un componente y no coincide con varios componentes separados por barras diagonales. Considera un patrón de URL con el example.com del host y el prefijo de ruta /bar/*/baz:
    • https://example.com/bar/123/baz es una coincidencia válida para el patrón de URL.
    • https://example.com/bar/123/baz/456/789 es una coincidencia válida para el patrón de URL.
    • https://example.com/bar/123/456/baz no es una coincidencia válida para el patrón de URL porque el comodín en el prefijo de la ruta de acceso no coincide con /123/456/.

Nota: Los comodines entre los componentes del prefijo de ruta de acceso solo coinciden con un solo componente.

Proceso de desarrollo

Envía un correo electrónico a [e-mail] los patrones de URL y de URL del iframe de Actualización de vínculos para tu complemento de prueba o producción.

Primero, puedes proporcionar configuraciones para tu complemento privado y cualquier entorno de prueba o desarrollo que poseas. El equipo de Classroom puede habilitar estas configuraciones de prueba antes de habilitar las de producción para que puedas probar el flujo en tu dominio de demostración. Recibirás una respuesta a tu correo electrónico cuando se habiliten las configuraciones. Ten en cuenta que los patrones de URL que usan localhost no son compatibles con esta función.

Importante: Los usuarios que puedan instalar y usar tu complemento pueden actualizar los vínculos a archivos adjuntos de complementos apenas el equipo de Classroom habilite los parámetros de configuración. Por eso, es importante proporcionar primero las configuraciones para tu complemento de prueba dentro de un entorno de prueba o desarrollo antes de proporcionar cualquier configuración de producción.

Escribe el formato del correo electrónico para incluir lo siguiente:

Google Cloud Project number: GCP_PROJECT_NUMBER

Link Upgrade iframe URL: LINK_UPGRADE_IFRAME_URL

URL Patterns:
- Host:HOST_1
- Path prefixes:
  - PATH_PREFIX_1
  - PATH_PREFIX_2

- Host:HOST_2
- Path prefixes:
  - PATH_PREFIX_3
  - PATH_PREFIX_4

// add more hosts and path prefixes as needed

Reemplaza lo siguiente:

• GCP_PROJECT_NUMBER: Es el número del proyecto de Google Cloud con el que está asociado el complemento.
• LINK_UPGRADE_IFRAME_URL es la URL que se debe abrir en el iframe de Actualización de vínculos.
• HOST_1: Es un host que Classroom debe detectar. Solo se admite el esquema https.
• PATH_PREFIX_1 y PATH_PREFIX_2: Son los prefijos de ruta de acceso asociados con HOST_1 que Classroom debe detectar y, luego, intentar actualizar.
• HOST_2: Es un host que Classroom debe detectar. Solo se admite el esquema https.
• PATH_PREFIX_3 y PATH_PREFIX_4: Son los prefijos de ruta de acceso asociados con HOST_2 que Classroom debe detectar y, luego, intentar actualizar.

Experiencia del usuario recomendada

Las siguientes son sugerencias que debes tener en cuenta cuando implementes esta función.

Evita el trabajo extra de los profesores

Te recomendamos que utilices el iframe para facilitar el acceso, si es necesario, o para mostrar un indicador de carga. Para brindar la mejor experiencia del usuario, no se le debe solicitar al profesor información adicional después de que haya acordado actualizar el vínculo pegado a un archivo adjunto de complemento. Sin embargo, si esto no es posible para tu complemento, puedes utilizar el iframe de Actualización de vínculos para recopilar la información adicional que necesites. El iframe también se puede usar para informar al profesor si no es posible actualizar el vínculo o si se produjo un error.

Incluye mensajes de error de acceso fáciles de usar

Si los profesores pegan y actualizan un vínculo al que no tienen acceso, muestra un mensaje de error fácil de usar en el iframe para que los profesores estén al tanto del problema. El iframe también se puede usar para proporcionarle al profesor los permisos adecuados para acceder al contenido.