Mejora la experiencia general de los usuarios con estas guías para el diseño de complementos.
Prácticas recomendadas generales
Te recomendamos que sigas las siguientes prácticas recomendadas para todos los complementos que desarrolles.
Determina la propiedad de los complementos antes de comenzar
Los complementos se definen en proyectos de Apps Script, que deben ser propiedad de una cuenta específica o ubicarse en una unidad compartida. Antes de programar un complemento, determina qué cuenta debe ser la propietaria del proyecto y qué cuenta actúa como su publicador. Además, determina qué cuentas actuarán como colaboradores y asegúrate de que esas cuentas tengan acceso al proyecto de secuencia de comandos y a su proyecto de Cloud Platform asociado.
Extiende Google Workspace, no lo repliques
Los complementos están diseñados para proporcionar capacidades nuevas a las aplicaciones de Google Workspace que extienden o automatizar tareas complejas. Es probable que los complementos que simplemente replican una funcionalidad que ya está dentro de la aplicación o aquellos que no replican mejoras significativas en un flujo de trabajo no pasen la revisión de complementos para su publicación.
Mantén los alcances limitados
Cuando definas tus alcances de forma explícita, siempre elige el conjunto de alcances con el menor permiso posible. Por ejemplo, no
tengas a tu solicitud de complemento acceso completo al Calendario del usuario con el
permiso https://www.googleapis.com/auth/calendar
si solo necesita acceso de
lectura. Para el acceso de solo lectura, usa el permiso https://www.googleapis.com/auth/calendar.readonly
.
Evita depender demasiado de las bibliotecas
El uso de las bibliotecas de Apps Script puede hacer que el complemento se ejecute más lentamente de lo que lo haría si todo el código de Apps Script estuviera dentro de un solo proyecto de secuencia de comandos. Aunque las bibliotecas de Apps Script funcionan con complementos, es posible que se produzcan reducciones de rendimiento si los usas. Evita incluir bibliotecas innecesarias en tu proyecto y considera formas de reducir la dependencia de tu complemento en ellas.
La latencia descrita anteriormente solo se aplica a los proyectos de Apps Script que se usan como bibliotecas del servidor. Puedes usar bibliotecas de JavaScript del cliente, como jQuery, con libertad sin encontrar esta latencia.
Prácticas recomendadas para el complemento de Google Workspace
Las siguientes prácticas recomendadas solo se aplican a los complementos de Google Workspace y al uso del servicio de tarjetas.
Usa solo algunas tarjetas
Si el complemento usa demasiadas tarjetas, la configuración de navegación se vuelve compleja y difícil de administrar.
Evita el impulso de crear más tarjetas de las necesarias.
Usa las funciones de creación de widgets
Cuando escribas código que cree Card
u otros objetos de IU complejos, procura colocar ese código en su propia función.
Esta función de creación solo debe compilar el objeto y mostrarlo. Esto te permite volver a generar con rapidez ese objeto cada vez que se debe actualizar la IU. Recuerda llamar a build()
después de usar las clases de compilador en el servicio de tarjetas.
Tarjetas simples
Si una tarjeta determinada tiene demasiados widgets, puede llenar demasiado de la pantalla y volverse menos útil. Si bien las secciones grandes de tarjetas se renderizan como elementos de la IU que se pueden contraer, esto oculta la información del usuario. Intenta optimizar tu complemento y proporcionar exactamente lo que el usuario necesita y nada más.
Usar tarjetas de error
Crea tarjetas para las condiciones de error. Si el complemento produce un error, debería mostrar una tarjeta con la información del error y las instrucciones para corregirlo, si es posible. Por ejemplo, si tu complemento no pudo conectarse a un servicio ajeno a Google porque falló la autorización, muestra una tarjeta que lo indique y pídele al usuario que verifique la información de la cuenta que se está usando.
Cómo escribir pruebas y mensajes de prueba
Debes probar por completo todos los complementos que crees. Compila funciones de prueba que crean tarjetas y widgets con datos de prueba y, luego, verifica que los objetos se creen como se espera.
Por lo general, cuando usas funciones de devolución de llamada de acción, debes construir un objeto de respuesta. Puedes usar declaraciones como las siguientes para verificar que las respuestas se estén construyendo de forma correcta:
Logger.log(response.printJson());
Ejecuta las funciones de prueba que creas directamente desde el editor de Apps Script mediante el menú Ejecutar. Cuando tengas un complemento viable, asegúrate de instalar la versión no publicada para que puedas probarlo.
Usar datos de prueba adecuados para cada aplicación de host que extienda el complemento Por ejemplo, si el complemento extiende Gmail, es probable que necesites algunos correos electrónicos de prueba y sus IDs de mensaje para asegurarte de que el complemento funcione como se espera cuando se recibe contenido de mensajes diferente. Si quieres obtener el ID de un mensaje determinado, puedes enumerarlos con el método Users.messages.list de la API de Gmail o si usas el servicio de Gmail de Apps Script.
Prácticas recomendadas para reuniones en Calendario
Si tu complemento integra opciones de conferencias de calendario de terceros en Calendario de Google, sigue estas prácticas recomendadas adicionales:
Mantén la luz de tu onCreateFunction
Se llama de forma síncrona a cada onCreateFunction
que definas en tu manifiesto cuando un usuario intenta crear una solución de conferencia de ese tipo. Asegúrate de que estas funciones solo hagan el trabajo
mínimo necesario para crear la conferencia. Si usas demasiado estas funciones, es posible que la experiencia del usuario con el complemento sea lenta.
Usa los campos ConferenceData
apropiados para los datos de la conferencia
Cuando compilas objetos ConferenceData
, puedes propagarlos con detalles sobre la conferencia (códigos de acceso, números de teléfono, pines, URIs, etcétera). Asegúrate de usar el campo EntryPoint
correspondiente para esta información. No coloques estos detalles en el campo de notas ConferenceData
.
No agregar detalles de la reunión al evento de Calendario de Google
El complemento no necesita agregar información sobre las conferencias de terceros creadas a la descripción del evento de Calendario de Google. El Calendario de Google lo hace automáticamente cuando es necesario.