Generic Proxy Setup

This guide covers the core concepts for setting up a Rybbit proxy with any reverse proxy or server framework. If your specific framework has a dedicated guide, we recommend following that instead for optimized instructions.

Prerequisites

Before setting up the proxy, ensure you have:

• A domain or subdomain where you'll serve the proxied scripts (e.g., yourdomain.com or analytics.yourdomain.com)
• SSL/TLS certificate for HTTPS (required for modern browsers)
• Server or platform with reverse proxy capabilities
• Your Rybbit instance URL:
  • Cloud: https://app.rybbit.io
  • Self-hosted: Your Rybbit instance URL (e.g., https://analytics.yourcompany.com)
• Your Rybbit site ID (found in your Rybbit dashboard)

Understanding the Endpoints

Rybbit uses several endpoints for tracking. You can choose between a minimal setup or full proxy:

Implementation Steps

Your domain path          →  Rybbit backend
-----------------            ---------------
/analytics/script.js      →  https://app.rybbit.io/api/script.js
/analytics/track          →  https://app.rybbit.io/api/track
/analytics/replay.js      →  https://app.rybbit.io/api/replay.js
... and so on

Cache-Control: public, max-age=3600  # For scripts
Cache-Control: public, max-age=300   # For config
Cache-Control: no-store              # For tracking POSTs

<script src="https://app.rybbit.io/api/script.js" async data-site-id="YOUR_SITE_ID"></script>

<script src="https://yourdomain.com/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Referrer-Policy: strict-origin-when-cross-origin

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type

Request Header Forwarding

Forward the browser's original headers to the Rybbit backend. The simplest and most robust approach is to pass through every incoming request header except Host and hop-by-hop headers (Connection, Content-Length — let your HTTP client recompute those).

Why this matters: Rybbit's bot detection scores requests on headers that every real browser sends. A proxy that forwards only User-Agent and the visitor IP produces requests that look exactly like a script — the events return 200 OK but are classified as bot traffic and never appear in your dashboard.

If you must whitelist headers instead of passing everything through, this is the minimum set:

Forwarded IP Headers

Set X-Forwarded-For to the original visitor IP before forwarding the request to Rybbit, and enable the First-Party Proxy toggle in your site settings so Rybbit trusts it unconditionally.

Cloudflare Worker example:

const clientIp = request.headers.get('CF-Connecting-IP') || '0.0.0.0';

const proxyHeaders = new Headers(request.headers);
proxyHeaders.set('X-Real-IP', clientIp);
proxyHeaders.set('X-Forwarded-For', clientIp);

CloudFront example:

• Set X-Forwarded-For to the viewer IP from a CloudFront Function/Lambda@Edge (CloudFront cannot forward X-Real-IP)
• Forward User-Agent, Referer, and Accept-Language

// CloudFront Function (viewer-request)
function handler(event) {
  event.request.headers["x-forwarded-for"] = { value: event.viewer.ip };
  return event.request;
}

Bandwidth Considerations

Proxying adds bandwidth usage to your infrastructure. Here's what to expect:

Typical bandwidth per session:

• Initial script load: ~18 KB (one-time per session)
• Pageview tracking: ~0.5-2 KB per pageview
• Custom events: ~0.5-3 KB per event
• Session replay: 50-500 KB per session (if enabled, varies by session length)
• Web Vitals: ~1-2 KB per page

Estimated monthly bandwidth for a site with 100,000 monthly sessions:

• Without session replay: ~5-10 GB/month
• With session replay: ~30-80 GB/month

Most modern hosting plans can handle this easily, but verify your bandwidth limits if you have high traffic or session replay enabled.

Performance Optimization

Use a CDN

If your server has CDN capabilities (like Cloudflare, Fastly, or AWS CloudFront), configure it to cache the static scripts:

• Cache scripts at edge locations worldwide
• Reduce latency for global users
• Offload bandwidth from your origin server

Enable Compression

Ensure your proxy enables gzip or brotli compression:

Content-Encoding: gzip

This can reduce script size by 60-70%, improving load times and reducing bandwidth.

Connection Reuse

Configure your proxy to maintain persistent connections to Rybbit's backend to reduce latency on repeated requests.

Common Proxy Patterns

https://analytics.yourdomain.com/script.js  →  https://app.rybbit.io/api/script.js
https://analytics.yourdomain.com/track      →  https://app.rybbit.io/api/track

https://yourdomain.com/analytics/script.js  →  https://app.rybbit.io/api/script.js
https://yourdomain.com/analytics/track      →  https://app.rybbit.io/api/track

Security Considerations

Rate Limiting

Consider adding rate limiting to prevent abuse:

• Limit POST requests to tracking endpoints (e.g., 100 requests per minute per IP)
• Whitelist your Rybbit backend IP if possible
• Monitor for unusual traffic patterns

Request Size Limits

Set appropriate request body size limits:

• /api/track, /api/identify: 1 MB max
• /api/session-replay/record/*: 10 MB max (session replay can send large payloads)

HTTPS Only

Always serve your proxy over HTTPS:

• Modern browsers require HTTPS for many features
• Protects user data in transit
• Required for accurate tracking in secure contexts

Troubleshooting

If something isn't working, check:

1. Script loads but no events tracked: Verify all tracking endpoints (/api/track, etc.) are proxied
2. CORS errors: Ensure CORS headers are preserved from Rybbit backend
3. 404 errors: Check that URL paths exactly match expected format
4. Incorrect geolocation: Verify X-Forwarded-For is set to the visitor IP and the First-Party Proxy toggle is enabled in site settings
5. /track returns 200 but nothing appears in the dashboard: Your proxy is probably forwarding too few headers and events are being classified as bot traffic — forward the full browser header set (see Request Header Forwarding)
6. Session replay not working: Add /api/replay.js and /api/session-replay/record/:siteId endpoints

For more detailed troubleshooting, see our troubleshooting guide.

Next Steps

Now that you understand the generic concepts, choose your specific framework or platform for detailed implementation instructions:

• Next.js
• Nginx
• Caddy
• Vercel
• Express.js
• Laravel
• Astro
• Cloudflare Workers