DataFirefly Live Counters: volledige gids

DataFirefly Live Counters toont op uw PrestaShop-winkel een widget met geanimeerde tellers, deels automatisch gevoed vanuit uw database (actieve klanten, verzonden bestellingen, producten, beleverde landen) en deels met waarden die u zelf invoert (reviews, tevredenheid, volgers op sociale netwerken, enzovoort). De widget plaatst zich native op meerdere hooks (homepage, footer, winkelwagen, kolommen) of waar dan ook in uw thema via de Smarty-tag widget name="dflivecounters". Deze documentatie behandelt de installatie, de configuratie van de 17 beschikbare tellers, de 5 visuele thema’s, de cachestrategie, het aansluiten van de Facebook- en Instagram-API’s, de live AJAX-refresh en het oplossen van de voornaamste problemen.

Installatie

1. Download het archief dflivecounters.zip vanuit uw DataFirefly-account.
2. PrestaShop-backoffice → Modules → Een module uploaden → verstuur de ZIP.
3. Bij de installatie registreert de module 7 weergavehooks en initialiseert hij een tiental configuratievariabelen. Er wordt geen enkele SQL-tabel aangemaakt: alle instellingen worden opgeslagen in ps_configuration.
4. De module laadt zijn standalone PSR-4-autoloader, er is geen composer install op de server nodig.

Uiterlijk van de widget

Open Modules → DataFirefly Live Counters → Configureren. De eerste sectie bundelt de globale uiterlijkinstellingen.

Visueel thema

Vijf kant-en-klare thema’s:

• Minimal: maximale soberheid, witte achtergrond, ideaal voor strakke thema’s.
• Glassmorphism: matglas met backdrop-blur, achtergrond licht getint met de primaire kleur. Erg trendy.
• Gradient: achtergrond met verloop over de volle breedte, van de primaire kleur naar een donkere tint. Sterke visuele impact, witte tekst.
• Card: verhoogde witte kaarten met zachte schaduw en hover. Klassiek premium.
• Flat: achtergrond licht getint met de primaire kleur, waarden in de primaire kleur.

Titel en ondertitel

Getoond boven het tellerraster. Laat ze leeg om de kop te verbergen (nuttig in de footer, waar de omgeving de context al geeft).

Kleuren

Drie hoofdkleuren sturen de hele widget aan via CSS-variabelen (--dflc-primary, --dflc-text, --dflc-bg):

• Primaire kleur: standaardiconen, accent van het Flat-thema, verloop van het Gradient-thema.
• Tekstkleur: titel, ondertitel, waarden en labels.
• Achtergrondkleur: achtergrond van de sectie (genegeerd op de thema’s Glassmorphism en Gradient, die hun eigen achtergrond toepassen).

Kolommen

Twee onafhankelijke instellingen:

• Kolommen desktop: 1 tot 6 (standaard 4).
• Kolommen mobiel: 1 tot 3 (standaard 2). Het breakpoint is 768 px.

Duur van de CountUp-animatie

Duur in milliseconden waarin de cijfers van 0 naar hun doelwaarde lopen (standaard 2.000 ms). Er wordt een cubische ease-out-curve toegepast voor een zachte vertraging. Zet 0 om de animatie uit te schakelen en de eindwaarde meteen te tonen.

Live AJAX-refresh (optioneel)

Eenmaal ingeschakeld bevraagt de widget periodiek een JSON-endpoint om de waarden bij te werken zonder de pagina te herladen. Twee parameters:

• Live refresh: AAN/UIT.
• Interval: in seconden, minimaal 30 (standaard 60). Voert u minder in, dan wordt 30 afgedwongen.

Het endpoint antwoordt met een Cache-Control: public, max-age=30, waardoor uw CDN het verkeer kan opvangen. De overgangsanimatie van de ene waarde naar de andere start vanaf de eerder getoonde waarde, niet vanaf nul, wat visueel natuurlijker oogt.

“Date from”

Referentiedatum die door twee tellers wordt gebruikt:

• Verzonden bestellingen: telt alleen de bestellingen die na deze datum zijn aangemaakt (filter WHERE date_add >= ?).
• Jaren ervaring: berekent automatisch het aantal verstreken jaren van deze datum tot vandaag.

Catalogus van de tellers

Er zijn 17 tellers beschikbaar, verdeeld in drie groepen naargelang hun berekeningswijze.

Automatische tellers (5)

Deze tellers lezen in realtime de gegevens van uw PrestaShop. Geen invoer nodig.

• Klanten: actieve klanten (active = 1 AND deleted = 0), gescoped op de shopcontext. TTL 15 min.
• Verzonden bestellingen: bestellingen waarvan minstens één statusgeschiedenis tot de geselecteerde statussen behoort (veld “Order states counted as shipped”). Is geen enkele status geselecteerd, dan gebruikt de module automatisch de vlag shipped = 1 van de tabel ps_order_state. TTL 15 min.
• Verwerkte bestellingen: alle bestellingen waarvan de huidige status de vlag logable = 1 heeft (de canonieke PrestaShop-vlag voor bestellingen die in de statistieken meetellen). Sluit dus annuleringen en terugbetalingen uit. TTL 15 min.
• Producten: actieve en zichtbare producten van de catalogus, gescoped op de shopcontext. TTL 30 min.
• Beleverde landen: aantal verschillende landen die minstens één bestelling hebben ontvangen (COUNT(DISTINCT id_country) op de tabel ps_address gejoind met ps_orders). TTL 1 u.

Hybride tellers (4)

Deze tellers proberen eerst een automatische berekening en vallen daarna terug op de handmatige waarde die u als back-up hebt ingevoerd.

• Jaren ervaring: berekend vanaf de datum “Date from”; handmatige waarde als u liever een afgerond cijfer vastzet (bv. “12” in plaats van “11”). TTL 24 u.
• Gepubliceerde artikelen: automatische detectie van de tabellen van de belangrijkste PrestaShop-blogmodules (smart_blog_post, prestablog_news, psblog_post, ph_simpleblog_post) via INFORMATION_SCHEMA. Geen match, gebruik dan de handmatige waarde. TTL 24 u.
• Facebook-volgers: aanroep van de Facebook Graph API met een langlevend Page Access Token. Handmatige fallback als dit niet is geconfigureerd of de API faalt. TTL 1 u.
• Instagram-volgers: aanroep van de Instagram Graph API (Business- of Creator-account vereist). Handmatige fallback. TTL 1 u.

Handmatige tellers (8)

Deze tellers tonen simpelweg de waarde die u invoert. Ideaal voor metrieken die PrestaShop niet kan berekenen of die u volledig in de hand wilt houden.

• Klantreviews: aantal reviews (uit Trustpilot, Google, enzovoort).
• Tevredenheid: tevredenheidspercentage. Tip: gebruik het achtervoegsel “%” en een waarde 0-100.
• Bespaarde CO₂: kg vermeden uitstoot. Tip: achtervoegsel “kg”.
• Onderscheidingen: prijzen, certificeringen, erkenningen.
• Supporturen: achtervoegsel “u”.
• TikTok-volgers: de TikTok Display API vereist een OAuth per gebruiker, onwerkbaar voor een publieke widget. Handmatige invoer.
• X-volgers (Twitter): de X API v2 is betalend. Handmatige invoer.
• LinkedIn-volgers: LinkedIn Organization Followers vereist een goedkeuring via het Marketing Developer Platform. Handmatige invoer.

Configuratie per teller

Elke tellerregel in de admin biedt dezelfde instellingen:

• Ingeschakeld (AAN/UIT): alleen de ingeschakelde tellers verschijnen in de widget. De weergavevolgorde volgt die van de admin.
• Aangepast label: vervangt het standaardlabel. Leeg laten om het native label te gebruiken, vertaald in de taal van de bezoeker.
• Waarde (handmatig): voor de handmatige tellers en de fallback van de hybride tellers.
• Offset: geheel getal dat bij de berekende waarde wordt opgeteld. Handig om van een flatterend cijfer te vertrekken zonder uw database aan te raken. Voor de tellers “Klanten” en “Verzonden bestellingen” kunt u bijvoorbeeld respectievelijk +500 en +2.000 toevoegen als uw winkel net is gemigreerd. Het label “Current live” naast het Offset-veld toont de ruwe, door PrestaShop berekende waarde, zonder offset.
• Voorvoegsel / achtervoegsel: respectievelijk 4 en 6 tekens. Voor- en achtervoegsel blijven vast, ook tijdens de animatie.
• Decimalen: 0 tot 3. De opmaak gebruikt Intl.NumberFormat met de locale van de bezoeker (gelokaliseerde duizendtalscheiders en decimaalteken).
• Icoonkleur: vervangt de primaire kleur, alleen voor dit icoon.

Bestelstatussen “verzonden”

De teller “Verzonden bestellingen” steunt standaard op de statusgeschiedenis. Met de instelling Order states counted as shipped kiest u precies welke statussen meetellen. Op een standaard PrestaShop-installatie zijn dat de vooraf ingestelde statussen ID 4 (Verzonden) en 5 (Geleverd).

Is geen enkele status geselecteerd, dan schakelt de module over op een fallback die de vlag shipped = 1 van de tabel ps_order_state bevraagt. Deze aanpak is ruimer en dekt de meeste gangbare configuraties.

Facebook configureren

1. Ga naar developers.facebook.com en maak een app van het type “Business” aan.
2. Selecteer in de sectie Graph API Explorer uw app en daarna uw Facebook-pagina.
3. Genereer een Page Access Token met de scopes pages_read_engagement en pages_show_list.
4. Wissel dit korte token (1 u) in voor een langlevend token (60 dagen) via het endpoint /oauth/access_token?grant_type=fb_exchange_token.
5. Haal uw Page ID op in de instellingen van uw pagina (sectie “Paginatransparantie” of rechtstreeks in de Graph API Explorer).
6. Vul beide velden in de Live Counters-configuratie in en sla op. De Facebook-teller wordt bij het opslaan bijgewerkt.

Instagram configureren

1. Uw Instagram-account moet in de modus Business of Creator staan. Persoonlijke accounts worden niet ondersteund door de Graph API.
2. Koppel uw Instagram-account aan een Facebook-pagina (pagina-instellingen → Instagram).
3. Bevraag in de Graph API Explorer /me/accounts met uw Page Access Token om het bijbehorende Instagram User ID op te halen (veld instagram_business_account).
4. Gebruik hetzelfde langlevende Facebook-token voor de Instagram-API.
5. Vul het IG User ID en het token in de Live Counters-configuratie in.

Cachestrategie

De cache werkt op twee niveaus om ook onder verkeer een constante TTFB te garanderen.

Cache per teller

Elke teller heeft zijn eigen TTL:

• 15 minuten: Klanten, Verzonden bestellingen, Verwerkte bestellingen.
• 30 minuten: Producten.
• 1 uur: Beleverde landen, Facebook, Instagram.
• 24 uur: Jaren ervaring, Gepubliceerde artikelen en alle handmatige tellers.

De cache gebruikt eerst de native PrestaShop-Cache-laag (memcached, APCu of Redis indien op uw server geconfigureerd), en daarna een filesystem-fallback in var/cache/dflivecounters/. Dat garandeert dat de TTL’s worden gerespecteerd, ook als de native laag in “no-cache”-modus staat.

Cache van de gerenderde widget

De volledige HTML van de widget wordt zelf 60 seconden gecachet, per taal en per hook (dflc_widget_LANG_HASH). Deze tweede laag vangt het grootste deel van het verkeer op, ook wanneer de interne tellers al actueel zijn.

Automatische opschoning

• Het opslaan van de configuratie schoont automatisch alle caches van de module op.
• Een knop Cache legen in het beheerpaneel dient voor handmatige invalidatie.
• De de-installatie van de module leegt de cache automatisch.

De widget in uw thema plaatsen

De module registreert bij de installatie 7 hooks:

• displayHome: homepage
• displayFooter: paginavoet
• displayFooterBefore: net vóór de footer (PS 8+)
• displayLeftColumn / displayRightColumn: zijkolommen
• displayShoppingCartFooter: winkelwagenpagina, onder de samenvatting
• actionFrontControllerSetMedia: registreert de CSS/JS-assets

U kunt hooks toevoegen of verwijderen via Design → Posities in de backoffice.

Vrije plaatsing via Smarty

Om de widget op een precieze plek in uw thema te zetten (bv. op de productpagina, onder de titel van een categorie), gebruikt u de Smarty-widgettag:

{widget name="dflivecounters"}

De widget implementeert de native PrestaShop-interface WidgetInterface, waardoor hij vanuit elk .tpl-template van uw thema aanroepbaar is.

Het widgettemplate aanpassen

Het hoofdtemplate (Smarty) is views/templates/hook/widget.tpl. Om het te overriden zonder de module te wijzigen (en zo de updates te behouden), kopieert u het naar uw thema, in de map themes/uw-thema/modules/dflivecounters/views/templates/hook/widget.tpl.

Beschikbare Smarty-variabelen:

• {$dflc.counters}: array van elke teller met de sleutels key, label, value, icon, prefix, suffix, decimals, icon_color
• {$dflc.theme}: slug van het thema (minimal, glassmorphism, gradient, card, flat)
• {$dflc.title}, {$dflc.subtitle}
• {$dflc.primary_color}, {$dflc.text_color}, {$dflc.bg_color}
• {$dflc.cols_desktop}, {$dflc.cols_mobile}
• {$dflc.hook}: naam van de oorspronkelijke hook (nuttig om de weergave aan de plaatsing aan te passen)

AJAX-endpoint

De front-controller refresh stelt een JSON-URL beschikbaar, bruikbaar voor de live refresh of elke integratie van derden:

index.php?fc=module&module=dflivecounters&controller=refresh

Het JSON-antwoord bevat een boolean success, een Unix-timestamp en een object counters, waarin elke sleutel de identifier van de teller is (customers, shipped_orders, facebook, instagram, enzovoort) en elke waarde het huidige aantal. De inhoud weerspiegelt de op het moment van de aanroep ingeschakelde tellers, met toegepaste offsets. Het antwoord wordt geserveerd met Cache-Control: public, max-age=30.

Toegankelijkheid

De widget is ontworpen volgens de aanbevelingen van WCAG 2.2 AA:

• Semantische structuur: section, header, ul role="list", li.
• Alle SVG-iconen hebben aria-hidden="true" (decoratief).
• Strikte naleving van prefers-reduced-motion: reduce: animatie uitgeschakeld, eindwaarde meteen getoond.
• Contrasten: de standaardkleuren respecteren een ratio boven 4.5:1 op de thema’s Minimal en Card. Controleer uw eigen kleuren met een tool zoals axe DevTools.
• Getalopmaak: font-variant-numeric: tabular-nums voor een constante cijferbreedte (vermijdt de visuele “sprong” tijdens de animatie).

AVG

De widget is zo ontworpen dat er geen enkele toestemmingsvermelding nodig is:

• Geen enkel cookie geplaatst aan bezoekerszijde.
• Geen enkel script van derden geladen (geen Facebook Pixel, geen Google Tag Manager).
• De Facebook- en Instagram-API-aanroepen gebeuren aan serverzijde in PHP, nooit vanuit de browser. Er wordt geen enkel bezoekersgegeven aan Meta doorgegeven.
• Geen enkel persoonsgegeven verzameld of opgeslagen door de module.

Compatibiliteit en technische opmerkingen

• PrestaShop 8.0 tot 9.x, PHP 8.1+.
• Native multistore: alle SQL-query’s zijn gescoped op Shop::getContextListShopID().
• Meertalig: Polylang Pro of het native meertalige PrestaShop-systeem.
• Geen enkele SQL-tabel aangemaakt: configuratie opgeslagen in ps_configuration.
• Standalone PSR-4-autoloader (geen composer install op de server).
• Native PrestaShop WidgetInterface: bruikbaar via {widget name="dflivecounters"}.
• Gewicht van de assets: 3 KB JS, 2 KB CSS. Standaard geen enkele externe request.
• Conform de PrestaShop 9 AJAX-conventies: $this->module->l() in plaats van $this->l(), eigen front-controller voor de refresh, nooit een override van ajaxRender.

FAQ en probleemoplossing

De widget verschijnt niet op de homepage. Controleer of de module aan de hook displayHome hangt in Design → Posities. Controleer ook of minstens één teller is ingeschakeld: zonder ingeschakelde teller geeft de widget niets terug (stilzwijgend).

De Facebook-teller blijft op nul. Meerdere mogelijke oorzaken: onjuist Page ID, verlopen token (levensduur 60 dagen), ontbrekende scope (pages_read_engagement is vereist). Leeg de cache van de module en herlaad de configuratie: de door de Graph API teruggegeven waarde verschijnt naast het label “Current live”.

De teller Verzonden bestellingen is te laag. Controleer de selectie “Order states counted as shipped”: alleen de geselecteerde statussen worden geteld. Wilt u aangepaste statussen opnemen (bv. “Click & Collect afgehaald”), voeg ze dan aan de selectie toe.

De cijfers lijken bevroren en weerspiegelen mijn echte verkeer niet. Dat is de cache die zijn werk doet. De standaard-TTL loopt van 15 minuten (klanten, bestellingen) tot 24 uur (statische tellers). Gebruik de knop Cache legen voor handmatige invalidatie. Voor automatische verversing schakelt u de modus Live refresh in.

De CountUp-animatie start niet. De widget gebruikt IntersectionObserver en start op het moment dat hij het viewport binnenkomt. Is de widget al zichtbaar bij het laden van de pagina (bv. helemaal bovenaan geplaatst), dan start de animatie onmiddellijk. Blijft ze op nul bevroren: controleer de JavaScript-console van uw browser, een andere module kan de JS-bundel breken.

De widget verpest mijn Lighthouse / Core Web Vitals. Met een plaatsing onderaan de pagina (footer) en de 60 s-cache op de gerenderde HTML is de CLS/LCP-impact verwaarloosbaar. Ziet u toch een probleem, controleer dan of u de Live refresh niet met een te kort interval hebt ingeschakeld (de AJAX vuurt terwijl Lighthouse meet). Schakel voor een schone audit de live refresh uit.

Zijn de tellers in multistore per winkel gescoped? Ja. Alle SQL-query’s gebruiken Shop::getContextListShopID(). In de modus “alle winkels” cumuleren de tellers; in de modus “één winkel” tellen ze alleen die winkel. De labels en de handmatige waarde zijn eveneens per winkel en per taal.

Hoe voeg ik een eigen aangepaste teller toe? Maak een klasse die Df/LiveCounters/Counter/AbstractCounter uitbreidt (of ManualCounter voor een 100% handmatige teller), implementeer getKey(), getDefaultLabel() en getValue(), en voeg de instantie toe aan de instantiearray van de CounterRegistry. Om uw code bij de volgende update niet te verliezen, maakt u een klein companion-moduletje dat uw teller via een custom hook in het register injecteert; neem gerust contact met ons op voor een voorbeeld.