Impulsando las aplicaciones de Webflow: Cómo construimos las API del Diseñador - Parte 1

Esto incluye a todos, desde el emprendedor que construye su agencia hasta el equipo de marketing de una empresa Fortune 500 que entrega resultados a millones de personas, y todos los que están en medio. Planeamos lograr esto de varias maneras, pero un método fundamental es ampliar las capacidades de nuestro ecosistema de aplicaciones. Por eso, en agosto de 2023 lanzamos nuestra nueva plataforma para desarrolladores para permitir que nuestra comunidad cree aplicaciones que puedan ser utilizadas por todos los clientes de Webflow.

Una parte de nuestra plataforma para desarrolladores son nuestras API del Diseñador, que impulsan las aplicaciones de extensión del Diseñador. Estas API permiten a los desarrolladores interactuar directamente con el lienzo de Webflow mediante la gestión de elementos, estilos, metadatos de página y más. Estas API deben exponerse de forma segura, permitiendo a los desarrolladores sentir el mismo poder que ofrece nuestro Diseñador. Para hacer realidad esta idea, necesitábamos encontrar una forma concisa y potente de permitir que los desarrolladores interactuaran con la lógica interna de nuestra arquitectura frontend: el Diseñador de Webflow.

Integración de aplicaciones sin complicaciones

Para garantizar una conexión segura entre el cliente (la aplicación de un desarrollador externo) y el host (el Diseñador de Webflow), necesitábamos una forma de que los desarrolladores crearan una aplicación en su IDE preferido pero la lanzaran en el Diseñador con acceso a todas las API. Al pensar en un SDK de frontend, lo habitual es que los desarrolladores lo instalen vía npm o referencien un paquete de JavaScript mediante CDN que exponga varios métodos globales. Esto funciona bien para algunos casos, pero queríamos la capacidad de lanzar nuevas API o correcciones de errores de inmediato sin tener que publicar un nuevo paquete npm y obligar a los desarrolladores a instalarlo. Optamos por una arquitectura para servir aplicaciones de forma segura que tengan todas las API del Diseñador más recientes y avanzadas disponibles tan pronto como se lanzan. Funciona así:

• Construcción: El desarrollador crea su aplicación como una aplicación de una sola página, utilizando su tecnología preferida (React, Vue, JavaScript, etc.).
• Empaquetado: Publicamos una herramienta CLI para permitir a los desarrolladores ejecutar un solo comando para empaquetar su aplicación y subirla a Webflow. También hay un comando que se puede usar al desarrollar una aplicación en localhost.
• Lanzamiento: Las aplicaciones en el Diseñador se inyectan en un iframe. Antes de que se renderice su punto de entrada (index.html), primero inyectamos nuestro propio paquete de JavaScript de la API del Diseñador en el head de su HTML. Esto expone todas las API del Diseñador a la aplicación y permite que la última versión de cada API esté disponible tan pronto como se lanza.
• Seguridad: La aplicación se aloja en un dominio separado del Diseñador de Webflow para ayudar a mitigar ataques de cross-site scripting (XSS). Además, hemos configurado una política de seguridad de contenido para garantizar que la aplicación solo se cargue donde esperamos.

Comunicación entre la aplicación y Webflow

Una vez que se lanza una aplicación y le inyectamos nuestro paquete de JavaScript, necesitamos una forma de comunicarnos entre el iframe (la aplicación) y el host (el Diseñador de Webflow). Para esto, usamos window.postMessage (documentación de MDN) junto con una biblioteca interna de JSON-RPC para enviar JSON entre las dos fuentes. Debemos asegurarnos de que la carga útil enviada desde la aplicación sea válida, por lo que tenemos una capa intermedia que valida el JSON. Aquí hay un ejemplo de lo que sucede cuando estableces el título de una página usando page.setTitle():

Procesamiento de la solicitud

La lógica central de las API del Diseñador reside dentro del código base del Diseñador de Webflow, al que llamamos "host". Internamente, usamos una arquitectura Flux para gestionar el estado en toda la aplicación. Por lo tanto, muchas de las API del Diseñador aumentan el estado o envían una acción de Flux. Un ejemplo de alto nivel de cómo procesamos una solicitud sería el siguiente ejemplo para actualizar el título de una página:

// logic in the "host" (Webflow Designer codebase)
designerApiResponder(setPageTitle, (state, payload) => {
  const {pageId, title} = payload;
  const page = state.PagesStore.getById(pageId);
  if (!page) return {status:'Error', value: 'ResourceMissing'};
  const updatedState = {
    ...state,
    PagesStore: updatePageTitle(pageId, title),
  };
  return [
    {status: 'Success', value: null},
    updatedState
  ];
});

El código anterior se puede desglosar en estos componentes:

• Configuramos un "respondedor" que escucha la ejecución de la API setPageTitle.
• Una vez que se ha ejecutado la API (y ya hemos validado la carga útil), obtenemos la página por su ID desde PagesStore.
  • Si no encontramos la página, devolvemos una respuesta de error que el cliente gestiona.
• Luego, fusionamos el estado actualizado en PagesStore.
  • Internamente, escuchamos las actualizaciones de estado y sincronizamos los datos con el servidor si se detectan cambios.
• Finalmente, devolvemos una tupla (una matriz con dos elementos).
  • El primer elemento de la matriz es la respuesta que queremos devolver al cliente. En el ejemplo anterior, devolvemos null para esta API.
  • El segundo elemento es el estado actualizado. Tenemos un reductor de Flux que toma este segundo elemento de la matriz y lo fusiona con el estado principal del Diseñador de Webflow.

El host maneja tanto la obtención como la actualización del estado, dependiendo de la API que se ejecute. Internamente, tenemos una cola de solicitudes para asegurarnos de realizar un seguimiento de los éxitos y fallos de cada API, de modo que podamos devolver la respuesta adecuada. El host responde con un estado y los datos de respuesta para que el cliente sepa si debe lanzar una excepción o devolver la respuesta. Cada API tiene una respuesta definida (publicamos algunos tipos de TypeScript para ayudar con esto). Si la respuesta es un error, tenemos una lista de posibles "causas" de error que un desarrollador puede leer para determinar qué salió mal. Aquí hay un ejemplo de cómo manejar un error:

try {
  const style = await webflow.createStyle('Heading');
  await style.setProperty('someIncorrectProp', '10px');
} catch (error) {
  const tag = error.cause.tag;
  const message = error.message;
  if (tag === 'InvalidStyleProperty') {
    alert('Invalid style property used');
  }
  console.log(message);
}

Solo estamos empezando

Las aplicaciones en todo el ecosistema de Webflow se vuelven más fuertes e impresionantes mediante el uso de las API del Diseñador. Seguimos ampliando las capacidades de estas API y nos esforzamos por poner gran parte del poder del Diseñador en manos de los desarrolladores. Desde el lanzamiento de nuestras API, los desarrolladores han creado aplicaciones potentes que han aumentado la productividad de sus usuarios y facilitado tareas que antes eran complejas. Hay aplicaciones en el marketplace que llevan el poder de la IA al Diseñador de Webflow, ayudan a crear archivos SVG complejos arrastrando y soltando un archivo, y mucho más.

Mantenemos la experiencia del desarrollador, el rendimiento y la seguridad como prioridades mientras iteramos. Creemos que al permitir que los desarrolladores creen aplicaciones nuevas y eficaces, estamos brindando superpoderes de desarrollo a todos. Mantente atento a la segunda parte de esta serie, donde profundizaremos en la optimización del rendimiento de varias API del Diseñador y cómo estamos trabajando para que la experiencia sea más rápida y fácil de usar para los desarrolladores.