Añade superpoderes de búsqueda a tu sitio con Algolia

La mayoría de las soluciones de búsqueda te obligan a elegir: o son potentes pero difíciles de configurar, o son sencillas pero limitadas. Algolia no es ninguna de las dos cosas. Es un servicio de búsqueda completo con un generoso plan gratuito, una API amigable para desarrolladores y, como te mostraré aquí, puede mantenerse perfectamente sincronizado con el CMS de Webflow de forma automática mediante webhooks. Configúralo una vez y tu contenido estará indexado y listo para ser buscado en minutos. Además, más allá de la búsqueda en sí, el panel de control de Algolia te ofrece una ventana a cómo la gente lo utiliza realmente: qué buscan y dónde podría haber lagunas en tu contenido.

Llevo años usando Algolia en mi blog personal y gestiona mis casi 7,000 publicaciones sin despeinarse. Su política de precios es increíblemente buena: el plan gratuito cubre mucho terreno y puede manejar bastantes sitios, lo que significa que, como mínimo, te permite empezar antes de que necesites considerar pasar a un plan de pago superior. En esta publicación, te guiaré a través de la integración con un sitio de Webflow, manteniendo las cosas lo más sencillas posible.

¿Qué necesitas?

Por parte de Webflow, necesitarás un plan CMS, ya que así es como realizaré la integración. Algolia también tiene una opción de rastreador web (crawler), pero en esta publicación nos centraremos en la opción del CMS.

Para Algolia, necesitarás una cuenta. Usaré el plan gratuito, así que no hay costes involucrados. Ese plan gratuito cubre 10,000 solicitudes y un millón de registros. Requiere un poco más de configuración, pero lo trataré más adelante.

¡Muy bien, empecemos!

El contenido

Antes de empezar, ten en cuenta que Algolia puede trabajar con cualquier tipo de datos: publicaciones de blog, productos, reseñas, gatos y más. A Algolia no le importa la forma de tus datos siempre que puedan convertirse a JSON. También puedes trabajar con múltiples tipos de contenido diferentes. Para mantener las cosas simples en esta demostración, usaré una colección de Publicaciones de blog. Esto se basa en la muestra predeterminada del CMS de Webflow para publicaciones de blog y consta de:

• Nombre
• Slug
• Cuerpo
• Fecha de publicación

Crea esta colección y anota el valor del ID. Lo necesitarás más adelante.

Cuando Webflow te ofrezca crear contenido generado por IA, te recomiendo aceptarlo, ya que creará un buen contenido inicial para hacer pruebas. Obviamente, si ya tienes una colección CMS con contenido y estás siguiendo esta guía, ¡no tienes de qué preocuparte!

El índice de Algolia

Algolia funciona mediante un índice de tu contenido. Puedes pensarlo como una copia de tu contenido, pero no necesariamente una copia exacta. Por ejemplo, tu contenido puede incluir propiedades que no tienen sentido para la búsqueda. También puede incluir propiedades que quieras modificar antes de que se indexen. Lo que entra en el índice depende de ti y de las necesidades específicas de búsqueda de tu sitio.

Pero el punto crucial es este: Algolia no puede buscar algo que no está en tu índice. Eso significa que deberás asegurarte de que el contenido de tu sitio de Webflow se mantenga sincronizado con tu índice.

Anteriormente, te pedí que crearas una cuenta de Algolia. Si ya lo hiciste y has iniciado sesión en tu panel de control, puedes hacer clic en "Search" en el menú de navegación izquierdo, bajo "Products". (Nota: es posible que al principio se te pida crear una aplicación). Esta aplicación es muy parecida a un espacio de trabajo en Webflow. Puedes usar una aplicación como contenedor para tus índices y crear varias aplicaciones si lo deseas.

Debes crear un índice para tu sitio, normalmente con un nombre relevante para que sea fácil de encontrar más tarde.

Después de crear tu índice, llegarás a una nueva página de índice. Aquí podrás explorar el contenido y probar la búsqueda, una vez que hayas indexado algo.

Como mencioné, hay una gran cantidad de configuraciones que puedes realizar para personalizar cómo se descubre tu contenido. La documentación de Algolia es bastante exhaustiva y te recomiendo encarecidamente que le eches un vistazo.

A estas alturas, deberías tener:

• Un sitio en Webflow con una colección CMS y algo de contenido. No importa cuánto, pero al menos un par de entradas.
• Un índice de Algolia vacío, esperando tus datos.

Obtén tus credenciales de Algolia

Los siguientes pasos requerirán ciertas credenciales de parte de Algolia, concretamente:

• El ID de la aplicación de Algolia
• La clave API de Algolia
• La clave API de búsqueda de Algolia
• El nombre del índice de Algolia

Ya tienes el nombre del índice, solo asegúrate de recordarlo. Para obtener tu ID de aplicación, en el panel de control, fíjate en el menú desplegable "Application" en la parte superior de la pantalla. Al hacer clic, verás una lista de aplicaciones junto con sus ID:

Puedes hacer clic en el pequeño icono de "copiar" para guardar el valor en tu portapapeles, o simplemente tener mejor memoria que yo.

Para tu clave API, ve a la configuración (icono de engranaje en la parte inferior izquierda), haz clic en "API Keys" y, en esta página, verás varias claves diferentes. La que está marcada como "Search API Key" y documentada como "segura para tu código frontend" se usará más adelante cuando creemos la interfaz de búsqueda en nuestro sitio de Webflow. Cópiala para tenerla a mano.

La siguiente, "Write API Key", es la que nuestro código usará para trabajar con el índice de Algolia. Esta no es segura para el público, pero sí para nuestro código backend. Cópiala también.

Alimentar el índice

Llegados a este punto, estamos listos para empezar nuestra integración, pero hay algo que debemos hacer primero. Tengo contenido existente que quiero volcar en el índice. Si estás creando un sitio nuevo y aún no tienes contenido, puedes saltarte a la siguiente sección. En el futuro, si necesitas crear un nuevo índice y volver a poblarlo, ¡este script hará exactamente eso! Nuestro script es un archivo Node.js que puede ejecutarse en tu máquina; no hay necesidad de alojarlo.

Para que nuestro script funcione, necesitaremos la clave API de Algolia mencionada anteriormente, el ID del CMS y una clave API de Webflow que permita operaciones de lectura del CMS. Creé un archivo .env con estos ajustes:

WF_API_KEY=my secret key
WF_COLLECTION_ID=6998dce17a56281f1afc766c

ALGOLIA_APP_ID=0FJBPN4K5D
ALGOLIA_API_KEY=my secret key
ALGOLIA_INDEX_NAME=webflow1

Nuestro script necesita hacer dos cosas básicas:

• Primero, conectarse a Webflow y obtener nuestros elementos del CMS.
• Enviar estos datos a Algolia

Vamos a desglosar el script, poco a poco.

Primero, leo del entorno toda la información que necesito y creo una instancia del SDK de Algolia:

/*
I'm responsible for reading from the Webflow CMS and populating into an Algolia index.

In theory, I should only be run once, but if you clear out the index you can run this again.
*/
import { algoliasearch as algoliaSearch } from 'algoliasearch';

const WF_API_KEY = process.env.WF_API_KEY;
const WF_COLLECTION_ID = process.env.WF_COLLECTION_ID
const ALGOLIA_APP_ID = process.env.ALGOLIA_APP_ID;
const ALGOLIA_API_KEY = process.env.ALGOLIA_API_KEY;
const ALGOLIA_INDEX_NAME = process.env.ALGOLIA_INDEX_NAME;

if(!WF_API_KEY || !WF_COLLECTION_ID|| !ALGOLIA_APP_ID || !ALGOLIA_API_KEY || !ALGOLIA_INDEX_NAME) {
  console.error('Missing environment variables. Please set WF_API_KEY, WF_COLLECTION_ID, ALGOLIA_APP_ID, ALGOLIA_API_KEY, and ALGOLIA_INDEX_NAME.');
  process.exit(1);
}

const algolia = algoliaSearch(ALGOLIA_APP_ID, ALGOLIA_API_KEY);

A continuación, necesito obtener todos los datos de la colección CMS. El endpoint List Live Items hará esto. Devuelve un conjunto de datos paginado, así que escribí mi función para manejar eso y seguir obteniendo datos hasta que todo esté recuperado.

async function getCMSItems(cmsid, apikey) {
    let results = [];
    let hasMore = true;
    let offset = 0;
    while (hasMore) {
        const response = await fetch(`https://api.webflow.com/v2/collections/${cmsid}/items/live?limit=100&offset=${offset}`, {
            headers: {
                'Authorization': `Bearer ${apikey}`
            }
        });
        const data = await response.json();
        results = results.concat(data.items);
        hasMore = data.pagination.total > offset + 100;
        offset += 100;
    }
    return results;
}

let items = await getCMSItems(WF_COLLECTION_ID, WF_API_KEY);
console.log(`Fetched ${items.length} items from Webflow CMS.`);

En este punto, deberías tener una matriz de elementos de tu CMS de Webflow. El SDK y las API de Algolia admiten tanto operaciones atómicas como operaciones por lotes. Y lo que es mejor, admiten una operación de "actualización" que funciona tanto para datos antiguos como nuevos, lo que simplifica la creación de tu código.

Como puedes imaginar, Algolia tiene un amplio conjunto de operaciones de API y múltiples SDK diferentes. Mi código utiliza el SDK de Node, y puedes consultar la documentación aquí.

Mi script hace uso de la operación batch, que básicamente te permite tomar cualquier lista de operaciones y realizarlas con una sola llamada. El resto del script muestra esto en acción:

let requests = [];
items.forEach(item => {
    requests.push({
        action: 'updateObject', 
        body: {
            objectID: item.id,
            name: item.fieldData.name,
            slug: item.fieldData.slug,
            body: item.fieldData.body,
            published: new Date(item.lastPublished).getTime(),
            // could also include lastUpdated
        }
    });
});

let algoliaResponse = await algolia.batch({
    indexName: ALGOLIA_INDEX_NAME,
    batchWriteParams: {
        requests
    }  
});

console.log('Done with inserts, check response to be sure.');

Aunque este código es bastante breve, hay algunos puntos importantes que debemos tener en cuenta:

• Lo que incluyas en el índice determina directamente cómo busca la gente en tu sitio y qué resultados obtiene. En el código anterior elegí name, slug, body y published, pero vale la pena pensarlo bien para tu propio sitio y contenido. El único valor realmente obligatorio es objectID, que es como Algolia identifica tu contenido. Esto es lo que hace que updateObject funcione tan bien. Le indico cuál es el ID único de mi contenido y él se encarga de reconocer si se trata de una entrada nueva en el índice o de una actualización. Recuerda: puedes cambiar y modificar los datos antes de enviarlos. Yo no lo hago aquí, pero podría enviar una parte del cuerpo del contenido en lugar de todo. Podría añadir valores nuevos que ni siquiera están en mi CMS. Incluso podría tomar dos colecciones de CMS en Webflow y combinarlas en un solo índice. Como dice el código,
• debería comprobar el resultado para ver si todo está bien, pero el panel de control de Algolia lo hace bastante sencillo. En cuanto esto se ejecuta, puedo empezar a ver mi contenido.
  

Ten en cuenta que el panel de control también te permite realizar búsquedas. Es una forma rápida de verificar que Algolia ha recibido tu contenido correctamente.

Antes de continuar, asegurémonos de que entendemos exactamente lo que hemos hecho hasta ahora:

• Tenemos un índice de Algolia para almacenar nuestro contenido. Creamos un script que lee
• toda nuestra colección del CMS de Webflow y la añade.

Puedes encontrar el script completo aquí.

Conexión entre Webflow y Algolia

Ya tenemos el índice de Algolia, ahora viene la parte divertida: mantener el índice sincronizado con los datos de Webflow. Por suerte, esto se puede hacer mediante webhooks. Los webhooks te permiten pedirle a Webflow que llame a un servicio externo cuando se realiza un cambio en tu sitio. Hay muchos tipos de eventos a los que puedes conectarte, pero para lo que necesitamos, nos interesan dos:

• collection_item_published collection_item_unpublished

Para actuar sobre esos eventos, necesitarás un gestor de webhooks, un pequeño fragmento de código backend que reciba la solicitud de Webflow y decida qué hacer con ella. En nuestro caso, eso significa decirle a Algolia que añada, actualice o elimine contenido del índice. Para ello, tendrás que registrar dos webhooks en tu sitio, pero necesitarás conocer la URL donde residirá tu lógica personalizada. Este es un momento excelente para recurrir a Webflow Cloud. Podemos alojar el gestor de webhooks directamente en nuestro sitio y mantener todo unido en una misma plataforma.

Para empezar con Webflow Cloud, crea un proyecto nuevo, selecciona la plantilla de inicio de aplicaciones y configúrala como una aplicación dentro de tu sitio. Una vez desplegada, tendrás la URL que necesitas para registrar tus webhooks.

Preparé una nueva aplicación Astro y, en mi directorio pages, creé api/contentChange.json.js. Usaré un solo archivo y un único endpoint para ambos webhooks, con lógica interna para reconocer si el contenido se añadió o se eliminó.

Así es como lo gestioné:

export const prerender = false;
import crypto from 'crypto';

import { algoliasearch as algoliaSearch } from 'algoliasearch';


export async function POST({ params, request, locals }) {

    const ALGOLIA_APP_ID = locals.runtime.env.ALGOLIA_APP_ID || process.env.ALGOLIA_APP_ID;
    const ALGOLIA_API_KEY = locals.runtime.env.ALGOLIA_API_KEY || process.env.ALGOLIA_API_KEY;
    const ALGOLIA_INDEX_NAME = locals.runtime.env.ALGOLIA_INDEX_NAME || process.env.ALGOLIA_INDEX_NAME;

    const WEBHOOK_PUBLISH_SECRET = locals.runtime.env.WEBHOOK_PUBLISH_SECRET || process.env.WEBHOOK_PUBLISH_SECRET;
    const WEBHOOK_UNPUBLISH_SECRET = locals.runtime.env.WEBHOOK_UNPUBLISH_SECRET || process.env.WEBHOOK_UNPUBLISH_SECRET;


    const body = await request.json();

    let wh_secret;
    let algoliaAction;

    // validate it's a trigger we handle
    if(body.triggerType !== 'collection_item_published' && body.triggerType !== 'collection_item_unpublished') {
        return new Response(JSON.stringify({ success: false, error: 'Invalid trigger type' }), { status: 400 });
    } else {
        if(body.triggerType === 'collection_item_published') {
            wh_secret = WEBHOOK_PUBLISH_SECRET;
            algoliaAction = 'updateObject';
        } else {
            wh_secret = WEBHOOK_UNPUBLISH_SECRET;
            algoliaAction = 'deleteObject';
        }
    }

    let ts = request.headers.get('x-webflow-timestamp');
    let sig = request.headers.get('x-webflow-signature');
    let isValid = verifyWebflowSignature(wh_secret, ts, JSON.stringify(body), sig);

    if(!isValid) {
        return new Response(JSON.stringify({ success: false, error: 'Invalid signature' }), { status: 400 });
    }

    console.log(`Valid webhook, send to Algolia with action ${algoliaAction}`);
    const algolia = algoliaSearch(ALGOLIA_APP_ID, ALGOLIA_API_KEY);

    let requests = [];
    if(algoliaAction === 'updateObject') {
        // when a CMS publish event is fired, it's an array
        body.payload.items.forEach(item => {
            requests.push({
                action: algoliaAction, 
                body: {
                    objectID: item.id,
                    name: item.fieldData.name,
                    slug: item.fieldData.slug,
                    body: item.fieldData.body,
                    published: new Date(item.lastPublished).getTime(),
                    // could also include lastUpdated
                }
            });
        });
    } else {
        // but a CMS unpublish event is just a single item
        requests.push({
            action: algoliaAction, 
            body: {
                objectID: body.payload.id
            }
        });
    }

    let algoliaResponse = await algolia.batch({
        indexName: ALGOLIA_INDEX_NAME,
        batchWriteParams: {
            requests
        }  
    });
    console.log('Algolia response', algoliaResponse);

    return new Response(JSON.stringify({ success: true }));
}

function verifyWebflowSignature(clientSecret, timestamp, requestBody, providedSignature) {
  try {
    const requestTimestamp = parseInt(timestamp, 10);
    const data = `${requestTimestamp}:${requestBody}`;
    const hash = crypto.createHmac('sha256', clientSecret)
                      .update(data)
                      .digest('hex');
    if (!crypto.timingSafeEqual(Buffer.from(hash, 'hex'), Buffer.from(providedSignature, 'hex'))) {
      throw new Error('Invalid signature');
    }
    const currentTime = Date.now();
    if (currentTime - requestTimestamp > 300000) { // 5 minutes in milliseconds
      throw new Error('Request is older than 5 minutes');
    }
    return true; // The request is valid
  } catch (err) {
    console.error(`Error verifying signature: ${err.message}`);
    return false;
  }
}

Analicemos esto. La funcionalidad principal recae en el método POST; es la forma en que Astro dice: "Ejecuta este código cuando se realice una solicitud HTTP POST a este endpoint". Obtengo todas mis variables de entorno y notarás que, aunque ya hablamos de las tres primeras, también tenemos valores secretos relacionados con los webhooks. Cuando creamos los webhooks en el panel de control de Webflow, el resultado es una clave especial. Esta clave se utiliza para verificar que el webhook provenga directamente de Webflow. (Todo esto se gestiona en verifyWebflowSignature).

El siguiente paso es observar el cuerpo de la solicitud del webhook. Si se trata de una publicación, configuramos la acción de Algolia como updateObject; de lo contrario, será deleteObject.

Una vez verificada la solicitud del webhook, volvemos al SDK de Algolia y realizamos la actualización. Ten en cuenta que vuelvo a utilizar el proceso por lotes (batch), ya que es posible que se publiquen o despubliquen varios elementos a la vez.

Una vez que la aplicación Astro esté desplegada en tu sitio, tendrás una URL adecuada que podrás usar al registrar el webhook en el sitio de Webflow. Esta dependerá del dominio de tu sitio y de cómo hayas desplegado tu aplicación de Webflow Cloud.

Para mis pruebas, la ruta de montaje fue /algolia. Mi sitio se publica en https://algolia-testing.webflow.new. Juntando todo, mis webhooks deben usar esta URL: https://algolia-testing.webflow.new/algolia/api/contentChange.json. Creé uno para ambos webhooks (se crean en la sección "Apps & Integrations" de la configuración de tu sitio), copié las claves y me aseguré de configurarlas como variables de entorno.

Nota: En el momento en que se creó esta publicación, no es posible registrar un webhook que apunte al dominio predeterminado webflow.io. En su lugar, debes usar un dominio personalizado. Este problema ya ha sido registrado y se corregirá en el futuro.