BigCommerce es el nuevo vecino en el barrio de las plataformas de eCommerce. Ha llegado con fuerza y ha venido para quedarse. En realidad llevan mas de 10 años en el mercado, pero su expansión se ha producido fundamentalmente dentro del mundo anglosajón y solo en los últimos años se ha convertido en una plataforma de referencia a nivel mundial.

BigCommerce es un SaaS lo que lo hace similar en varios aspectos a Shopify, su mas directo competidor. Frente a éste destaca por sus capacidades para SEO, con una excelente velocidad de carga; y también por sus capacidades analíticas.

En España cada vez son mas las tiendas que deciden pasarse a esta plataforma y en Ebolution como partners certificados de BigCommerce, cada vez son mas los proyectos basados en esta plataforma.

Este artículo hablamos de uno de los mecanismos que tiene BigCommerce para extender su funcionalidad: las Apps. Además de presentar el esquema básico de una App para BigCommerce, como parte de mi trabajo en Ebolution he desarrollado un módulo que incluye toda la funcionalidad básica para crear tus Apps. Este módulo ha sido cedido por Ebolution como OpenSource con licencia MIT y puedes usarlo libremente para crear tu próxima App para BigCommerce.

Cómo extender BigCommerce

BigCommerce es un SaaS. Esto tiene la ventaja de que alquilas una tienda completamente funcional, y que no te tendrás que preocuparte por la operación de los servidores ni por las actualizaciones del producto.

La contrapartida es que las capacidades de personalización que tienes son algo menores que en otro tipo de plataformas como Magento (Adobe Commerce) o Prestashop, donde tienes prácticamente un control total.

En BigCommerce hay tres forma de modificar el comportamiento out-of-the-box de tu tienda:

• A través de la configuración en el panel de control: muchos aspectos del comportamiento del eCommerce se ofrecen como opciones configurables en el panel de control de la tienda. Hay una configuración a nivel de store (back-office) y una configuración a nivel de store-front (front-office).
• A través del tema de la tienda: BigCommerce viene con una serie de temas predefinidos que nosotros podemos descargar y personalizar a nuestro antojo (tenemos control completo del código del tema).
• A través de una App: las Apps permiten crear funciones nuevas que BigCommerce no incluye. Como en todas las plataformas de eCommerce, existe un marketplace donde podemos acudir a buscar una App ya desarrollada que cubra nuestras necesidades. Y si no existe o no las cubre de forma adecuada, podemos crear nuestra propia App para BigCommerce.

Implementar una funcionalidad nueva en BigCommerce suele implicar utilizar una o varias de estas estrategias. Los casos mas simples se suelen resolver simplemente con configuración, pero los casos mas complejos suelen involucrar una App que extiende el modelo de datos de BigCommerce, junto con su panel de control para administrar éstos datos y una API que permite que el tema de la tienda consuma la información almacenada en la App.

En este artículo –el primero de una serie de dos– nos vamos a centrar en cómo crear nuestra propia App para BigCommerce partiendo del módulo bigcommerce-app-adapter que puedes descargarte de GitHub. En el segundo artículo de la serie mostraremos un ejemplo de como crear un aplicación sencilla que demuestre como este módulo interactúa con BigCommerce y con nuestra App.

Qué es una App de BigCommerce

Como hemos visto antes básicamente una App es una extensión de la plataforma de eCommerce.

La App debe estar alojada en un servidor/infraestructura independiente de BigCommerce. Cuando creamos una App tenemos completa libertad para usar el stack tecnológico que prefiramos.

Una App para BigCommerce típicamente incluye:

• Una base de datos que extiende el modelo de datos de BigCommerce con datos adicionales o entidades nuevas.
• Un servidor de aplicaciones con la lógica de negocio y los componentes internos de la App.
• Una API REST para:
  • Gestionar la comunicación con BigCommerce.
  • Proveer a la tienda de servicios adicionales (ej. acceso a las nuevas entidades del modelo de datos).
• Una librería Javascript para integrar las funciones de la App con el tema de la tienda. En el mejor de los casos la App provee de un script que se inyecta en el tema y que es capaz de modificar el comportamiento de la tienda sin que el desarrollador conozca los detalles internos de implementación de la App.

Las Apps disponibles en el marketplace de BigCommerce está alojadas y operadas por sus respectivos creadores. Usar una App suele conllevar un pago mensual por el servicio, aunque los proveedores suelen ofrecer un periodo gratuito de evaluación.

Si nosotros vamos a crear nuestra propia App, lo primero que tenemos que pensar es en cómo y dónde la vamos a alojar, aunque como veremos mas adelante, las primeras etapas del desarrollo se pueden llevar a cabo en un entorno local basado en Docker, con la ayuda de alguna herramienta.

Creando nuestra primera App

Para crear una App lo primero que hay que hacer es conectarse al Developer Portal de BigCommerce para crear el perfil básico de la App (inicialmente en modo borrador).

Necesitarás tener acceso a una tienda de BigCommerce para poder entrar en el portal de desarrolladores. Si simplemente estás evaluando la plataforma, puedes crear una tienda de forma gratuita que estará activa por un periodo de 15 días. Sin embargo, si realmente piensas crear una App para BigCommerce, te aconsejo que consigas una tienda sandbox (no se borra), a través de los programas de partners de BigCommerce.

Cuando crees una nueva App, lo primero que vas a tener que indicar es su nombre:

Luego hay que establecer una serie de datos básicos en la sección de App Summary:

De momento no te preocupes si no tienes o no conoces el Partner ID. Solo será necesario para publicar la App.

No es estrictamente obligatorio, pero si muy recomendable que incluyas un logo y un icono para tu App, que describas brevemente su cometido y que le asignes una categoría:

Gestionando los usuarios de nuestra App

Cuando instalamos una App en nuestra tienda de BigCommerce, generalmente creamos una cuenta de servicio dentro del servidor en el que está alojada la App. Las Apps del marketplace están diseñadas como otro SaaS y desde el punto de vista del proveedor son multi-tenant.

BigCommerce se encarga de gestionar el dialogo con la App para decir en cada momento qué tienda es la que está conectándose y que usuario de la tienda está haciendo uso de la App.

Cualquier App que creemos debe llevar a cabo una gestión básica de usuarios y tiendas. Incluso en el caso que desarrollemos una aplicación llave en mano para un solo cliente, debemos poder gestionar las conexiones que crea BigCommerce con sus códigos de autorización y en muchos casos también necesitamos conocer el usuario concreto del back-office de la tienda que hace uso de la App.

Esto nos lleva a crear una primera entidad que toda App va a necesitar para la gestión de tiendas y usuarios. La aproximación mas sencilla que podemos plantear pasa por definir una nueva entidad que hemos llamado ‘bc_authorized_users’.

Esta entidad tiene las siguientes atributos:

• id: identificador secuencial de cada registro.
• store_hash: identifica el store de BigCommerce.
• access_token: representa la autorización que nos da BigCommerce para que nuestra App pueda hacer uso de los datos de la tienda a través de llamadas a la API de BigCommerce.
• user_id: id del usuario conectado dentro de la tienda de BigCommerce.
• user_email: e-mail del usuario conectado (para enviar notificaciones).
• created_at / updated_at: campos para auditoría.

bigcommerce-app-adapter gestiona las conexiones a nivel del usuario conectado al back-office. En algunos casos se podría hacer una gestión mas simple creando una única conexión por tienda que estaría asociada al usuario que tiene el rol de propietario de la tienda (el que instaló la App).

bigcommerce-app-adapter asume que se ha configurado la App de esta manera (sección Technical), aunque funcionaría de forma correcta en el caso de que se configure como ‘Store owner’ en cuyo caso solo habrá un registro por tienda en nuestra tabla ‘bc_authorized_users’.

Conectando nuestra App con BigCommerce

Para que nuestra App se comunique con BigCommerce es necesario que creemos una API con cuatro end-points muy concretos:

• Auth: Se invoca cuando se instala la App en una tienda. Entre otras cosas, la llamada nos indica el store_hash de la tienda, el owner_id y el access_token con el que podemos hacer llamadas a la API de BigCommerce. La respuesta normal a este callback es una redirección a la home de nuestra App, tras almacenar en bc_authorized_users los datos de la autorización para usar la App concedida al owner de la tienda.
• Load: Se llama cada vez que un administrador carga la App desde el panel de control de BigCommerce. La respuesta normal a este callback también es una redirección a la home de nuestra App (o a la URL que se indique en la llamada). En esta llamada BigCommerce nos indica el user_id del usuario administrador que está cargando la aplicación, el owner_id y el store_hash de la tienda.
• Uninstall: Se llama al desinstalar la aplicación de una tienda. Como respuesta se borran los usuarios autorizados para este store.
• Remove User (no es necesario si se ha configurado Multiple Users como Store Owner): Esta llamada pide que se de de baja un usuario concreto de la aplicación, pero no la aplicación en si misma. Como respuesta se borra el registro de bc_authorized_users asociado al usuario.

Las URLs de estos end-points se denominan URLs de Callback y necesitarán ser configuradas en la sección Technical de la configuración de la App:

Este es el aspecto que tendría la configuración de nuestra App basada en bigcommerce-app-adapter asumiendo que esté alojada en my-hosted-app.site. El módulo implementa internamente el dialogo a llevar a cabo con BigCommerce para cada una de estas cuatro callbacks.

Asignando permisos

Si nuestra App va a interactuar con los datos de BigCommerce, lo cual será lo mas habitual, debemos asegurarnos de que damos a la App permisos suficientes como para llevar a cabo las llamadas a la API de BigCommerce que vaya a realizar.

Siguiendo el Principle of Least Privilege (PoLP), solo daremos los permisos imprescindibles para que la aplicación pueda funcionar.

Para saber los permisos que necesitamos, lo primero que tendremos que hacer es listar las llamadas que hacemos a la API de BigCommerce. Luego tendremos que buscar la documentación de la API. En la sección Authentication hay un botón Show details que nos mostrará los permisos que la llamada requiere:

Por ejemplo, si vamos a hacer una llamada GET a ‘Get All Categories’, necesitamos el scope ‘store_v2_products_read_only’, que se obtiene con el permiso read-only en la entidad Products. Estos permisos se configuran en la sección OAuth scopes dentro de la pestaña Technical del perfil de la aplicación.

Para hacer el desarrollo inicial de nuestra App no es necesario que hagamos configuraciones adicionales. Sí tendremos que revisar y cumplimentar el resto de las secciones antes de poder enviar la App al marketplace.

bigcommerce-app-adapter

bigcommerce-app-adapter es un módulo pensado como base para la creación de una App para BigCommerce genérica. Resuelve cuatro aspectos fundamentales:

• Implementa las cuatro callbacks que requiere BigCommerce (auth, load, uninstall, remove user) y por tanto se encarga de gestionar la comunicación con BigCommerce.
• Mantiene la entidad bc_authorized_users con las lista de usuarios que han sido autorizados a usar la App desde BigCommerce, y sus códigos de autorización correspondientes.
• Provee de un proxy a la API de BigCommerce de forma que nuestra App pueda acceder a los datos de nuestro store de acuerdo con los permisos concedidos a la App.
• Habilita de un mecanismo para el desarrollo local de la App sin necesidad de ser invocada desde dentro de BigCommerce.

bigcommerce-app-adapter está implementado en PHP y usa el paradigma de la arquitectura hexagonal. La capa de infraestructura está implementada con Laravel, pero gracias a su arquitectura sería fácilmente adaptable a otros frameworks.

Puedes descargarte el módulo de GitHub.

En la segunda parte de este artículo te vamos a explicar cómo crear una aplicación en Laravel con una funcionalidad muy sencilla, pero que nos permite demostrar como usar este módulo para crear una App con una funcionalidad arbitraria.

Si no quieres esperar, lee el archivo Readme.md con las instrucciones sobre como instalar y configurar el módulo y sobre como funciona el flujo de seguridad a través de tokens JWT.

Para añadir el módulo a tu proyecto Laravel usa los siguientes comandos:

composer config repositories.ebolution-bigcommerce-app-adapter git https://github.com/ebolution/bigcommerce-app-adapter.git 
composer require ebolution/bigcommerce-app-adapter:dev-master