Breng je tags op locatie: custom geolocatie headers in sGTM
In de wereld van digitale ads en analytics is informatie over de globale locatie van gebruikers vaak nuttig. Een beter begrip van verschillen per regio betekent immers meer granulair inzicht in het gedrag van je gebruikers. Het kan het verschil zijn tussen een succesvolle of mislukte campagne. In dit blogartikel beschrijf ik hoe je geolocatie headers kunt integreren in server-side Google Tag Manager (sGTM).
Dit blog bouwt (wederom) voort op de kennis van ‘Host server-side GTM voor een paar euro per maand’ en ‘Host server-side GTM volledig bulletproof met logging’. Ik sta daarom niet zo nadrukkelijk stil bij de Docker commands, maar wel bij de configuratie van de Caddy proxy en Docker. Voor degenen die direct aan de slag willen met geolocaties en sGTM: je kan direct naar het einde van dit artikel springen voor een eenvoudig stappenplan. Een korte leeswijzer:De Docker Image variant van bovenstaande Dockerfile is overigens beschikbaar in mijn repository. Het image kan je als volgt downloaden:Deze aanpassing zorgt ervoor dat Caddy proxy de geolocatie doorgeeft aan de server-side tagging containers.Door de headers (Vervang vervolgens de placeholders met de relevante waarden voor jouw setup, waaronder ook de Maxmind variabelen die in stap 1 zijn beschreven. Note: dat DNS mapping naar je server al goed moet staan (zie wederom mijn eerdere blog).
- Belangrijkste aanpassingen in het Caddy Image en Docker-Compose
- Configuratie van de Caddyfile voor Geolocatie
- MaxMind account + eenvoudig stappenplan
(1) Belangrijkste aanpassingen in het Caddy Image en Docker-Compose
Caddy Dockerfile en integratie van caddy-geoip2 plugin
Om geolocatie headers te onsluiten naar sGTM maken we gebruik van een aangepaste Caddy server. We maken hiervoor gebruik van de Caddy plugin ‘caddy-geoip2 ‘. Deze plugin stelt Caddy instaat om binnenkomende IP-adressen om te zetten naar geolocaties. De Dockerfile ziet er als volgt uit:FROM caddy:2.7.4-builder AS builder
RUN xcaddy build \
--with github.com/zhangjiayin/caddy-geoip2
FROM caddy:2.7.4-alpine
COPY --from=builder /usr/bin/caddy /usr/bin/caddydocker pull ghcr.io/frankdevlabs/caddy-geo-headers:v1.0.1Docker-Compose bestand voor integratie van nieuwe Caddy image
De volgende stap is het vervangen van de standaard Caddy server. Het relevante snippet in het Docker-Compose bestand is als volgt:version: '3.9'
services:
…
proxy:
image: ghcr.io/frankdevlabs/caddy-geo-headers:latest
…(2) Configuratie van de Caddyfile voor geolocatie
Caddy wordt geconfigureerd door de Caddyfile aan te passen. Het is nu van belang om de settings van het plugin caddy-geoip2 in dit bestand op te nemen. Want pas daarna zal de geolocatie kunnen worden doorgegeven aan sGTM. De documentatie van het plugin is hier te vinden. Het overnemen van deze settings is vrij eenvoudig en resulteert in het volgende Caddyfile betand:{
order geoip2_vars first
# Only configure databaseDirectory and editionID when autoupdate is not desired.
geoip2 {
accountId {$MAXMIND_ACCOUNT_ID}
databaseDirectory "/tmp/"
licenseKey {$MAXMIND_LICENSE_KEY}
lockFile "/tmp/geoip2.lock"
editionID "GeoLite2-City"
updateUrl "https://updates.maxmind.com"
updateFrequency 86400 # in seconds
}
}
(default_headers) {
header_up Host {remote_host}
header_up X-Forwarded-For {client_ip}
# header_up X-Forwarded-Proto {scheme} Unnecessary header_up X-Forwarded-Proto: the reverse proxy's default behavior is to pass headers to the upstream
header_up X-Forwarded-Host {remote_host}
}
(geoip_headers) {
header_up X-GeoIP-City-Name {geoip2.city_name}
header_up X-GeoIP-Continent-Code {geoip2.continent_code}
header_up X-GeoIP-Continent-Name {geoip2.continent_name}
header_up X-GeoIP-Country-Code {geoip2.country_code}
header_up X-GeoIP-Country-Name {geoip2.country_name}
header_up X-GeoIP-Country-EU {geoip2.country_eu}
header_up X-GeoIP-Location-Accuracy-Radius {geoip2.location_accuracy_radius}
header_up X-GeoIP-Location-Latitude {geoip2.location_latitude}
header_up X-GeoIP-Location-Longitude {geoip2.location_longitude}
header_up X-GeoIP-Location-Time-Zone {geoip2.location_time_zone}
}
{$TAG_SERVER_DOMAIN} {
log {
output file /etc/logs/{$TAG_SERVER_DOMAIN}-access.json {
roll_size 50mib
roll_keep 10
}
}
geoip2_vars strict
@hasGeoip expression {geoip2.country_code} != ""
reverse_proxy @hasGeoip http://tag-server:8080 {
import geoip_headers
import default_headers
}
reverse_proxy http://tag-server:8080 {
import default_headers
}
}
{$PREVIEW_SERVER_DOMAIN} {
log {
output file /etc/logs/{$PREVIEW_SERVER_DOMAIN}-access.json {
roll_size 50mib
roll_keep 10
}
}
reverse_proxy http://preview-server:8080 {
import default_headers
}
}
(geoip_headers) { … }) op te nemen in de reverse proxy-configuratie, zorgen we ervoor dat elke keer als een verzoek wordt doorgestuurd naar de sGTM-service, deze verrijkt wordt met waardevolle geolocatiegegevens. Dit stelt sGTM in staat om tags te genereren die aangepast zijn aan de locatie van de gebruiker, wat cruciaal is voor locatiegebaseerde personalisatie en analytics.Als je alles goed hebt gedaan, dan zijn de headers 'X-GeoIP-*' uit te lezen in je sGTM setup. Note: wat je precies met de geolocatie kan doen, laat ik even buiten beschouwing in dit blog! (3) MaxMind account + eenvoudig stappenplan
Tot slot nog een kort stappenplan om bovenstaande setup te implementeren. Ik ga er (wederom) vanuit dat je al een docker swam hebt draaien (lees anders mijn eerdere blog). In aanvulling op eerdere blogs heb je ook nog een Maxmind account nodig. Dit is de technologie waarmee IP-adressen worden omgezet in een geolocatie.- (1) Maak een Maxmind account aan
MAXMIND_LICENSE_KEY en MAXMIND_ACCOUNT_ID.- (2) Clone het repository
git clone https://github.com/frankdevlabs/sgtm-manual-server- (3) Maak het .env bestand aan:
cd sgtm-manual-server
cp .env.template .env
vim .env- (4) Start het docker sGTM stack
cd $HOME
cd sgtm-manual-server
git checkout feat/with-geo-headers
env $(cat ./.env | xargs) envsubst < ./docker-compose.yml | doc