# 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…
- Pagina:
- Taal: nl
- Bijgewerkt op: 2026-10-28
- Andere talen: [fr](https://www.datafirefly.com/documentation/dffreegift/index.md), [en](https://www.datafirefly.com/en/documentation/dffreegift/index.md), [es](https://www.datafirefly.com/es/documentation/dffreegift/index.md), [de](https://www.datafirefly.com/de/documentation/dffreegift/index.md), [pl](https://www.datafirefly.com/pl/documentation/dffreegift/index.md), [it](https://www.datafirefly.com/it/documentation/dffreegift/index.md), [pt](https://www.datafirefly.com/pt/documentation/dffreegift/index.md)
- Index:
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.1.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**.
**Let op.** De CartRule die bij de installatie ontstaat, heeft nog geen cadeauproduct toegewezen (`gift_product = 0`) en werkt dus functioneel nog niet. Zij wordt gesynchroniseerd zodra u in het configuratiescherm een ID van een cadeauproduct opslaat.
**Bijwerken vanaf 1.0.0.** Upload het zip-bestand 1.0.1 over de geïnstalleerde versie: je instellingen blijven behouden en de winkelwagenregel krijgt zijn vertaalde naam („Gratis cadeau”…).
## 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.
**Tip.** Wijzigt u later van cadeauproduct, dan wordt de CartRule bij het opslaan automatisch opnieuw gesynchroniseerd. U hoeft de regel in het onderdeel Kortingen niet handmatig aan te raken.
### 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:
```
$amount = Cart::getOrderTotal(
$with_taxes = (bool) CFG_TAX_INCL,
$type = CFG_INCLUDE_SHIPPING ? Cart::BOTH : Cart::ONLY_PRODUCTS
);
if (!CFG_INCLUDE_SHIPPING) {
$amount -= $giftValue; // waarde van het al toegevoegde cadeau
}
```
Zonder verzendkosten wordt de waarde van het cadeau dat al in de winkelwagen zit van het totaal afgetrokken (sinds 1.0.1): het cadeau telt nooit mee om de drempel te halen en wordt verwijderd zodra de andere producten weer onder de drempel zakken. Met verzendkosten trekt `Cart::BOTH` de kortingen al af, het cadeau inbegrepen. De bedragen komen uit de standaardmethoden van PrestaShop, net als het overzicht van de winkelwagen.
### 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.
**Aanbeveling.** Laat deze controle aanstaan. Zonder controle kunnen bestellingen bij het afrekenen blijven steken door een uitverkocht cadeau, wat de klantervaring schaadt en handmatig ingrijpen vraagt.
### 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.
Instellingen van DataFirefly Free Gift: cadeauproduct, drempelbedrag van de winkelwagen, berekening incl. btw, verzending en klantgroepen
## 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.
PrestaShop-winkelwagenregel aangemaakt door de module, met de actie die het cadeauproduct verstuurt
Afrekenen: het cadeauproduct staat met zijn korting in het besteloverzicht
### 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.
Sinds versie 1.0.1 wordt het blok bijgewerkt zonder de pagina te herladen telkens als de winkelwagen verandert (aantal, verwijderd artikel). De korting die het cadeau gratis maakt, ziet de klant onder een vertaalde naam: „Gratis cadeau”, „Free gift”, „Cadeau offert”, „Regalo gratuito”, „Gratis-Geschenk”, „Omaggio”, „Brinde” of „Prezent gratis”, afhankelijk van de taal.
Winkelwagen: melding met het resterende bedrag tot het cadeau en voortgangsbalk
Drempel bereikt: het cadeauproduct wordt automatisch aan de winkelwagen toegevoegd en is gratis via de korting Gratis cadeau
Winkelwagen weer onder de drempel: het cadeau wordt automatisch verwijderd en de melding wordt bijgewerkt zonder de pagina te herladen
### 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).
De module wordt vertaald geleverd in 8 talen, backoffice en front-office: Frans (brontaal), Engels, Spaans, Duits, Italiaans, Portugees, Pools en Nederlands. Deze vertalingen zijn een basis; je kunt ze aanpassen zoals hierboven beschreven.
## 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).
**Let op.** De drempel van dffreegift wordt beoordeeld op het totaal _zonder cadeau_. Hebt u een andere winkelwagenregel die het totaal verlaagt voordat dffreegift het beoordeelt, dan gebeurt de vergelijking op het totaal _na_ korting. Een winkelwagen van 60 € met 15 € korting zakt naar 45 € en haalt een drempel van 50 € dus niet.
## 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:
```
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 €).
Als het cadeau al in de winkelwagen zit, bevat het getoonde subtotaal het tegen de normale prijs, gecompenseerd door de kortingsregel „Gratis cadeau”. De module vergelijkt het totaal _zonder het cadeau_ met de drempel.
## 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_`.
**Opgelet.** Het verwijderen herstelt de cadeaus in eerdere bestellingen niet: die behouden hun oorspronkelijke momentopname met het cadeau netjes vastgelegd. Alleen de lopende winkelwagens worden geraakt.
## 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.1 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](https://www.datafirefly.com/nl/contact/) 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]`)