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 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.
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).

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.

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.
• 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.