Tapfiliate server-side GTM tag template

De Tapfiliate Server Tag-template doet affiliate tracking vanuit een GTM server container. In plaats van API-aanroepen vanuit de browser stuurt hij conversie- en klantdata rechtstreeks vanaf je server naar de Tapfiliate REST API.

Deze template werkt alleen in een server-side container. In een webcontainer doet hij niets.

• Vier operatietypes: Create Conversion, Update Conversion, Create Customer en Update Customer
• Verstuurt server-side naar https://api.tapfiliate.com/1.7/pb/, zodat je API-token niet in client-side code belandt
• Stuurt User-Agent en client-IP (X-Forwarded-For, X-Real-IP) uit het oorspronkelijke verzoek door voor kloppende attributie
• Drie attributiemethodes met een vaste volgorde: coupon, dan click ID, dan referral code
• Accepteert optionele JSON-metadata voor eigen velden zoals abonnementsvorm of klantwaarde
• Regelt statuswijzigingen van conversies, goedgekeurd of afgekeurd, voor je commissieproces

Je token authenticeert elk verzoek. Je vindt hem in het Tapfiliate-dashboard onder Settings, API Keys. Vul hem in het tagveld in, of verwijs naar een server-side GTM-variabele, wat prettiger is zodra je meerdere tags hebt.

Create Conversion. De meest gebruikte. Registreert een verkoop, lead of aanmelding via een POST naar https://api.tapfiliate.com/1.7/pb/con/c/.

Update Conversion. Keurt een eerder aangemaakte conversie goed of af, bijvoorbeeld na levering of een retour. POST naar https://api.tapfiliate.com/1.7/pb/con/u/.

Create Customer. Legt een klant vast en koppelt die aan een affiliate voor terugkerende commissie. POST naar https://api.tapfiliate.com/1.7/pb/cus/c/.

Update Customer. Werkt een bestaande klant bij, bijvoorbeeld om de attributie te wijzigen of metadata toe te voegen. POST naar https://api.tapfiliate.com/1.7/pb/cus/u/.

Zijn er meerdere attributievelden gevuld, dan werkt Tapfiliate deze volgorde af:

• Coupon, gematcht tegen de affiliate-couponcodes in Tapfiliate
• Click ID, de klik-identificatie van Tapfiliate, meestal in een cookie
• Referral code, de code van de affiliate, meestal via een URL-parameter

Eén methode volstaat, maar er meerdere meegeven geeft Tapfiliate iets om op terug te vallen.

Het Meta Data-veld neemt een JSON-string aan voor eigen kenmerken die je gebruikt in rapportage of commissieregels:

{"product_category": "subscription",
 "plan_duration": "annual",
 "is_first_purchase": true}

Los daarvan leest de template het inkomende verzoek en stuurt de User-Agent en het client-IP (X-Forwarded-For of X-Real-IP) door naar Tapfiliate, dat die gebruikt voor fraudedetectie en geotargeting. Daar hoef je niets voor in te stellen.

Je server container moet eerst events ontvangen: een GA4- of custom client die inkomende verzoeken verwerkt, een webcontainer die naar de sGTM transport-URL stuurt, en purchase-events met transactie-ID, bedrag en coupon erin.

• Maak een tag met de Tapfiliate Server Tag-template.
• Zet Operation Type op Create Conversion en vul je API-token in.
• Koppel Transaction ID aan {{Event - transaction_id}}.
• Koppel Conversion Value aan {{Event - value}} en Currency aan {{Event - currency}}.
• Koppel Coupon aan {{Event - coupon}} als die er is.
• Trigger op een custom event dat matcht met purchase uit je GA4-client, en publiceer.

Werk je met programma's waar conversies handmatig goedgekeurd worden, maak dan een tweede tag met Operation Type Update Conversion. Die wordt meestal server-to-server getriggerd, bijvoorbeeld door een webhook van je ordersysteem op je sGTM-endpoint.

401 Unauthorized. De token ontbreekt of klopt niet. Controleer hem onder Settings, API Keys, en let op spaties aan het begin of eind.

Conversies komen binnen maar zonder affiliate. Minstens één attributieveld moet matchen met een bekende affiliate. Bekijk de payload in sGTM Preview. Meestal is het een couponcode die bij geen enkele affiliate hoort, of een ontbrekend click ID.

Dubbele conversies. Tapfiliate dedupliceert op transactie-ID, dus duplicaten betekenen dat je purchase-event vaker afgaat. Bouw deduplicatie in je sGTM-opzet, bijvoorbeeld via een Firestore-cache of het unieke event-ID.

Conversiebedrag nul of leeg. De gekoppelde variabele moet een numerieke waarde teruggeven. Komt die uit GA4, controleer dan of de value-parameter in je webcontainer goed staat.

Client-IP komt niet door. De template leest X-Forwarded-For en X-Real-IP. Strippen je CDN of load balancer die headers, dan ziet Tapfiliate het IP van je server. Zorg dat je infrastructuur ze doorlaat.

Metadata wordt geweigerd. Het veld moet geldige JSON bevatten. Enkele aanhalingstekens en een komma te veel zijn de klassiekers. Valideer het voordat je het plakt.

• Tapfiliate REST API-documentatie: https://tapfiliate.com/docs/rest/
• Tapfiliate helpcentrum: https://tapfiliate.com/docs/
• Documentatie server-side GTM: https://developers.google.com/tag-platform/tag-manager/server-side
• GTM Help Center: https://support.google.com/tagmanager/