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 capacidad, 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 pedirá 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ínculo 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 de complemento. Luego, puedes usar los otros parámetros de consulta para verificar si el usuario accedió y llamar al CreateAddOnAttachment método 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 de complemento.

Una vez que se crea el archivo adjunto de 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 está codificado como URI cuando se pasa al iframe de actualización de vínculo. Debes decodificar la URL para obtenerla en su forma original. Si usas JavaScript, por ejemplo, puedes usar la función decodeURIComponent() para hacerlo.

Cierra el iframe de actualización de vínculo

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 de complemento. Esto cierra el iframe. Consulta la página de detalles de la implementación de 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ínculo: Es la URL que se abre en el iframe cuando un profesor acepta actualizar.

• 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 ningún prefijo 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 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:
    • 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 los componentes del prefijo de ruta de acceso solo coincide con un solo componente y no con varios componentes separados por barras. Considera un patrón de URL con el host example.com y el prefijo de ruta de acceso /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 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 la URL del iframe de actualización de vínculo y los patrones de URL para tu complemento de prueba o producción por correo electrónico a [e-mail].

Puedes proporcionar configuraciones 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 activos.

Recibirás una respuesta a tu correo electrónico cuando se hayan habilitado 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 las configuraciones. Por eso, es importante proporcionar primero las configuraciones para tu complemento de prueba en un entorno de prueba o desarrollo antes de proporcionar cualquier configuración de producción.

Da 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 debe abrirse en el iframe de actualización de vínculo.
• 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 tratar de 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 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 brindar la mejor experiencia del usuario, no se le debe solicitar al profesor información adicional después de que haya aceptado actualizar el vínculo pegado a un archivo adjunto de complemento. Sin embargo, si esto no es posible para tu complemento, puedes usar el iframe de actualización de vínculo 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 proporcionar al profesor los permisos adecuados para acceder al contenido.