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

Una forma en que los profesores pueden agregar contenido de terceros a Classroom es pegar un vínculo como Vínculo adjunto 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 solicitará a los profesores que actualicen un vínculo a uno de estos archivos cuando peguen un archivo adjunto de vínculo en la página de creación de tareas. Solo se 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 lanzados en el iframe de descubrimiento de archivos adjuntos. El parámetro de búsqueda urlToUpgrade es nuevo y puede ayudarte a evaluar cómo se debe crear el 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 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 verlo 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.

Leer el parámetro de consulta urlToUpgrade

El parámetro de búsqueda urlToUpgrade tiene codificación de URI cuando se pasa en el iframe de actualización de vínculos. Debes decodificar la URL para obtener su forma 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 se haya creado correctamente el archivo adjunto del 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ínculos: 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 consistir en 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 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 de 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 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 del prefijo de ruta de acceso no coincide con /123/456/.

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

Proceso de desarrollo

Envía un correo electrónico a [e-mail] para enviar los patrones de URL y la URL de iframe de actualización del vínculo 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 estos parámetros de configuración de prueba antes de habilitar los 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 hayan habilitado los parámetros de configuración. 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 estos en cuanto el equipo de Classroom habilite los parámetros de configuración. Por eso es importante proporcionar primero los parámetros de configuración para tu complemento de prueba dentro de un entorno de prueba o desarrollo antes de brindar cualquier configuración de producción.

Dale formato al correo electrónico para que incluya la siguiente información:

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

A continuación, se incluyen sugerencias que debes tener en cuenta cuando implementes esta función.

Evita el trabajo adicional de los profesores

Te recomendamos que uses 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 debe solicitar al profesor información adicional después de que acepte actualizar el vínculo pegado a un archivo adjunto del complemento. Sin embargo, si esto no es posible con tu complemento, puedes usar el iframe de actualización de vínculos para recopilar la información adicional que necesites. El iframe también se puede usar para informarle al profesor si no es posible actualizar el vínculo o si se produjo un error.

Incluye mensajes de error de acceso fácil 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 estén al tanto del problema. El iframe también se puede usar para proporcionarle al profesor los permisos adecuados que le permitan acceder al contenido.