Nginx Proxy

Set up an EngageTrack proxy with Nginx reverse proxy.

Nginx Proxy

Nginx is ideal for proxying EngageTrack because it handles the forwarding at the web server level with minimal overhead.

Configuration

Add the following location blocks to your Nginx server configuration:

server {
    listen 443 ssl;
    server_name yourdomain.com;
 
    # ... your existing SSL and site configuration ...
 
    # Proxy the EngageTrack SDK script
    location = /js/script.js {
        proxy_pass https://cdn.engagetrack.net/sdk.js;
        proxy_set_header Host cdn.engagetrack.net;
        proxy_ssl_server_name on;
 
        # Cache the script for 1 hour to reduce upstream requests
        proxy_cache_valid 200 1h;
        proxy_cache_use_stale error timeout updating;
    }
 
    # Proxy the event API endpoint
    location = /api/event {
        proxy_pass https://api.engagetrack.net/api/v1/event;
        proxy_set_header Host api.engagetrack.net;
        proxy_ssl_server_name on;
 
        # Forward the real client IP for geolocation
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Real-IP $remote_addr;
 
        # Pass through the request body
        proxy_set_header Content-Type $content_type;
        proxy_pass_request_body on;
    }
}

Proxy Headers

These headers are important for correct behavior:

Header	Purpose
`Host`	Set to the upstream hostname so EngageTrack's servers route the request correctly.
`X-Forwarded-For`	Pass the visitor's real IP address for geolocation.
`X-Real-IP`	Alternative IP header, used as a fallback by some configurations.
`proxy_ssl_server_name on`	Enable SNI so the TLS handshake uses the correct upstream hostname.

Without proxy_ssl_server_name on, Nginx may fail to connect to the upstream HTTPS server. This is the most common misconfiguration.

Caching the Script

The SDK script changes infrequently, so caching it reduces load on the upstream CDN. Add a caching zone if you have not already:

# In the http block (outside server)
proxy_cache_path /var/cache/nginx/engagetrack
    levels=1:2
    keys_zone=engagetrack:1m
    max_size=10m
    inactive=2h;
 
# In the location block for the script
location = /js/script.js {
    proxy_pass https://cdn.engagetrack.net/sdk.js;
    proxy_set_header Host cdn.engagetrack.net;
    proxy_ssl_server_name on;
 
    proxy_cache engagetrack;
    proxy_cache_valid 200 1h;
    proxy_cache_use_stale error timeout updating;
    add_header X-Cache-Status $upstream_cache_status;
}

Do not cache the event endpoint (/api/event). Each event POST must be forwarded to the EngageTrack API in real time.

Updated Script Tag

After configuring Nginx, update your tracking script:

<script
	defer
	data-site-id="YOUR_SITE_ID"
	data-api="https://yourdomain.com/api/event"
	src="https://yourdomain.com/js/script.js"
></script>

Test the Configuration

Reload Nginx: sudo nginx -t && sudo systemctl reload nginx
Verify the script loads: curl -I https://yourdomain.com/js/script.js
Verify the event endpoint: curl -X POST https://yourdomain.com/api/event -H "Content-Type: application/json" -d '{"test": true}'
Check your site in a browser with data-debug="true" and confirm events are sent through the proxy