# DataFirefly Live Counters

> DataFirefly Live Counters muestra en tu sitio WordPress/WooCommerce contadores animados (clientes, pedidos, seguidores sociales, KPIs propios) que permanecen correctos incluso cuando todo el sitio es servido desde un full-page cache…

- Página: <https://www.datafirefly.com/es/documentation/dflivecounters-wp/>
- Idioma: es
- Actualizado el: 2026-06-28
- Otros idiomas: [fr](https://www.datafirefly.com/documentation/dflivecounters-wp/index.md), [en](https://www.datafirefly.com/en/documentation/dflivecounters-wp/index.md), [de](https://www.datafirefly.com/de/documentation/dflivecounters-wp/index.md), [it](https://www.datafirefly.com/it/documentation/dflivecounters-wp/index.md), [pl](https://www.datafirefly.com/pl/documentation/dflivecounters-wp/index.md), [nl](https://www.datafirefly.com/nl/documentation/dflivecounters-wp/index.md), [pt](https://www.datafirefly.com/pt/documentation/dflivecounters-wp/index.md)
- Índice: <https://www.datafirefly.com/es/documentation/llms.txt>

DataFirefly Live Counters muestra en tu sitio WordPress/WooCommerce contadores animados (clientes, pedidos, seguidores sociales, KPIs propios) que permanecen correctos incluso cuando todo el sitio es servido desde un full-page cache como LiteSpeed Cache o WP Rocket.

## Instalación e inicio rápido

### Requisitos previos

- WordPress 6.2 o superior (probado en 6.7).
- PHP 8.1 o superior.
- WooCommerce 7.0+ recomendado para los contadores de tienda. Sin WooCommerce, los contadores sociales y KPI personalizados siguen plenamente funcionales.
- Polylang o WPML opcional para las etiquetas multilingües.

### Instalación

1. Descarga el archivo `dflivecounters.zip` desde tu cuenta DataFirefly.
2. En WordPress, ve a **Plugins → Añadir nuevo → Subir plugin**.
3. Elige el zip y haz clic en **Instalar ahora**.
4. Activa el plugin. Aparece un nuevo elemento **Live Counters** en el menú de WooCommerce (o Ajustes si WooCommerce no está instalado).

### Primera visualización en 30 segundos

Coloca este shortcode en cualquier página o entrada:

```
[dflivecounters]
```

En la primera carga, aparece una cuadrícula de cuatro contadores con una animación count-up. Los números se calculan desde tu catálogo WooCommerce y se cachean.

## Ajustes generales

Ve a **WooCommerce → Live Counters**. La página tiene cuatro tarjetas, seguidas de una vista previa en directo y un botón de vaciado de caché.

### Tarjeta «Visualización y caché»

- **Estilo**: `Tarjetas`, `Minimalista`, `Degradado`.
- **Columnas**: entre 1 y 6. Responsive: 2 columnas en móvil, 1 en pantalla muy pequeña.
- **Color de acento**: para iconos, números (tarjetas) y fondo (degradado). Por defecto `#0f172a`.
- **Duración animación (ms)**: 200 a 8 000. 0 desactiva la animación.
- **Caché de contadores (min)**: 60 por defecto.
- **Caché de redes sociales (min)**: 360 por defecto (APIs sociales con rate-limit).
- **Abreviar números grandes**: muestra `12,4 k`.
- **Añadir «+» a los contadores acumulativos**.
- **Pre-calentar caché automáticamente (cron)**: Action Scheduler prioridad, WP-Cron fallback.

### Estados de pedido contabilizados

- **Estados contabilizados**: por defecto `Procesando` y `Completado`.
- **Estados «enviados»**: solo para _Productos enviados_. Por defecto `Completado`.

### Fecha de inicio de actividad

El contador _Años de experiencia_ se calcula a partir de la fecha en **«Fecha de fundación»**.

### Vaciar y regenerar el caché

El botón **«↻ Vaciar y regenerar el caché ahora»** elimina todos los transients y activa un warm-up inmediato. Cualquier modificación de los ajustes vacía automáticamente el caché.

## Contadores WooCommerce

### Lista de contadores disponibles

- **Clientes satisfechos** (`customers`).
- **Productos enviados** (`shipped`).
- **Pedidos procesados** (`orders`).
- **Artículos vendidos** (`items_sold`).
- **Productos en catálogo** (`products`).
- **Reseñas de clientes** (`reviews`).
- **Países de envío** (`countries`).
- **Años de experiencia** (`years`).

### Activar y personalizar un contador

- Etiqueta personalizada.
- Periodo (ver sección dedicada).
- Offset para integrar histórico previo.
- Objetivo que activa la barra de progreso.

### Compatibilidad HPOS

El plugin detecta automáticamente HPOS o el almacenamiento legacy. Las consultas están escritas en dos versiones optimizadas. La compatibilidad se declara vía el hook `before_woocommerce_init`.

## Contadores sociales y KPI personalizados

### Redes sociales soportadas

- **Facebook** e **Instagram** — recuperación automática vía API Meta Graph v19 (Instagram solo cuentas Business o Creator).
- **TikTok**, **X**, **LinkedIn**, **YouTube** — entrada manual.

### Configurar Facebook o Instagram vía API Meta Graph

1. Crea una app en [developers.facebook.com](https://developers.facebook.com).
2. Genera un token de larga duración con `pages_read_engagement` (FB) o `instagram_basic` + `pages_show_list` (IG).
3. Obtén el ID de la página o de la cuenta Business.
4. Marca **«Recuperar vía API»**, pega ID y token.

Si la llamada API falla, el plugin conserva el último valor conocido. El campo «manual» sirve como fallback.

### Contadores KPI personalizados

En la tarjeta **«Contadores personalizados (KPI)»**, clic en **«+ Añadir contador»**, luego: icono, etiqueta, valor, prefijo opcional, sufijo opcional, objetivo opcional.

## Periodos, objetivos y tendencia

### Ventanas temporales por contador

Contadores que soportan periodos: `customers`, `shipped`, `orders`, `items_sold`, `reviews`, `countries`.

- **Total**: comportamiento por defecto.
- **Este año**: desde el 1 de enero.
- **Este mes**: desde el día 1 del mes.
- **Últimos 30 días**: ventana móvil.

### Objetivos y barra de progreso

Indicar un objetivo en la columna **«Objetivo (0 = ninguno)»** activa automáticamente una barra animada hasta `min(100 %, valor / objetivo)`.

### Indicador de tendencia ▲/▼

Una insignia coloreada aparece junto al número: ▲ verde si el valor ha aumentado, ▼ rojo si ha disminuido, ninguna si la variación es nula o el histórico es insuficiente. Ventana móvil de 7 días por defecto, configurable vía el filtro `dflc_trend_window`. Baselines en una única opción `dflc_trend`.

**Paciencia esperada.** En un sitio nuevo, la insignia solo aparecerá tras el vencimiento de la ventana (7 días por defecto).

## Visualización: bloque, widget, shortcode

### Bloque Gutenberg

En el editor de bloques, busca **«DataFirefly Live Counters»** (categoría «Widgets»). El panel de inspección permite configurar columnas, estilo y lista de contadores. Vista previa idéntica al renderizado en el front.

### Widget clásico

En **Apariencia → Widgets**, añade **«DataFirefly Live Counters»**. Campos: título, columnas (0 a 6), estilo, claves (lista separada por comas).

### Shortcode

```
[dflivecounters]
[dflivecounters keys="customers,orders,reviews" columns="3"]
[dflivecounters keys="social_facebook,social_instagram" columns="2" style="gradient"]
[dflivecounters keys="custom_0,custom_1" style="minimal"]
```

Atributos: `keys` (string), `columns` (int 1-6), `style` (`cards`, `minimal`, `gradient`).

### Claves disponibles

| Contador | Clave |
| --- | --- |
| Clientes | `customers` |
| Productos enviados | `shipped` |
| Pedidos procesados | `orders` |
| Artículos vendidos | `items_sold` |
| Productos en catálogo | `products` |
| Reseñas de clientes | `reviews` |
| Países de envío | `countries` |
| Años de experiencia | `years` |
| Redes sociales | `social_facebook`, `social_instagram`, `social_tiktok`, `social_twitter`, `social_linkedin`, `social_youtube` |
| Contadores personalizados | `custom_0`, `custom_1`, etc. |

### Inserción en un tema (PHP)

```
echo do_shortcode( '[dflivecounters keys="customers,orders" columns="2"]' );
```

## Arquitectura del caché

### El problema

Cuando un caché de página (LiteSpeed, WP Rocket, NGINX micro-cache, Varnish, Cloudflare APO) sirve HTML pregenerado, cualquier número renderizado en PHP queda congelado. Desactivar el caché en estas páginas degrada gravemente el rendimiento.

### El principio: separar estructura y valores

- **Estructura cacheable**: cuadrícula, iconos, etiquetas y huecos vacíos, renderizados en el servidor.
- **Valores no cacheables**: recuperados por `fetch()` a una ruta REST dedicada con cabecera `Cache-Control` corta.

### Caché transient + warm-up

La ruta REST nunca hace una consulta SQL pesada durante la visita. Lee transients de WordPress, pre-calentados por Action Scheduler (job `dflc_warm_cache`) o WP-Cron como fallback.

### Stale-while-revalidate

1. Cache miss detectado.
2. Lectura del último valor conocido (en la opción persistente `dflc_lastgood`), devuelto inmediatamente.
3. Job de refresh asíncrono programado.
4. Lock corto (2 minutos) evita refrescos concurrentes.

### Seguridad del endpoint REST

- Lectura pública únicamente.
- Whitelist de claves.
- Cabecera `Cache-Control: public, max-age=...`.

**Atención.** Si tu CDN ignora la cabecera `Cache-Control` de la ruta REST, los números quedarán congelados a nivel CDN. Excluye `/wp-json/dflivecounters/v1/counters` de tu caché CDN.

## API desarrollador

Cinco filtros PHP extienden el plugin sin tocar el core.

### dflc_counter_definitions

```
add_filter( 'dflc_counter_definitions', static function ( array $items, array $settings ) {
    $items[] = array(
        'key'        => 'newsletter_subscribers',
        'label'      => 'Suscriptores newsletter',
        'icon'       => 'heart',
        'suffix'     => '+',
        'prefix'     => '',
        'abbreviate' => true,
        'goal'       => 5000,
    );
    return $items;
}, 10, 2 );
```

### dflc_compute

```
add_filter( 'dflc_compute', static function ( $pre, string $key, array $settings ) {
    if ( 'newsletter_subscribers' === $key ) {
        return (int) get_option( 'my_newsletter_count', 0 );
    }
    return $pre;
}, 10, 3 );
```

### dflc_counter_value

```
add_filter( 'dflc_counter_value', static function ( int $value, string $key ) {
    if ( 'customers' === $key && $value < 1000 ) {
        return 1000;
    }
    return $value;
}, 10, 2 );
```

### dflc_payload

```
add_filter( 'dflc_payload', static function ( array $payload, array $only, bool $force ) {
    foreach ( $payload as &$item ) {
        $item['emoji'] = '🎉';
    }
    return $payload;
}, 10, 3 );
```

### dflc_trend_window

```
add_filter( 'dflc_trend_window', static fn() => 30 * DAY_IN_SECONDS );
```

### Receta: contador Mailchimp

```
add_filter( 'dflc_counter_definitions', static function ( array $items ) {
    $items[] = array(
        'key' => 'mailchimp_subs', 'label' => 'Suscriptores newsletter',
        'icon' => 'heart', 'suffix' => '+', 'prefix' => '',
        'abbreviate' => true, 'goal' => 0,
    );
    return $items;
} );

add_filter( 'dflc_compute', static function ( $pre, string $key ) {
    if ( 'mailchimp_subs' !== $key ) {
        return $pre;
    }
    $response = wp_remote_get( 'https://us1.api.mailchimp.com/3.0/lists/LIST_ID', array(
        'headers' => array( 'Authorization' => 'Bearer ' . MAILCHIMP_API_KEY ),
    ) );
    if ( is_wp_error( $response ) ) {
        return 0;
    }
    $body = json_decode( wp_remote_retrieve_body( $response ), true );
    return (int) ( $body['stats']['member_count'] ?? 0 );
}, 10, 2 );
```

## Resolución de problemas

### Los números no se animan

- Verificar que `dflc-front.js` se carga.
- Verificar que `/wp-json/dflivecounters/v1/counters` responde 200 con JSON válido.
- Probar con otro tema.

### Los números muestran siempre «—»

- La llamada REST falló. Revisar consola JS.
- La ruta puede estar bloqueada por un plugin de seguridad.

### Los números no se actualizan

- Verificar que **«Pre-calentar caché automáticamente»** está activado.
- En sitios de bajo tráfico, considerar un cron real del sistema.
- Forzar refresco con el botón de vaciado.

### La llamada API Meta devuelve 0

- Verificar token en [Access Token Debugger](https://developers.facebook.com/tools/debug/accesstoken/).
- Verificar que la cuenta Instagram es Business o Creator.

### Aviso WP 6.7 «_load_textdomain_just_in_time»

Corregido desde la versión 1.1.1.