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

Una forma en que los profesores agregan contenido de terceros a Classroom es pegando un vínculo como Archivo adjunto de vínculo en la página de creación de tareas. Para aprovechar lo que los profesores ya conocen, ahora puedes configurar tu complemento para permitir que los profesores actualicen un archivo adjunto de vínculo a un archivo adjunto de complemento.

Descripción general

Si configuras tu complemento con esta función, se les pedirá a los profesores que actualicen un vínculo a un archivo adjunto de 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 instalado el complemento.

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

• courseId
• itemId
• itemType
• addOnToken
• urlToUpgrade
• login_hint (solo si el usuario ya autorizó tu app)

Los primeros cuatro parámetros de consulta reflejan los parámetros de consulta que se inician 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 consulta para verificar si el usuario accedió y llamar al método CreateAddOnAttachment de courseWork, courseWorkMaterials o announcements según el valor de 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 que se crea 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 de la función.

Lee el parámetro de consulta urlToUpgrade

El parámetro de consulta urlToUpgrade se codifica en URI cuando se pasa al iframe de actualización de vínculos. Debes decodificar la URL para obtenerla en su forma original. Por ejemplo, si usas JavaScript, puedes usar la función decodeURIComponent() para hacerlo.

Cierra el iframe de actualización de vínculos.

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

Detalles de configuración

Se requieren las siguientes configuraciones para integrar esta función en tu complemento:

• URL del iframe de actualización de vínculos: Esta es la URL que se abre en el iframe cuando un profesor acepta 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.

  • Puedes proporcionar varios patrones de URL.
  • Si no proporcionas ningún prefijo de ruta, 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 contener localhost.
  • Los prefijos de ruta de acceso no deben contener parámetros de consulta ni fragmentos de URL.
  • Por el momento, los prefijos de ruta de acceso pueden admitir comodines, pero los hosts no pueden hacerlo:
    • example.com es un host válido y /foo y /bar/*/baz son prefijos de ruta válidos.
    • example.*.host.com no es un host válido.
  • Un comodín entre componentes de prefijo de ruta solo coincide con un solo componente y no con varios componentes separados por barras diagonales. Considera un patrón de URL con el host example.com 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 ruta no coincide con /123/456/.

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

Proceso de desarrollo

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

Puedes proporcionar parámetros de configuración para cualquier proyecto de Google Cloud que represente un complemento de Classroom. Te recomendamos que primero proporciones configuraciones para un complemento con visibilidad privada para que puedas desarrollar y probar en un dominio de demostración sin afectar a los usuarios en vivo.

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 pueden instalar y usar tu complemento pueden actualizar los vínculos a archivos adjuntos de complementos en cuanto el equipo de Classroom habilite la configuración. Por este motivo, es importante que primero proporciones configuraciones para tu complemento de prueba en un entorno de prueba o de desarrollo antes de proporcionar cualquier configuración de producción.

Dale formato al 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 debería detectar. Solo se admite el esquema https.
• PATH_PREFIX_1 y PATH_PREFIX_2: Son prefijos de ruta asociados con HOST_1 que Classroom debe detectar y tratar de actualizar.
• HOST_2: Es un host que Classroom debería detectar. Solo se admite el esquema https.
• PATH_PREFIX_3 y PATH_PREFIX_4: Son prefijos de ruta asociados con HOST_2 que Classroom debe detectar y tratar de actualizar.

Experiencia del usuario recomendada

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

Evita el trabajo adicional para los profesores

Te recomendamos que uses el iframe para facilitar el acceso, si es necesario, o mostrar un indicador de carga. Para garantizar la mejor experiencia del usuario, no se le debe solicitar información adicional al profesor después de que acepte actualizar el vínculo pegado a un archivo adjunto del complemento. Sin embargo, si esto no es posible para tu complemento, puedes usar el iframe de Link Upgrade para recopilar la información adicional que necesitas. 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 entender para los usuarios

Si los profesores pegan y actualizan un vínculo al que no tienen acceso, se mostrará 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.