dffreegift: cadeau bij een winkelwagendrempel, volledige gids

Volledige gids van de module dffreegift voor PrestaShop 8 en 9: installatie, configuratie, interne werking (native CartRule), aanpassing, probleemoplossing en verwijderen. Bij elke stap horen de exacte parameters die u in productie gebruikt.

Overzicht

dffreegift legt automatisch een cadeauproduct in de winkelwagen zodra een ingestelde drempel is bereikt, en haalt het er weer uit als de winkelwagen onder die drempel zakt. De werking berust volledig op het native CartRule-systeem van PrestaShop (veld gift_product): de module raakt nooit rechtstreeks aan de productprijzen, maakt geen tijdelijke SpecificPrice aan en injecteert niets in de hooks voor prijsberekening. Het resultaat is volledige verenigbaarheid met uw andere promoties, kortingscodes, belastingen en meerdere valuta.

De module toont ook een voortgangsblok op de winkelwagenpagina met het bericht « Voeg nog X € toe en ontvang uw cadeau », een gekleurde balk die vult naarmate de drempel nadert, en een animatie bij het bereiken ervan.

Vereisten

• PrestaShop 8.0 tot 9.x (getest op 8.0, 8.1, 8.2 en 9.0)
• PHP 8.1 minimaal (8.2 en 8.3 ondersteund)
• Een actief product in uw catalogus dat als cadeau dient (een eenvoudig product of een product met varianten)
• Beheerderstoegang tot de PrestaShop-backoffice

Installatie

1. Ga in de backoffice naar Modules → Modulebeheer → Een module uploaden.
2. Upload het bestand dffreegift-1.0.0.zip.
3. Klik op Installeren en daarna op Configureren.

Bij de installatie voert de module op de achtergrond het volgende uit:

• Registratie van 5 hooks: actionCartSave, actionObjectCartRuleDeleteBefore, displayShoppingCart, displayCartExtraProductActions en displayHeader.
• Wegschrijven van de standaard configuratiewaarden (drempel 50 €, berekening inclusief btw, zonder verzendkosten, voorraadcontrole ingeschakeld).
• Aanmaken van een « schaduw »-CartRule met een unieke code van het type DFFREEGIFT_A7B3F2D9, zichtbaar in Catalogus → Kortingen → Winkelwagenregels.

Configuratie

Het configuratiescherm vindt u in Modules → DataFirefly Free Gift → Configureren. Alle parameters staan in één formulier.

De module inschakelen

De schakelaar De module inschakelen werkt als hoofdschakelaar. In de stand Nee blijft de module geïnstalleerd maar doet hij niets: geen automatische toevoeging, geen blok aan de frontzijde, geen drempelberekening. Handig om de actie tijdelijk stop te zetten (bijvoorbeeld aan het einde van een seizoensactie) zonder de configuratie kwijt te raken.

Cadeauproduct en variant

Twee velden, in te vullen in deze volgorde:

1. ID van het cadeauproduct: voer de PrestaShop-ID in van het product dat u weggeeft. Die ID vindt u in Catalogus → Producten (kolom ID). Na een eerste keer opslaan verschijnt de naam van het product als hulp onder het veld, ter bevestiging.
2. Variant: keuzelijst met de beschikbare combinaties van het product. Die wordt automatisch gevuld nadat u de product-ID hebt opgeslagen. Kies een bepaalde variant (bijvoorbeeld « Maat M, kleur zwart ») of laat — Zonder variant — staan voor een eenvoudig product.

Drempel

Het veld Drempel bepaalt vanaf welk winkelwagenbedrag het cadeau wordt toegevoegd. Twee bijbehorende parameters bepalen de rekenbasis:

• Berekening inclusief btw: staat dit aan, dan bevat het totaal alle belastingen op de winkelwagen. Staat het uit, dan wordt de drempel met het totaal exclusief btw vergeleken. De meeste B2C-winkels werken inclusief btw; B2B-winkels rekenen vaak exclusief btw.
• Verzendkosten meetellen: staat dit aan, dan worden de geschatte verzendkosten vóór de vergelijking bij het totaal geteld. In de praktijk zet men dit zelden aan, omdat de verzendkosten niet altijd al berekend zijn wanneer de klant zijn winkelwagen bekijkt (geen vervoerder gekozen betekent 0 €).

Concreet komt het beoordeelde totaal overeen met een native aanroep van PrestaShop:

Cart::getOrderTotal(
    $with_taxes = (bool) CFG_TAX_INCL,
    $type = CFG_INCLUDE_SHIPPING ? Cart::BOTH : Cart::ONLY_PRODUCTS
);

Zo is de waarde die voor de vergelijking wordt gebruikt exact dezelfde als die in het winkelwagenoverzicht van PrestaShop.

Voorraadcontrole

De schakelaar De voorraad van het cadeau controleren (standaard aan) schort de automatische toevoeging op als het cadeauproduct niet beschikbaar is. De controle volgt de out of stock-strategie die globaal in PrestaShop is ingesteld:

• Staat het product op « bestellen bij uitverkocht toegestaan », dan blijft de automatische toevoeging werken, ook bij hoeveelheid 0.
• Weigert het product bestellingen bij uitverkocht, dan wordt de automatische toevoeging opgeschort zodra de hoeveelheid 0 bereikt.

Beperking per klantgroep

Het raster In aanmerking komende klantgroepen toont alle groepen van de winkel met per groep een selectievakje. Er zijn twee gedragingen:

• Geen enkel vakje aangevinkt: alle klanten komen in aanmerking, ook niet-geïdentificeerde bezoekers (op voorwaarde dat de standaardgroep PS_UNIDENTIFIED_GROUP niet is uitgesloten, wat het standaardgedrag is).
• Een of meer vakjes aangevinkt: alleen klanten uit minstens één aangevinkte groep zien het voortgangsblok en krijgen de automatische toevoeging.

Typische toepassingen:

• Cadeau voorbehouden aan de groep « Professionals » voor een B2B-publiek.
• Cadeau voorbehouden aan de groep « VIP » in een getrouwheidsprogramma.
• Cadeau voor iedereen behalve wederverkopers (alle groepen aanvinken behalve de wederverkopersgroep).

Weergaveopties

Twee onafhankelijke schakelaars bepalen het uitzicht van het blok aan de frontzijde:

• Het voortgangsbericht tonen: schakelt het blok op de winkelwagenpagina volledig aan of uit. In de stand Nee blijft de automatische toevoeging werken, maar krijgt de klant geen enkel bericht te zien (handig als u de weergave via uw eigen thema wilt sturen).
• De voortgangsbalk tonen: schakelt de gekleurde balk onder het bericht aan of uit. De tekst blijft zichtbaar.

Hoe het technisch werkt

De schaduw-CartRule

In plaats van aan de productprijzen te raken, benut dffreegift het native cadeaumechanisme van PrestaShop via CartRule. Bij de installatie wordt een regel met de volgende eigenschappen aangemaakt:

• code = DFFREEGIFT_A7B3F2D9 (achtervoegsel willekeurig gegenereerd bij de installatie)
• gift_product = 0 (bijgewerkt bij elke bewaring van de configuratie)
• gift_product_attribute = 0 (bijgewerkt bij elke bewaring van de configuratie)
• quantity = 999 999 en quantity_per_user = 999 999 (praktisch onbeperkt)
• date_from = nu, date_to = +50 jaar
• active = 1, geen code, geen korting, geen product- of categoriebeperking

Zodra de drempel is bereikt, koppelt de module deze regel aan de winkelwagen via Cart::addCartRule($id). PrestaShop doet daarna de rest:

• Invoegen van een winkelwagenregel met gift = 1 en price = 0.
• Weergave in het winkelwagenoverzicht met een badge « Cadeau ».
• Overname bij het omzetten in een bestelling.
• Momentopname in de bestelhistoriek (het cadeau blijft zichtbaar, ook als u later van cadeauproduct wisselt).

Zakt de winkelwagen onder de drempel, dan koppelt de module de regel los via Cart::removeCartRule($id). De cadeauregel verdwijnt in hetzelfde verzoek.

De gebruikte hooks

• actionCartSave: de hoofdhook. Wordt bij elke bewaring van de winkelwagen aangeroepen (toevoegen, wijzigen, weghalen, inloggen met samenvoeging van winkelwagens). De module berekent het totaal en beslist om de regel te koppelen of los te koppelen. Een statische vlag self::$syncing voorkomt recursie als het koppelen van de regel op zijn beurt een bewaring uitlokt.
• actionObjectCartRuleDeleteBefore: zelfherstel. Verwijdert een beheerder de schaduwregel handmatig via Catalogus → Kortingen, dan merkt deze hook dat op en zet hij de ID in de configuratie op nul. De volgende synchronisatie maakt een nette regel opnieuw aan.
• displayHeader: registreert de CSS en JS aan de frontzijde (views/css/dffreegift.css en views/js/dffreegift.js).
• displayShoppingCart: bouwt het voortgangsblok op de winkelwagenpagina op.
• displayCartExtraProductActions: gereserveerd voor toekomstige uitbreidingen (badge op de cadeauregel).

De drempelberekening

Bij elke aanroep van syncCartGift() controleert de module in deze volgorde:

1. Staat de module aan? (zo niet, stopt hij)
2. Komt de klant volgens de ingestelde groepen in aanmerking? (zo niet, koppelt hij los indien gekoppeld)
3. Is het cadeauproduct geldig (bestaat het, is het actief, is het op voorraad als de controle aanstaat)? (zo niet, koppelt hij los)
4. Berekening van het totaal volgens inclusief of exclusief btw en met of zonder verzendkosten.
5. Vergelijking met de drempel, met een afrondingstolerantie van 0,001 €.
6. De regel koppelen als de drempel is bereikt en zij nog niet gekoppeld is. Loskoppelen als het bedrag onder de drempel zakt en zij gekoppeld is.

Voortgangsblok aan de frontzijde

Het blok verschijnt automatisch op de winkelwagenpagina, tussen het productoverzicht en het totaal. Er zijn twee visuele toestanden:

• In afwachting (drempel niet bereikt): lichtgrijze achtergrond, bericht « Voeg nog X,XX € toe en ontvang uw cadeau », oranje balk die vult naarmate de drempel nadert.
• Doel bereikt (drempel gehaald): lichtgroene achtergrond, bericht « Cadeau toegevoegd aan uw winkelwagen! », volle groene balk. Bij de overgang van in afwachting naar bereikt speelt een pulse-animatie.

De kleuren aanpassen

De kleuren staan in views/css/dffreegift.css. Om ze aan te passen zonder de module te wijzigen (wat uw aanpassingen bij updates zou wissen), overschrijft u de klassen in de CSS van uw thema:

.dffreegift-progress {
    border-color: #uw-kleur;
    background: #uw-achtergrond;
}
.dffreegift-progress--reached {
    background: #uw-lichtgroen;
    border-color: #uw-groen;
}
.dffreegift-progress__bar-fill {
    background: linear-gradient(90deg, #kleur1, #kleur2);
}

De teksten aanpassen

De teksten aan klantzijde zijn vertaalbaar via het standaardmechanisme van PrestaShop. Ga naar Internationaal → Vertalingen, kies « Vertalingen van de module », selecteer dffreegift en de taal, en zoek daarna het domein Modules.Dffreegift.Shop. De beschikbare teksten:

• « Voeg nog %amount% toe en ontvang uw cadeau »: het bericht in afwachting (%amount% wordt automatisch vervangen door het resterende bedrag, opgemaakt volgens de valuta en de locale).
• « Cadeau toegevoegd aan uw winkelwagen! »: het bericht wanneer het doel is bereikt.
• « Voortgang naar het cadeau »: het ARIA-label van de balk (voorgelezen door schermlezers).

Samengaan met andere promoties

Omdat het cadeau via een native CartRule wordt toegevoegd, gaat het gewoon samen met elke andere CartRule. Het verwachte gedrag:

• Andere kortingscodes van de klant (procentuele korting, vast bedrag, gratis levering): die gelden gewoon naast het cadeau. Het cadeau verbruikt de korting niet, en omgekeerd.
• Een andere regel met gift_product die elders is ingesteld: PrestaShop behandelt beide als onafhankelijke regels en voegt beide cadeaus toe. Let op als u meerdere cadeaumodules combineert.
• Een regel met product_restriction die het cadeauproduct uitsluit: de beperkende regel wint. Het cadeau wordt niet toegevoegd als een andere actieve regel het uitdrukkelijk uitsluit.
• Een regel met cart_rule_restriction: verbiedt een andere regel het gebruik van de onze via een kruisbeperking, dan wordt de automatische toevoeging geblokkeerd (native gedrag van PrestaShop).

Multistore

De module werkt met de multistoreconfiguratie van PrestaShop in de standaard winkelcontext. De instellingen (drempel, cadeauproduct, opties) worden bewaard via Configuration::updateValue, dat de huidige winkelcontext respecteert. De CartRule die bij de installatie ontstaat, hangt aan de winkel die op dat moment actief is.

Wilt u in multistore per winkel een ander cadeau, dan moet u de module voorlopig in elke winkelcontext apart installeren en instellen. Neem contact op met de ondersteuning voor een variant met een uitdrukkelijke afbakening per id_shop.

Problemen oplossen

Het cadeau wordt niet aan de winkelwagen toegevoegd

Controleer in deze volgorde:

1. Staat de module wel aan? (Modules → Configureren → schakelaar De module inschakelen).
2. Is het cadeauproduct geldig? (juiste ID, actief product, op voorraad als de voorraadcontrole aanstaat).
3. Zit de klant in een toegestane groep? (hebt u tot bepaalde groepen beperkt, dan ziet een niet-geïdentificeerde bezoeker die in geen enkele toegestane groep zit niets).
4. Is de drempel werkelijk bereikt? Bereken het totaal handmatig volgens uw parameters (inclusief of exclusief btw, met of zonder verzending).
5. Bestaat de schaduw-CartRule en is die actief? Ga naar Catalogus → Kortingen → Winkelwagenregels en zoek op DFFREEGIFT_.

Het voortgangsblok verschijnt niet op de winkelwagenpagina

Gebruikelijke oorzaken:

• De schakelaar Het voortgangsbericht tonen staat op Nee.
• De klant komt volgens de ingestelde klantgroepen niet in aanmerking.
• Het cadeauproduct is ongeldig (bestaat niet, is inactief of is uitverkocht terwijl de voorraadcontrole aanstaat).
• Uw eigen thema roept de hook displayShoppingCart niet aan. Controleer dat met grep -r "displayShoppingCart" themes/uw-thema/ of via Modules → Posities.

De CartRule is uit de backoffice verdwenen

Heeft iemand de regel via Catalogus → Kortingen verwijderd, dan heeft de hook actionObjectCartRuleDeleteBefore dat opgemerkt en de configuratie op nul gezet. Bij de volgende synchronisatie van een winkelwagen (dus zodra een klant een product toevoegt) wordt automatisch een nieuwe regel aangemaakt, met een nieuwe code DFFREEGIFT_xxxxxxxx.

Wilt u die meteen forceren zonder op een klant te wachten:

1. Ga naar Modules → DataFirefly Free Gift → Uitschakelen.
2. Schakel daarna opnieuw in. Zo ontstaat er een nette regel.

Fouten in de PrestaShop-logboeken

De module logt uitzonderingen in Geavanceerde parameters → Logboeken met het voorvoegsel [dffreegift]. Een typische melding bij een probleem:

[dffreegift] actionCartSave error: <omschrijving van de fout>

Die fouten onderbreken de werking van de winkelwagen nooit; zij zijn louter informatief. Blijft een melding terugkomen, bezorg dan de volledige tekst aan de ondersteuning.

De drempel lijkt verkeerd berekend

De berekening hangt strikt af van uw parameters Berekening inclusief btw en Verzendkosten meetellen. Om na te gaan wat PrestaShop teruggeeft:

• Inclusief btw en zonder verzending: komt overeen met het Subtotaal producten inclusief btw in het winkelwagenoverzicht.
• Inclusief btw en met verzending: komt overeen met het Totaal inclusief btw (producten plus verzendkosten als er een vervoerder is gekozen).
• Exclusief btw en zonder verzending: komt overeen met het Subtotaal producten exclusief btw.
• Exclusief btw en met verzending: komt overeen met het Totaal exclusief btw (producten plus verzendkosten exclusief btw).

Stelt u een verschil vast, vergelijk dan met de exacte regel uit het winkelwagenoverzicht. De kans is groot dat het verschil komt van verzendkosten die nog niet zijn berekend (de klant heeft nog geen vervoerder gekozen, dus staan die op 0 €).

Verwijderen

Ga naar Modules → Modulebeheer → DataFirefly Free Gift → Verwijderen. Het verwijderen wist:

• De schaduw-CartRule en al haar koppelingen met winkelwagens (lopende winkelwagens verliezen hun cadeau automatisch).
• Alle configuratiesleutels met het voorvoegsel DFFREEGIFT_.

Korte FAQ

• Verschijnt het cadeau in de mini-winkelwagen in de header? Nee, alleen op de winkelwagenpagina (hook displayShoppingCart). Elk thema behandelt de mini-winkelwagen anders, waardoor een integratie per thema nodig zou zijn. Op aanvraag bij de ondersteuning.
• Kan ik meerdere cadeaus met meerdere drempels aanbieden (bijvoorbeeld cadeau A bij 50 € en cadeau B bij 100 €)? Nee, versie 1.0.0 werkt met één cadeau en één drempel. Neem voor meerdere niveaus contact op met de ondersteuning.
• Zit het cadeau in de terugbetalingen? Zoals elk native cadeauproduct van PrestaShop verschijnt het cadeau in de bestelling tegen 0. Bij een gedeeltelijke terugbetaling blijft het cadeau in de bestelling zonder financieel gevolg.
• Mag ik het bestand dffreegift.php rechtstreeks aanpassen? Technisch wel (de code is niet versleuteld), maar officiële updates overschrijven uw aanpassingen. Maak voor diepgaande aanpassingen een override-module.

Ondersteuning en updates

Bij de module horen 12 maanden updates en ondersteuning vanaf de aankoopdatum. Ondersteuning per e-mail in het Frans of het Engels, met een antwoord binnen 24 werkuren.

Neem voor vragen of afwijkingen contact op met de DataFirefly-ondersteuning en vermeld daarbij:

• Uw PrestaShop-versie (te zien in Geavanceerde parameters → Informatie)
• Uw PHP-versie
• De geïnstalleerde versie van dffreegift
• Een beschrijving van het waargenomen gedrag tegenover het verwachte gedrag
• Een uittreksel uit de PrestaShop-logboeken indien van toepassing ([dffreegift])