El texto alternativo en imágenes es uno de esos aspectos que todo el mundo sabe que importa, pero que rara vez recibe la atención que merece. Para sitios con cientos o miles de imágenes, escribir descripciones manualmente resulta repetitivo y fácil de postergar. Esta necesidad llevó a crear un generador de texto alternativo con inteligencia artificial para WordPress, un proyecto que combina visión artificial, un backend escalable y una integración limpia con el ecosistema de plugins. Sin embargo, el verdadero valor no está solo en generar alt text, sino en hacerlo de forma fiable, segura y medible. Durante el desarrollo surgieron lecciones que van mucho más allá de la IA: la telemetría bien diseñada, la prevención de duplicados en eventos, el rastreo de acciones a través de múltiples sistemas y la privacidad por defecto. Aquí compartimos esas enseñanzas, desde la perspectiva de Q2BSTUDIO, empresa especializada en aplicaciones a medida y soluciones tecnológicas avanzadas.
El plugin se apoya en una arquitectura que va más allá del típico script de WordPress. Por un lado, el panel de administración en PHP gestiona la biblioteca de medios, mientras que un backend en Node.js alojado en Render procesa las solicitudes de generación. Los datos de suscripciones y uso residen en Supabase, los pagos se gestionan con Stripe y la analítica se recoge con PostHog. El flujo comienza cuando el usuario solicita generar alt text para una o varias imágenes; el plugin envía una petición autenticada al backend, que valida la cuota disponible, envía la imagen a un servicio de visión por IA, guarda el resultado y devuelve la descripción. Todo esto parece sencillo, pero cada paso introdujo desafíos que obligaron a repensar el diseño.
El primer gran reto fue la telemetría. En un momento dado, las métricas mostraban '4 inicios de generación' y '13 finalizaciones', lo que parecía un error de duplicados. La causa real era que 'inicio' medía trabajos (jobs) y 'finalización' medía imágenes individuales dentro de un trabajo por lotes. Comparar ambas métricas directamente era como comparar viajes al supermercado con productos comprados. La solución fue definir eventos semánticos claros: generation_job_started, generation_item_completed, generation_job_completed y generation_job_failed. Cada trabajo recibe un generation_run_id único, y cada imagen un generation_item_id. Esto permite responder preguntas concretas: cuántos trabajos comenzaron, cuántas imágenes se procesaron, cuántos trabajos finalizaron con éxito y cuántos ítems fallaron dentro de un lote. La lección es que la semántica de los eventos importa tanto como recolectarlos.
El segundo desafío fue evitar duplicados en la telemetría. Los eventos pueden dispararse múltiples veces por clics repetidos, rerenderizados, reintentos o emisiones desde frontend y backend simultáneamente. Para hacerlo tolerante a reintentos, se añadieron identificadores estables de PostHog ($insert_id) y se definió qué sistema es propietario de cada evento: el frontend registra la intención del usuario (como hacer clic en un botón de actualizar), el backend registra la creación exitosa de un Checkout Session, los webhooks de Stripe determinan la finalización del pago y la activación de la suscripción, y el backend registra el alt text solo después de haberlo persistido. Esto evita que una misma acción se cuente dos o tres veces por diferentes partes de la aplicación.
El tercer reto fue rastrear una acción a través de varios sistemas. Un proceso de pago puede pasar por WordPress, el backend, Stripe, su webhook, Supabase y PostHog. Sin un identificador compartido, depurar ese viaje es tedioso. Se introdujeron correlation_id, checkout_attempt_id, generation_run_id, signup_attempt_id, session_id y site_install_id. Estos identificadores permiten seguir una misma acción desde el plugin hasta los servicios externos. Cuando un checkout se abandona o un inicio de sesión falla, el mismo correlation_id aparece en todos los sistemas, en lugar de tener que buscar por marcas de tiempo desconectadas.
El cuarto reto fue la telemetría segura de autenticación. Un evento genérico de 'login_failed' no es útil porque no indica si la causa fue credenciales incorrectas, cuenta deshabilitada, limitación de tasa, timeout de red, API no disponible, fallo en creación de token o fallo en almacenamiento de sesión. Se implementó una taxonomía interna de errores controlada, con mensajes públicos genéricos para no revelar si una cuenta existe. Se registran códigos internos como invalid_credentials, account_disabled, rate_limited, network_timeout, api_unavailable, token_creation_failed, session_creation_failed y unknown_auth_error. Contraseñas, tokens y respuestas crudas se eliminan antes de enviar la telemetría.
El quinto reto fue la privacidad por defecto. La analítica de producto puede convertirse rápidamente en un problema de privacidad si no se cuida. La capa de telemetría elimina campos como direcciones de correo, licencias, tokens, claves API, contenido de alt text, nombres de archivo, URLs, prompts y respuestas completas de la API. La grabación de sesiones de PostHog está desactivada por defecto. La analítica debe describir lo que ocurrió sin copiar el contenido con el que el usuario estaba trabajando.
Si tuviéramos que empezar de nuevo, definiríamos el contrato de analítica antes de construir los paneles, documentando cada evento con su desencadenador exacto, si es propiedad del frontend o backend, si se dispara una vez por usuario, sesión, trabajo, ítem o transacción, las propiedades requeridas, la estrategia de desduplicación y la versión del esquema. Retocar la telemetría a posteriori es posible, pero mucho más trabajo que diseñarla bien desde el principio. También añadiríamos correlation IDs desde el día uno: son baratos de implementar y enormemente valiosos cuando la aplicación abarca múltiples servicios.
La lección más grande es que construir la funcionalidad de generación con IA fue solo una parte del producto. Un plugin listo para producción necesita también autenticación fiable, gestión de suscripciones y cuotas, webhooks idempotentes, analítica respetuosa con la privacidad, semántica de eventos clara, clasificación de errores, observabilidad de extremo a extremo y un plan de migración para telemetría antigua. La IA puede ser la característica estrella, pero la fiabilidad es lo que la convierte en un producto utilizable.
En Q2BSTUDIO sabemos que detrás de cualquier solución aparentemente simple hay una complejidad de integración, seguridad y análisis que marca la diferencia. Por eso ofrecemos servicios de inteligencia artificial a medida, así como consultoría en ciberseguridad, cloud AWS/Azure, BI con Power BI y agentes de IA. Cada proyecto nos enseña que la excelencia técnica no está solo en el algoritmo, sino en la orquestación de sistemas, la telemetría bien diseñada y la experiencia de usuario final. Este generador de alt text es un ejemplo de ello: lo más valioso no es la generación en sí, sino todo lo que la rodea para que funcione de forma robusta y fiable.
