# DataFirefly Live Counters

> O DataFirefly Live Counters apresenta no seu site WordPress/WooCommerce contadores animados (clientes, encomendas, seguidores nas redes sociais, KPI próprios) que se mantêm corretos mesmo quando todo o site é servido…

- Página: <https://www.datafirefly.com/pt/documentation/dflivecounters-wp/>
- Idioma: pt
- Atualizado em: 2026-09-02
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/dflivecounters-wp/index.md), [en](https://www.datafirefly.com/en/documentation/dflivecounters-wp/index.md), [es](https://www.datafirefly.com/es/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)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

O DataFirefly Live Counters apresenta no seu site WordPress/WooCommerce contadores animados (clientes, encomendas, seguidores nas redes sociais, KPI próprios) que se mantêm corretos mesmo quando todo o site é servido a partir de uma cache de página completa, como o LiteSpeed Cache ou o WP Rocket.

## Instalação e arranque

### Requisitos

- WordPress 6.2 ou superior (testado na 6.7).
- PHP 8.1 ou superior.
- WooCommerce 7.0+ recomendado para os contadores de loja. Sem WooCommerce, os contadores sociais e os KPI personalizados mantêm-se totalmente funcionais.
- Polylang ou WPML facultativos para as designações multilingues.

### Instalação

1. Descarregue o ficheiro `dflivecounters.zip` a partir da sua conta DataFirefly.
2. No WordPress, vá a **Plugins → Adicionar plugin → Carregar plugin**.
3. Escolha o zip e clique em **Instalar agora**.
4. Ative a extensão. Aparece um novo elemento **Live Counters** no menu WooCommerce (ou em Definições, se o WooCommerce não estiver instalado).

### Primeira apresentação em 30 segundos

Coloque este shortcode em qualquer página ou artigo:

```
[dflivecounters]
```

No primeiro carregamento, aparece uma grelha de quatro contadores com uma animação de contagem crescente. Os números são calculados a partir do seu catálogo WooCommerce e colocados em cache.

## Definições gerais

Vá a **WooCommerce → Live Counters**. A página está organizada em quatro cartões, seguidos de uma pré-visualização em direto e de um botão de limpeza da cache.

### Cartão «Apresentação e cache»

- **Estilo**: `Cartões`, `Minimalista`, `Gradiente`.
- **Colunas**: entre 1 e 6. Responsivo: 2 colunas em telemóvel, 1 em ecrãs muito pequenos.
- **Cor de destaque**: usada nos ícones, nos números (cartões) e no fundo (gradiente). Predefinição `#0f172a`.
- **Duração da animação (ms)**: 200 a 8000. 0 desativa a animação.
- **Cache dos contadores (min)**: 60 por predefinição.
- **Cache das redes sociais (min)**: 360 por predefinição (as API sociais têm limites de débito).
- **Abreviar os números grandes**: apresenta `12,4 mil` em vez de `12 400`.
- **Acrescentar «+» aos contadores acumulativos**.
- **Pré-aquecer a cache automaticamente (cron)**: Action Scheduler em prioridade, WP-Cron como recurso.

### Estados de encomenda contados

- **Estados contados (clientes, encomendas, artigos, países)**: por predefinição `Processing` e `Completed`.
- **Estados «expedidos»**: usado apenas em _Produtos expedidos_. Por predefinição `Completed`.

### Data de criação

O contador _Anos de experiência_ calcula o seu valor a partir da data indicada em **«Data de criação»**.

### Limpar e regerar a cache

O botão **«↻ Limpar e regerar a cache agora»** elimina todos os transientes do plugin e desencadeia um aquecimento imediato. Qualquer alteração das definições limpa automaticamente a cache e reagenda o aquecimento.

## Contadores WooCommerce

### Lista dos contadores disponíveis

- **Clientes satisfeitos** (`customers`): endereços de e-mail distintos que fizeram uma encomenda num estado contado.
- **Produtos expedidos** (`shipped`): soma das quantidades de artigos nas encomendas «expedidas».
- **Encomendas tratadas** (`orders`).
- **Artigos vendidos** (`items_sold`): soma das quantidades em todas as linhas.
- **Produtos no catálogo** (`products`).
- **Avaliações de clientes** (`reviews`): avaliações aprovadas.
- **Países servidos** (`countries`).
- **Anos de experiência** (`years`): a partir da data de criação.

### Ativar e personalizar um contador

Na tabela **«Contadores de loja»**, assinale _Ativo_ e, opcionalmente:

- Indique uma **designação personalizada**.
- Escolha um **período** (ver a secção dedicada).
- Acrescente um **desvio** para integrar um histórico anterior (por exemplo, 1200 clientes herdados de uma loja anterior).
- Defina um **objetivo**, que ativa a barra de progresso.

### Compatibilidade HPOS

O plugin deteta automaticamente o HPOS (High-Performance Order Storage) ou o armazenamento antigo (CPT). As consultas estão escritas em duas versões otimizadas. A compatibilidade com o HPOS e com os Cart/Checkout Blocks é declarada através do hook `before_woocommerce_init`.

## Contadores sociais e KPI personalizados

### Redes sociais suportadas

- **Facebook** e **Instagram**: obtenção automática através da API Meta Graph v19 (Instagram apenas em conta Business ou Creator).
- **TikTok**, **X (Twitter)**, **LinkedIn**, **YouTube**: introdução manual.

O TikTok, o X e o LinkedIn não expõem um contador de seguidores através de uma API pública fiável, daí a introdução manual.

### Configurar o Facebook ou o Instagram através da API Meta Graph

1. Crie uma aplicação em [developers.facebook.com](https://developers.facebook.com).
2. Gere um token de acesso de longa duração com a permissão `pages_read_engagement` (Facebook) ou `instagram_basic` mais `pages_show_list` (Instagram).
3. Obtenha o ID da Página do Facebook ou da conta IG Business.
4. No cartão «Redes sociais», assinale **«Obter através da API»**, cole o ID em _ID do objeto_ e o token em _Token de acesso_.

Se a chamada à API falhar (token expirado, limite de débito), o plugin conserva o último valor conhecido. O campo «manual» serve de recurso final.

### Contadores KPI personalizados

No cartão **«Contadores personalizados (KPI)»**, clique em **«+ Acrescentar um contador»** e indique: ícone (users, award, heart, leaf, download…), designação, valor, prefixo opcional («$», «+»), sufixo opcional («%», «h», «M») e objetivo opcional.

## Períodos, objetivos e tendência

### Períodos por contador

Os contadores que agregam ao longo do tempo (`customers`, `shipped`, `orders`, `items_sold`, `reviews`, `countries`) podem ser restringidos:

- **Total**: comportamento predefinido.
- **Este ano**: desde 1 de janeiro.
- **Este mês**: desde o dia 1 do mês.
- **Últimos 30 dias**: janela deslizante.

O efeito «124 encomendas este mês» é muitas vezes mais envolvente do que «9421 encomendas».

### Objetivos e barra de progresso

Indicar um objetivo na coluna **«Objetivo (0 = nenhum)»** ativa automaticamente uma barra por baixo do contador, animada ao mesmo tempo que a contagem crescente, até `min(100%, valor / objetivo)`. Disponível também nos contadores sociais e personalizados.

### Indicador de tendência ▲/▼

Aparece uma pastilha colorida ao lado do número:

- ▲ verde se o valor aumentou desde o instantâneo anterior.
- ▼ vermelho se desceu.
- Sem pastilha se a variação for nula ou se o histórico for insuficiente.

A percentagem é calculada numa janela deslizante de 7 dias por predefinição, alterável através do filtro `dflc_trend_window`. As linhas de base são guardadas numa única opção do WordPress (`dflc_trend`).

**É preciso paciência.** Num site novo, a pastilha de tendência só aparece depois de decorrida a janela (7 dias por predefinição).

## Apresentação: bloco, widget, shortcode

### Bloco Gutenberg

No editor de blocos, procure **«DataFirefly Live Counters»** (categoria «Widgets»). O painel de inspeção permite configurar colunas, estilo e lista dos contadores a apresentar. A pré-visualização usa o `ServerSideRender`, idêntico à apresentação no front-end.

### Widget clássico

Em **Aparência → Widgets**, acrescente **«DataFirefly Live Counters»**. Campos: título, colunas (0 a 6), estilo, chaves (lista separada por vírgulas, ou vazio = todos os contadores ativos).

### 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 suportados: `keys` (string, lista de chaves), `columns` (inteiro de 1 a 6), `style` (`cards`, `minimal`, `gradient`).

### Lista das chaves disponíveis

| Contador | Chave |
| --- | --- |
| Clientes | `customers` |
| Produtos expedidos | `shipped` |
| Encomendas tratadas | `orders` |
| Artigos vendidos | `items_sold` |
| Produtos no catálogo | `products` |
| Avaliações de clientes | `reviews` |
| Países servidos | `countries` |
| Anos de experiência | `years` |
| Redes sociais | `social_facebook`, `social_instagram`, `social_tiktok`, `social_twitter`, `social_linkedin`, `social_youtube` |
| Contadores personalizados | `custom_0`, `custom_1`, etc. |

### Inserção num tema (PHP)

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

## Arquitetura da cache

### O problema

Quando uma cache de página (LiteSpeed, WP Rocket, microcache do NGINX, Varnish, Cloudflare APO) serve um HTML pré-gerado, qualquer número gerado em PHP fica fixo. A resposta clássica, desativar a cache nessas páginas, degrada gravemente o desempenho.

### O princípio: separar estrutura e valores

- **Estrutura colocável em cache**: grelha, ícones, designações e espaços vazios, gerados no servidor e perfeitamente colocáveis em cache.
- **Valores não colocáveis em cache**: obtidos por `fetch()` a uma rota REST dedicada, com um cabeçalho `Cache-Control` curto.

O visitante recebe instantaneamente o HTML em cache, e depois os números preenchem-se em JavaScript com uma animação de contagem crescente.

### Cache em transientes e aquecimento

A rota REST nunca faz uma consulta SQL pesada durante a visita. Lê transientes do WordPress, pré-aquecidos pelo Action Scheduler (tarefa `dflc_warm_cache`) ou pelo WP-Cron como recurso.

### Stale-while-revalidate

Se um transiente expirar exatamente entre dois aquecimentos:

1. O **último valor conhecido** é lido a partir da opção persistente `dflc_lastgood` (que sobrevive à expiração do transiente) e devolvido de imediato.
2. É agendada uma tarefa de atualização assíncrona.
3. Um bloqueio curto (2 minutos) impede a acumulação de várias atualizações em simultâneo.

O verdadeiro arranque a frio só acontece na primeiríssima apresentação depois da instalação.

### Segurança do endpoint REST

- Apenas leitura pública.
- Lista de permissões de chaves: só são aceites as chaves que correspondem a contadores realmente configurados.
- Cabeçalho `Cache-Control: public, max-age=...` dimensionado pelo TTL dos contadores.

**Atenção.** Se o seu CDN ignorar o `Cache-Control` da rota REST e a colocar em cache de forma agressiva, os números ficam fixos ao nível do CDN. Exclua `/wp-json/dflivecounters/v1/counters` da cache do seu CDN se observar este comportamento.

## API para programadores

Cinco filtros PHP permitem estender o plugin sem tocar no núcleo.

### dflc_counter_definitions

Acrescentar, reordenar ou ocultar contadores.

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

### dflc_compute

Contorna o cálculo. Devolver um inteiro assume o controlo, `null` deixa o núcleo tratar.

```
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

Filtra o valor final logo antes do envio para o front-end.

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

### dflc_payload

Filtra a totalidade do payload REST.

```
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

Altera a janela deslizante de tendência. Valor em segundos, predefinição `7 * DAY_IN_SECONDS`.

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

### Receita: contador Mailchimp

```
add_filter( 'dflc_counter_definitions', static function ( array $items ) {
    $items[] = array(
        'key' => 'mailchimp_subs', 'label' => 'Subscritores da 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 );
```

## Resolução de problemas

### Os números não se animam

- Verificar que o script `dflc-front.js` é carregado (separador de rede).
- Verificar que a rota REST `/wp-json/dflivecounters/v1/counters` responde com 200 e um JSON válido.
- Testar com outro tema.

### Os números mostram sempre «—»

- A chamada REST falhou. Verificar a consola de JS.
- A rota REST pode estar bloqueada por uma extensão de segurança.

### Os números não se atualizam

- Verificar que **«Pré-aquecer a cache automaticamente»** está ativo.
- Nos sites de baixo tráfego, ponderar um verdadeiro cron de sistema em vez do WP-Cron.
- Forçar uma atualização através do botão **«↻ Limpar e regerar a cache agora»**.

### A chamada à API Meta devolve 0

- Verificar a validade do token no [Access Token Debugger](https://developers.facebook.com/tools/debug/accesstoken/).
- Verificar que a conta Instagram é mesmo Business ou Creator.

### Aviso do WP 6.7 «_load_textdomain_just_in_time»

Corrigido desde a versão 1.1.1.