Configuración del proyecto de Google Cloud

En esta página, se incluye la información que necesitas saber para crear y configurar proyectos de Google Cloud para los complementos de Classroom. Los proyectos de Google Cloud se usan para implementar el inicio de sesión único de Google a través de OAuth 2.0 (SSO de Google), para autorizar las solicitudes que realiza tu complemento y para administrar la ficha de un complemento en Google Workspace Marketplace.

Para obtener información más general sobre cómo publicar un complemento en Marketplace, consulta Cómo publicar una app.

Creación de proyectos de Google Cloud

Punto clave: Tu aplicación de complemento de producción debe tener la visibilidad establecida como pública en el SDK de Google Workspace Marketplace. Un proyecto privado puede ser útil para desarrollar y probar tu complemento, pero solo se requiere uno público.

Existen dos tipos de proyectos que puedes crear: un proyecto privado que se usa para el desarrollo y un proyecto público al que pueden acceder los usuarios finales. Las etiquetas "pública" y "privada" hacen referencia a la visibilidad de tu aplicación en Google Workspace Marketplace. Una aplicación privada de Marketplace solo la pueden instalar los usuarios del dominio en el que se creó, mientras que una aplicación pública de Marketplace está disponible para cualquier dominio de Google Workspace. Deben ser dos aplicaciones separadas, ya que un proyecto no puede ser público y privado al mismo tiempo. Las aplicaciones públicas deben revisarse y aprobarse antes de estar disponibles en el mercado.

Importante: No puedes convertir un proyecto privado en uno público.

Para obtener información general sobre la creación de proyectos de Google Cloud, visita Crea un proyecto de Google Cloud.

Crea un proyecto público de Google Cloud

Este proyecto representa la aplicación del complemento a la que pueden acceder administradores, profesores y estudiantes. El equipo de Google Workspace Marketplace debe revisar y aprobar un proyecto público antes de que se pueda lanzar o instalar.

1. Crea un proyecto nuevo de Google Cloud en tu dominio de producción.

   Crea un proyecto de Google Cloud

   Importante: Asegúrate de que el proyecto pertenezca a tu dominio de producción y de que hayas accedido a la consola de Google Cloud como usuario de ese dominio.
   Advertencia: Debes usar la versión Borrador de tu proyecto para realizar pruebas. Para obtener más información, consulta Actualiza tu ficha de la app con borradores.

2. Habilita la API de Classroom en tu proyecto de Cloud.

   Habilita la API de Classroom

3. Habilita el SDK de Google Workspace Marketplace en tu proyecto de Cloud.

   Habilita el SDK de Google Workspace Marketplace

4. Establece la Configuración de la app de Visibilidad de la app del SDK de Marketplace en Pública y marca la casilla No listada.

   Punto clave: No puedes compartir ni convertir un proyecto privado que se usó durante el desarrollo y las pruebas internos.
   Punto clave: Las apps no publicadas no se pueden encontrar en Google Workspace Marketplace a través de la navegación o la búsqueda. En la configuración del SDK de Marketplace, puedes encontrar una URL directa que se puede usar para instalar el complemento. Solo Google y el desarrollador pueden encontrar la ficha de Play Store. Tu app debe permanecer como no listada hasta que te sientas a gusto con su lanzamiento al público general. Puedes activar o desactivar si un complemento aparece en la página Configuración de la app del SDK de Marketplace.

5. Completa los campos obligatorios en la página Ficha de Play Store del SDK de Marketplace y haz clic en PUBLICAR.

6. El equipo de Google Workspace Marketplace revisará tu app. Se comunicarán contigo a través de la dirección de correo electrónico del desarrollador especificada en el SDK de Marketplace. Después de que se apruebe la app, desmarca la casilla Sin listar para que los profesores y administradores puedan encontrarla en Marketplace.

Crea un proyecto privado de Google Cloud

Este proyecto privado representa la aplicación de complemento que se usa para el desarrollo. No es accesible para los usuarios fuera del dominio en el que se creó, pero no necesita aprobación antes de la instalación. Por lo tanto, Google recomienda usar este proyecto para desarrollar y probar tu complemento en un entorno controlado.

Para crear un proyecto privado, debes tener acceso a un dominio de Google Workspace for Education con la licencia de Teaching & Learning o Plus. Si aún no tienes acceso a un dominio de este tipo, sigue estos pasos para configurar un dominio de demostración de Google Workspace for Education, actualizarlo a una licencia de Plus y permitirle acceder a la API de complementos de Classroom:

1. Completa los pasos para obtener un dominio de prueba para desarrolladores.

2. Mientras accedes como administrador en el dominio de demostración, crea un proyecto nuevo de Google Cloud.

   Crea un proyecto de Google Cloud

   Advertencia: Asegúrate de que el proyecto pertenezca al dominio de demostración y de que hayas accedido a la consola de Google Cloud con una cuenta de administrador del dominio de demostración.

   Si no puedes acceder a la consola de Google Cloud ni crear proyectos de Cloud, verifica lo siguiente en la consola del administrador:

   • Visita la página Configuración de la cuenta > Configuración de acceso según la edad y selecciona la opción Todos los usuarios de este grupo o unidad organizativa son mayores de 18 años.
   • En Apps > Servicios adicionales de Google, haz lo siguiente:
   • Google Cloud Platform está ACTIVADO para todos.
   • La configuración de creación del proyecto es Permite que los usuarios creen proyectos.
   • La configuración de acceso a Cloud Shell es Permitir acceso a Cloud Shell.

3. Completa y envía el formulario de solicitud de actualización del dominio de demostración. Si envías este formulario, solicitas que Google actualice tu dominio de demostración a Google Workspace for Education Plus con diez licencias y que tu proyecto de Cloud pueda acceder a la API de complementos de Classroom.

   Recibirás un correo electrónico cuando se completen los procesos de actualización y de inclusión en la lista de entidades permitidas. Asigna licencias de Plus a las cuentas de profesores de prueba en la Consola del administrador. En Directorio > Usuarios, crea o selecciona tus cuentas de profesor de prueba. En las Licencias de cada profesor, confirma que Google Workspace for Education Plus esté Asignado.

4. Habilita la API de Classroom en tu proyecto de Cloud.

   Habilita la API de Classroom

5. Habilita el SDK de Google Workspace Marketplace en tu proyecto de Cloud.

   Habilita el SDK de Google Workspace Marketplace

6. Configura la visibilidad de la app de la configuración de la app del SDK de Marketplace como privada.

7. Completa los campos obligatorios en la página Ficha de Play Store del SDK de Marketplace y haz clic en PUBLICAR. Después de que se publique la ficha de la app, los usuarios del dominio podrán encontrarla e instalarla en Google Workspace Marketplace o visitando la URL de la app que se muestra en la página de la ficha de Play Store.

OAuth 2.0

El acceso a la API de Classroom requiere el consentimiento para acceder a los datos del usuario. Estos se obtienen solicitando acceso de Google a los permisos de OAuth para el usuario que accedió y recibiendo un token que se puede usar posteriormente para realizar llamadas a la API de Google Classroom. Los alcances se deben configurar en la ficha de Play Store de Google Workspace Marketplace para que el administrador del dominio pueda otorgar el consentimiento en nombre de los usuarios del dominio si instalan el complemento.

Importante: Si tu complemento solicita permisos adicionales, inclúyelos en la pantalla de consentimiento de OAuth, en la pestaña Configuración de la app del SDK de Marketplace, y en el código de la aplicación del complemento. Los alcances que no coinciden en estas ubicaciones pueden causar problemas a los usuarios durante la instalación de complementos.

Dado que los permisos de Classroom son sensibles, debes solicitar la verificación de OAuth antes de lanzar tu complemento. De lo contrario, los usuarios verán un mensaje de advertencia que indica que la aplicación no está verificada, y solo una pequeña cantidad de usuarios podrá acceder a tu producto. Consulta la descripción general de la secuencia de revisión para obtener más información sobre la verificación.

Advertencia: Si usas un proyecto existente de Google Cloud para desarrollar un complemento, no solicites los nuevos alcances en el código de los productos existentes hasta que se complete la verificación. Usa un flujo de autorización independiente, un entorno de pruebas o configura una marca de función para solicitar estos permisos solo para las rutas relacionadas con tus complementos antes de completar la verificación.

Consulta la página Permisos de OAuth para las APIs de Google para obtener una lista detallada de todos los permisos disponibles y sus usos. Consulta Configura la página de OAuth en la documentación de Workspace para obtener información general sobre la configuración de OAuth.

Permisos de usuario

Tu app web debe solicitar al menos uno de los siguientes permisos:

• https://www.googleapis.com/auth/userinfo.email, que permite que una aplicación vea la dirección de correo electrónico del usuario.
• https://www.googleapis.com/auth/userinfo.profile, que permite que una aplicación vea información personal, como el retrato, el nombre y el apellido, y otra información personal que el usuario haya puesto a disposición del público.

Después de que un usuario autoriza uno de estos alcances en tu complemento, se lo identifica con el parámetro de consulta login_hint. Este parámetro se pasa a cualquiera de las URLs de tu app web cuando se abre un iframe. Si un usuario no autorizó uno de estos alcances, no se enviará login_hint.

Advertencia: Tu app debe solicitar al menos uno de los permisos de userinfo.email o userinfo.profile para recibir login_hint en visitas posteriores del mismo usuario.

login_hint es un parámetro estándar de OpenID Connect que puedes pasar de forma opcional a Google cuando usas el Acceso con Google o solicitas un token de OAuth. Su objetivo es que la experiencia de autorización sea más fluida para el usuario final.

Permisos de los complementos de Classroom

Los siguientes permisos son específicos de los complementos de Classroom:

• https://www.googleapis.com/auth/classroom.addons.teacher, que permite el acceso a todos los métodos de la API.
• https://www.googleapis.com/auth/classroom.addons.student, que permite el acceso a las operaciones de lectura de validación y adjuntos de lanzamiento.

Incluso con un token de acceso de OAuth válido que indica las credenciales del usuario, las llamadas a la API están controladas por requisitos adicionales:

• Todos los métodos requieren que el usuario sea profesor o estudiante del curso especificado por courseId en la solicitud.
• La creación, actualización, eliminación y devolución de calificaciones de archivos adjuntos requieren que el usuario sea profesor.
• Las llamadas a una publicación específica de Google Classroom están controladas por las siguientes verificaciones.
  • Cuando un complemento ya tiene al menos un adjunto en una publicación, puede realizar solicitudes para lo siguiente:
    • Validación del inicio de iframe
    • Operaciones de lectura, actualización y eliminación de archivos adjuntos
    • Actualizaciones de calificaciones en esa publicación
  • Cuando se abre por primera vez el iframe de Attachment Discovery, es posible que el complemento aún no tenga un archivo adjunto en la publicación. Se proporciona un parámetro de consulta addOnToken que se puede usar para realizar solicitudes de lo siguiente:
    • Crear un adjunto en la publicación (se requiere addOnToken)
    • Validación de lanzamiento (addOnToken se valida si se proporciona y es obligatorio cuando el complemento no tiene un archivo adjunto existente en la publicación)

Verificación de OAuth

Nota: No puedes crear un video de demostración para enviarlo como parte del proceso de verificación de OAuth. En su lugar, publica el complemento sin verificar OAuth. Si lo haces, se alertará al equipo de revisión de Google Workspace Marketplace para que cree un video de demostración en tu nombre. Luego, el equipo de revisión te proporcionará el video para que lo incluyas en el envío de verificación de OAuth.

Un complemento de Classroom usa las APIs de Google para acceder a los datos de los usuarios de Google.

• Verifica la identidad de tu marca.
• Verifica los permisos sensibles de OAuth.

Consulta las Preguntas frecuentes sobre la verificación de la API de OAuth para obtener más información sobre el proceso de verificación.

Ficha de Google Workspace Marketplace

Advertencia: Una vez que guardes tu opción de visibilidad durante el proceso de publicación, no podrás cambiar tu selección más adelante.

Para obtener información general sobre la configuración del SDK de Google Workspace Marketplace, consulta Cómo habilitar y configurar el SDK de Google Workspace Marketplace y Cómo crear una ficha de Google Workspace Marketplace.

Consideraciones sobre la ficha

La ficha de Marketplace SDK Store de tu proyecto público de Google Cloud especifica el nombre y las descripciones de tu aplicación que se muestran a los usuarios finales. Puedes proporcionar estos detalles en varios idiomas en Detalles de la app.

Sigue estos lineamientos en tus fichas:

• En App Details, haz lo siguiente:
  • Evita usar signos de puntuación en el nombre de la aplicación. Por ejemplo, usa "Mi complemento de Mi empresa" en lugar de "Mi empresa: Mi complemento" o "Mi complemento de Mi empresa".
  • La Descripción breve y la Descripción detallada no deben contener exactamente el mismo texto.
  • Asegúrate de haber seleccionado un valor para el campo Precios. Este campo incluye opciones de precios Gratis, Pagada con prueba gratuita, Pagada con funciones gratuitas y Pagada. No es necesario que especifiques el importe del costo en la ficha de Marketplace.
  • Asegúrate de haber seleccionado un valor para el campo Categoría. Recursos académicos o Herramientas para profesores y administradores podrían ser buenas opciones para un complemento de Classroom.
  • Consulta los elementos que se indican en la descripción de los detalles de la app de Marketplace para obtener más información.

Importante: Revisa los detalles de la app para cada idioma en el que ofreces tu complemento.

• En Recursos gráficos, haz lo siguiente:
  • Los recursos gráficos proporcionados no son borrosos y cumplen con los tamaños especificados en los estándares de Google Workspace Marketplace
  • Las capturas de pantalla proporcionadas son representaciones precisas de la experiencia de tu complemento.
• En Vínculos de asistencia, haz lo siguiente:
  • Asegúrate de haber proporcionado un vínculo a las Condiciones del Servicio de tu aplicación.
• Asegúrate de cumplir con los Lineamientos de desarrollo de la marca de las APIs de Google, que abarcan los nombres y las descripciones permitidos.
• Si mencionas algún producto de Google en tu ficha, usa su nombre en el formato que se proporciona en la Lista de marcas. Asegúrate de incluir el símbolo de marca comercial (™) si se especifica; usa "Google Docs™", no "Google Docs".

Integración con los servicios de facturación y licencias de Google

Si te interesa que tus aplicaciones de Google Workspace Marketplace se integren con los servicios de facturación y licencias de Google, visita la API de Marketplace.

Configuración de la instalación

Los complementos pueden permitir la instalación individual además de la instalación del administrador. En esta página, se destacan algunas diferencias entre los dos tipos de instalación, pero no se pretende promover ninguno de ellos. Puedes elegir si permites la instalación individual en la página de configuración de la app del SDK de Google Workspace Marketplace.

Instalación del administrador

Las instalaciones del administrador permiten que un administrador agregue un complemento a todas las cuentas de un dominio o a grupos de acceso o unidades organizativas específicos. Solo un administrador del dominio puede realizar una instalación de administrador. De manera opcional, el administrador puede dar su consentimiento para todos los alcances de acceso en nombre de todos los usuarios del dominio. Si el administrador decide hacerlo, no se les pedirá a los usuarios que den su consentimiento para ningún alcance de acceso.

A continuación, se incluyen algunas consideraciones sobre la instalación del administrador.

• Controles más estrictos. Los administradores pueden restringir el acceso a un complemento a ciertos usuarios.
• Compatibilidad con licencias. Si tu aplicación requiere una licencia, canalizar las instalaciones a través de un administrador puede ayudar a garantizar que las licencias se distribuyan y utilicen de manera adecuada con la institución correspondiente.
• Reduce la carga de los usuarios finales. La instalación del administrador reduce la carga de configuración para profesores y estudiantes. Esto podría generar una experiencia del usuario más fluida con menos clics y menos oportunidades de confusión.

Consulta Cómo instalar apps de Marketplace en tu dominio para obtener más información sobre cómo realizar instalaciones de administrador y Cómo funciona la estructura organizativa para obtener más información sobre las unidades organizativas y los grupos de acceso.

Instalación individual

Las instalaciones individuales agregan un complemento a la cuenta del usuario. Durante la instalación, se le solicita al usuario que dé su consentimiento para los permisos de acceso del complemento.

A continuación, se incluyen algunas consideraciones sobre la instalación individual.

• Facilita la adopción. Más usuarios pueden ver e instalar tu complemento desde Google Workspace Marketplace. Permitir la instalación individual puede motivar a más profesores a adoptar tu producto o recomendarlo.
• Pruebas de administrador. Un administrador puede instalar individualmente un complemento para probarlo o evaluarlo antes de aprobarlo o instalarlo para un grupo más amplio.

Además de instalar complementos en nombre de los usuarios, los administradores también pueden mantener una lista de entidades permitidas para que los usuarios instalen complementos que permitan la instalación individual. Si un complemento no está en la lista de entidades permitidas, los usuarios podrán ver su ficha en Google Workspace Marketplace, pero no podrán instalarlo. En su lugar, verán un mensaje que explica que un administrador del dominio no permitió la instalación del complemento. Consulta Cómo administrar las apps de Google Workspace Marketplace en tu lista de entidades permitidas para obtener más información sobre este comportamiento.

Consulta la documentación sobre la configuración de instalación de Google Workspace Marketplace para obtener más información.

Integraciones de la app

Debes proporcionar una URL de iframe de inicio en el campo URI de configuración del adjunto. Esta URL se usa como el valor src del iframe para el iframe de Attachment Discovery. Los profesores usan el iframe de Attachment Discovery para encontrar contenido o actividades que adjuntar a sus tareas. Se puede configurar en la consola del proyecto de Google Cloud.

Los prefijos de URI de archivos adjuntos permitidos se usan para validar los URI establecidos en un AddOnAttachment con los métodos *.addOnAttachments.create y *.addOnAttachments.patch. La validación es una coincidencia literal del prefijo de cadena y no permite el uso de comodines.

También debes especificar todos los prefijos de URI desde los que se permiten archivos adjuntos de tu complemento. Esta función aumenta la seguridad, ya que evita que se adjunten archivos de fuentes no autorizadas.

Establece ambos valores en la página Configuración de la app del SDK de Marketplace de tu proyecto de Google Cloud.

Cuentas de prueba

Crea cuentas de prueba en tu dominio de demostración para verificar el comportamiento correcto de tu complemento privado. Se necesitan dos cuentas de estudiantes para probar el cambio entre estudiantes en el iframe de Student Work Review.

Cuentas de prueba sugeridas:

• Profesora Tamara, tammy.teacher@<tu dominio de demostración>
• Sam Student, sam.student@<tu dominio de demostración>
• Sally Student, sally.student@<tu dominio de demostración>

Sigue este procedimiento para crear una nueva cuenta de prueba:

1. Accede a la Consola del administrador.
2. Navega a Usuarios.
3. Haz clic en Agregar un usuario nuevo (consulta la Figura 1).
4. Ingresa la información del usuario y asígnale los roles adecuados.

Figura 1: Ubicación del vínculo Agregar usuario nuevo en la Consola del administrador.

Sigue este procedimiento para crear un nuevo grupo de prueba:

1. Accede a la Consola del administrador.
2. Navega a Grupos.
3. Haz clic en Crear grupo (ver la figura 2).
4. Ingresa los miembros y propietarios del grupo.

Figura 2: Ubicación del vínculo Crear grupo en la Consola del administrador.