6 Min. Lesedauer

First-Party Proxy Setup

Serve Zenovay tracking through your own domain to bypass browser tracking protection and ad blockers.

A first-party proxy routes tracking through YOUR domain, so browsers see it as first-party and allow it. This can recover 15-30% more visitors.

Why Use a First-Party Proxy?

Modern browsers block third-party tracking scripts. Here's what each browser blocks:

Browser	Protection	Blocks api.zenovay.com?
Firefox	Enhanced Verfolgung Protection (ETP)	Yes
Brave	Shields	Yes
Edge	Verfolgung Prevention	Yes
Opera	Built-in Blocker	Yes
Safari	Intelligent Verfolgung Prevention (ITP)	Partial
Chrome	Limited (for now)	Some extensions

How It Works

How First-Party Proxy WorksTEXT

Without proxy (blocked):
Browser → api.zenovay.com ❌ (Third-party = blocked by browsers)

With proxy (works):
Browser → yourdomain.com/api/_z/* ✅ (First-party = allowed)
     ↓
Your Server → api.zenovay.com/fp/* (Server-to-server = always works)

The browser only sees requests to YOUR domain, so tracking protection doesn't apply.

Understanding Same-Origin (Critical!)

This is the most important concept to understand.

Not all "first-party" approaches are equal. There's a critical difference between same-domain proxy and custom subdomain.

The Two Approaches

Approach	Example	Firefox ETP	Why
Same-domain proxy	`/api/_z/script.js`	✅ WORKS	Same origin
Custom subdomain	`z.yourdomain.com`	❌ BLOCKED	Different origin

Was ist "Same Origin"?

Browsers define "same origin" as: same protocol + same domain + same port

Same Origin ExamplesTEXT

https://yourdomain.com (your site)

❌ https://z.yourdomain.com    → Different origin (different subdomain)
❌ https://api.yourdomain.com  → Different origin (different subdomain)
✅ https://yourdomain.com/api/ → SAME origin (just a path)

Why Subdomains Don't Work for Firefox

Even though z.yourdomain.com looks "first-party", Firefox ETP treats it as third-party because:

Origin check: z.yourdomain.com ≠ yourdomain.com
Cross-origin request: Browser makes request to different origin
ETP blocks: Firefox blocks cross-origin tracking requests

Why Same-Domain Proxy Works

With /api/_z/script.js:

Origin check: yourdomain.com/api/_z/ = yourdomain.com ✅
Same-origin request: Browser makes first-party request
ETP allows: Firefox allows same-origin requests
Server proxies: Your server forwards to Zenovay (browser never sees this)

Bottom line: If you need Firefox compatibility, use the same-domain proxy approach (Vercel, Netlify, Weiter.js, Cloudflare Pages, nginx, Apache, Astro).

The Cloudflare Workers custom subdomain approach (z.yourdomain.com) does NOT bypass Firefox ETP - it only bypasses some ad blockers.

Choose Your Platform

Select your hosting platform to get started with a detailed step-by-step guide:

Weiter.js

Use next.config.js rewrites. The simplest option for Weiter.js projects.

Cloudflare Workers

Perfect for shared hosting users. Create a free Worker in 5 minutes.

Cloudflare Pages

Use Pages Functions if you're already hosting on Cloudflare Pages.

Vercel

Use vercel.json rewrites or Edge Middleware. Works with any framework.

Netlify

Simple _redirects file or netlify.toml configuration.

nginx / Apache

Self-hosted servers using reverse proxy configuration.

Astro

API routes for Astro projects with SSR enabled.

Quick Reference

Your Setup	Best Option	Guide
Weiter.js project	`next.config.js` rewrites	Weiter.js Guide
Vercel (any framework)	`vercel.json` rewrites	Vercel Guide
Netlify	`_redirects` file	Netlify Guide
Cloudflare Pages	Pages Functions	CF Pages Guide
Cloudflare (general)	Cloudflare Workers	CF Workers Guide
Self-hosted server	nginx/Apache proxy	nginx/Apache Guide
Astro	API routes	Astro Guide
Shared hosting (Hostinger, GoDaddy, etc.)	Cloudflare Workers (free)	CF Workers Guide

Using shared hosting (Hostinger, GoDaddy, Bluehost)?

These platforms don't support server-side proxying. Create a FREE Cloudflare account and use Cloudflare Workers instead. It takes 5 minutes and works perfectly.

→ Cloudflare Workers Guide

After Setup: Update Your Script

Once you've set up the proxy, update your tracking script:

Before (Third-party - may be blocked)HTML

<script defer
data-tracking-code="YOUR_TRACKING_CODE"
src="https://api.zenovay.com/z.js">
</script>

After (First-party - always works)HTML

<script defer
data-tracking-code="YOUR_TRACKING_CODE"
src="/api/_z/script.js">
</script>

IMPORTANT: Cloudflare Workers Limitation

The Cloudflare Workers approach (z.yourdomain.com) does NOT bypass Firefox ETP because subdomains are still different origins.

For Firefox compatibility, use one of the same-domain proxy options instead:

Verify It's Working

After setting up, verify the proxy is working:

1. Check Network Tab

Open DevTools (F12 or Cmd+Option+I)
Go to the Network tab
Reload your page
Look for /api/_z/script.js (or your custom domain path)
Should show 200 status from YOUR domain

2. Test in Firefox (Strictest)

Firefox has the strictest tracking protection:

Open Firefox
Settings → Datenschutz & Security → Enhanced Verfolgung Protection: Strict
Visit your website
Check the script loads successfully

If it works in Firefox strict mode, it works everywhere.

API Endpoints Reference

Your proxy should forward these paths:

Your Path	Zenovay API	Purpose
`/api/_z/script.js`	`/fp/script.js`	Verfolgung script
`/api/_z/e/:code`	`/fp/e/:code`	Page view events
`/api/_z/settings/:code`	`/fp/settings/:code`	Website settings
`/api/_z/load`	`/fp/load`	Dynamic loader

Troubleshooting

Having issues? Check these common problems:

Script returns 404 - Verify your proxy path configuration
CORS errors - Make sure your proxy adds CORS headers
Geolocation wrong - Forward the client IP with X-Zenovay-Real-IP header
Still blocked - Make sure you're using the proxied path, not the direct URL

For detailed troubleshooting, see each platform's specific guide or the general troubleshooting page.

Weiter Steps

Custom Events - Track button clicks and form submissions
Besucher Identification - Connect analytics to user accounts
Troubleshooting - Common issues and fixes