Los complementos de Google Classroom ya están en fase de disponibilidad general para desarrolladores. Consulta la documentación sobre complementos para obtener más información.

Se usó la API de Cloud Translation para traducir esta página.

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 un 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 solicitará 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á 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 lanzaron en el iframe de Attachment Discovery. El parámetro de búsqueda 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 de la implementación técnica

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 en el 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 la vinculación.

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

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.
- 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 búsqueda ni fragmentos de URL.
- Por el momento, los prefijos de ruta pueden admitir comodines, pero los hosts no:
  - 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 los componentes del prefijo de ruta solo coincide con un 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 la ruta de acceso no coincide con /123/456/.

Proceso de desarrollo

Envía la URL del iframe de actualización de vínculos y los patrones de URL de tu complemento de prueba o producción por correo electrónico a classroom-link-upgrade-external@google.com.

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, de modo 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 los parámetros de configuración. Ten en cuenta que esta función no admite los patrones de URL que usan localhost.

Formatea el correo electrónico para que incluya 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 se asocia 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 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 prefijos de ruta de acceso asociados con HOST_2 que Classroom debe detectar y tratar de 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 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 ninguna 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 Link Upgrade 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 conozcan el problema. El iframe también se puede usar para otorgarle al profesor los permisos adecuados para acceder al contenido.