First-Party Tracking mit Cloudflare Pages

Richten Sie einen First-Party Proxy mit Cloudflare Pages Functions ein. Dies ist die beste Option, wenn Sie Ihre Website bereits auf Cloudflare Pages hosten.

Vorbereitung

Stellen Sie sicher, dass Sie folgendes haben:

• Ein Projekt, das auf Cloudflare Pages bereitgestellt ist
• Ihren Zenovay Tracking-Code (zu finden unter Domains, öffnen Sie Ihre Website und gehen Sie dann zum Tab General — in der Tracking-Script-Karte)
• Zugriff auf den Quellcode Ihres Projekts

Wie es funktioniert

Wenn Sie einen functions-Ordner zu Ihrem Cloudflare Pages Projekt hinzufügen, erstellt Cloudflare automatisch serverlose Funktionen. Wir erstellen eine Funktion, die Anfragen an die Zenovay-API weiterleitet und sie so für Browser als First-Party-Anfragen erscheinen lässt.

Browser → yourdomain.pages.dev/api/_z/script.js ✅ (First-Party)
               ↓
        Cloudflare Function
               ↓
         api.zenovay.com/fp/script.js (Server-zu-Server)

Schritt 1: Erstellen Sie das Functions-Verzeichnis

your-project/
├── functions/          ← HIER (Projektwurzel)
│   └── api/
│       └── _z/
│           └── [[path]].ts
├── src/
├── public/
└── package.json

Erstellen Sie die Verzeichnisstruktur:

# Erstellen Sie die Functions-Verzeichnisstruktur
mkdir -p functions/api/_z

# Überprüfen Sie, ob Sie am richtigen Ort sind
ls -la
# Sie sollten sehen: functions/  src/  public/  package.json  etc.

Nach dem Ausführen dieser Befehle sollte Ihre Projektstruktur so aussehen:

your-project/
├── functions/
│   └── api/
│       └── _z/
│           └── [[path]].ts    ← Wir werden das später erstellen
├── src/
├── public/
├── package.json
└── ...

Schritt 2: Erstellen Sie die Proxy-Funktion

Erstellen Sie die Datei functions/api/_z/[[path]].ts mit diesem Inhalt:

/**
* Zenovay First-Party Proxy
* Diese Funktion leitet Tracking-Anfragen weiter, um sie First-Party zu machen
*/

interface EventContext {
request: Request
params: { path?: string[] }
}

export async function onRequest(context: EventContext): Promise<Response> {
const { request, params } = context

// Pfad aus dem Catch-All-Parameter aufbauen
// [[path]] erfasst: script.js, e/CODE, settings/CODE, etc.
const path = (params.path || []).join('/')
const url = new URL(request.url)
const targetUrl = `https://api.zenovay.com/fp/${path}${url.search}`

// Verarbeiten Sie CORS-Preflight-Anfragen
if (request.method === 'OPTIONS') {
  return new Response(null, {
    status: 204,
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type',
    },
  })
}

try {
  // Holen Sie die echte Client-IP für genaue Geolokalisierung
  const clientIP = request.headers.get('CF-Connecting-IP') || ''

  // Leiten Sie die Anfrage mit echter IP weiter
  const proxyHeaders = new Headers(request.headers)
  proxyHeaders.set('X-Zenovay-Real-IP', clientIP)
  proxyHeaders.delete('Host')

  // Bauen Sie die Anfrage auf
  const requestInit: RequestInit = {
    method: request.method,
    headers: proxyHeaders,
  }

  // Fügen Sie den Body für POST/PUT/PATCH-Anfragen ein
  if (['POST', 'PUT', 'PATCH'].includes(request.method)) {
    requestInit.body = await request.arrayBuffer()
  }

  // Leiten Sie an Zenovay weiter
  const response = await fetch(targetUrl, requestInit)

  // Fügen Sie CORS-Header zur Antwort hinzu
  const responseHeaders = new Headers(response.headers)
  responseHeaders.set('Access-Control-Allow-Origin', '*')

  return new Response(response.body, {
    status: response.status,
    headers: responseHeaders,
  })
} catch (error) {
  console.error('Proxy error:', error)
  return new Response(JSON.stringify({ error: 'Proxy error' }), {
    status: 502,
    headers: { 'Content-Type': 'application/json' },
  })
}
}

JavaScript-Alternative

Wenn Sie lieber JavaScript verwenden (kein TypeScript), erstellen Sie functions/api/_z/[[path]].js:

/**
* Zenovay First-Party Proxy
* Diese Funktion leitet Tracking-Anfragen weiter, um sie First-Party zu machen
*/

export async function onRequest(context) {
const { request, params } = context

// Pfad aus dem Catch-All-Parameter aufbauen
const path = (params.path || []).join('/')
const url = new URL(request.url)
const targetUrl = `https://api.zenovay.com/fp/${path}${url.search}`

// Verarbeiten Sie CORS-Preflight-Anfragen
if (request.method === 'OPTIONS') {
  return new Response(null, {
    status: 204,
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type',
    },
  })
}

try {
  // Holen Sie die echte Client-IP für genaue Geolokalisierung
  const clientIP = request.headers.get('CF-Connecting-IP') || ''

  // Leiten Sie die Anfrage mit echter IP weiter
  const headers = new Headers(request.headers)
  headers.set('X-Zenovay-Real-IP', clientIP)
  headers.delete('Host')

  // Leiten Sie an Zenovay weiter
  const response = await fetch(targetUrl, {
    method: request.method,
    headers: headers,
    body: ['POST', 'PUT', 'PATCH'].includes(request.method)
      ? await request.arrayBuffer()
      : undefined,
  })

  // Fügen Sie CORS-Header zur Antwort hinzu
  const responseHeaders = new Headers(response.headers)
  responseHeaders.set('Access-Control-Allow-Origin', '*')

  return new Response(response.body, {
    status: response.status,
    headers: responseHeaders,
  })
} catch (error) {
  return new Response(JSON.stringify({ error: 'Proxy error' }), {
    status: 502,
    headers: { 'Content-Type': 'application/json' },
  })
}
}

Schritt 3: Fügen Sie das Tracking-Script hinzu

Fügen Sie dieses Script zur HTML Ihrer Website hinzu. Der Speicherort hängt von Ihrem Framework ab:

<!-- Zenovay Analytics - First-Party Tracking -->
<script defer
data-tracking-code="YOUR_TRACKING_CODE"
src="/api/_z/script.js">
</script>

Framework-spezifische Beispiele

React / Next.js

export default function RootLayout({ children }) {
return (
  <html lang="en">
    <head>
      <script
        defer
        data-tracking-code="YOUR_TRACKING_CODE"
        src="/api/_z/script.js"
      />
    </head>
    <body>{children}</body>
  </html>
)
}

Vue / Nuxt

<!-- In app.vue -->
<script setup>
useHead({
script: [
  {
    src: '/api/_z/script.js',
    defer: true,
    'data-tracking-code': 'YOUR_TRACKING_CODE'
  }
]
})
</script>

Astro

---
const { title } = Astro.props;
---
<html lang="en">
<head>
  <title>{title}</title>
  <script defer data-tracking-code="YOUR_TRACKING_CODE" src="/api/_z/script.js"></script>
</head>
<body>
  <slot />
</body>
</html>

Einfaches HTML

<!DOCTYPE html>
<html>
<head>
  <title>My Website</title>
  <script defer data-tracking-code="YOUR_TRACKING_CODE" src="/api/_z/script.js"></script>
</head>
<body>
  <!-- Your content -->
</body>
</html>

Schritt 4: Bereitstellung

Stellen Sie Ihr Projekt auf Cloudflare Pages bereit:

Option A: Mit Git (Empfohlen)

Falls Sie automatische Bereitstellungen von Git haben:

git add .
git commit -m "Add Zenovay first-party tracking"
git push

Cloudflare Pages wird automatisch Build und Bereitstellung durchführen.

Option B: Mit Wrangler CLI

# Bauen Sie Ihr Projekt zuerst
npm run build

# Stellen Sie auf Cloudflare Pages bereit
npx wrangler pages deploy ./dist --project-name=your-project-name

Schritt 5: Überprüfen Sie, ob es funktioniert

Prüfung 1: Functions Tab in Cloudflare

1. Gehen Sie zu Cloudflare Dashboard → Pages
2. Klicken Sie auf Ihr Projekt
3. Klicken Sie auf den Tab Functions
4. Sie sollten api/_z/[[path]] aufgelistet sehen

Prüfung 2: Network Tab im Browser

1. Öffnen Sie Ihre bereitgestellte Website
2. Drücken Sie F12 (oder Cmd+Option+I auf Mac) um DevTools zu öffnen
3. Klicken Sie auf den Tab Network
4. Aktualisieren Sie die Seite (Cmd+R oder Ctrl+R)
5. Geben Sie im Filterfeld script.js ein
6. Suchen Sie nach /api/_z/script.js

Das sollten Sie sehen:

• Status: 200 ✅
• Domain: Ihre Pages Domain (z. B. your-project.pages.dev)
• Response: JavaScript-Code

Prüfung 3: Firefox Strict Mode (Am Wichtigsten!)

Firefox hat den strengsten Tracking-Schutz. Falls es in Firefox funktioniert, funktioniert es überall.

1. Öffnen Sie den Firefox-Browser
2. Klicken Sie auf das Menü (☰) → Einstellungen
3. Klicken Sie auf Datenschutz & Sicherheit in der linken Seitenleiste
4. Wählen Sie unter "Enhanced Tracking Protection" die Option Strict
5. Besuchen Sie Ihre Website
6. Öffnen Sie DevTools (F12) → Network Tab
7. Aktualisieren Sie und überprüfen Sie, dass /api/_z/script.js mit Status 200 geladen wird

Prüfung 4: Zenovay Dashboard

1. Gehen Sie zu app.zenovay.com und melden Sie sich an
2. Klicken Sie auf Ihre Website
3. Besuchen Sie Ihre bereitgestellte Website in einem anderen Tab
4. Innerhalb von 1-2 Minuten sollten Sie den Besuch in Ihrem Dashboard sehen

Finale Checkliste

Überprüfen Sie, bevor Sie fertig sind, ALL diese Punkte:

• Datei functions/api/_z/[[path]].ts existiert im Projektwurzelverzeichnis
• Funktion erscheint im Cloudflare Pages Functions Tab
• Script wird unter /api/_z/script.js mit Status 200 geladen
• Attribut data-tracking-code enthält Ihren korrekten Tracking-Code
• In Firefox mit Enhanced Tracking Protection auf Strict getestet
• Besuche erscheinen im Zenovay Dashboard

Troubleshooting

Funktion gibt 404 zurück

Ursache: Die Funktionsdatei befindet sich an der falschen Position oder hat den falschen Namen.

Lösung:

1. Überprüfen Sie, dass sich die Datei exakt unter functions/api/_z/[[path]].ts befindet
   • functions-Ordner muss im Projektwurzelverzeichnis sein
   • Muss Unterverzeichnisse api/_z/ haben
   • Muss [[path]].ts mit doppelten Klammern heißen
2. Stellen Sie sicher, dass der functions-Ordner in Ihrer Bereitstellung enthalten ist
3. Überprüfen Sie den Functions Tab im Cloudflare Dashboard

Funktion gibt 500 zurück

Ursache: Es gibt einen Syntax- oder Runtime-Fehler im Funktionscode.

Lösung:

1. Überprüfen Sie die Funktionsprotokolle in Cloudflare auf Fehlerdetails:
   • Gehen Sie zu Ihrem Pages Projekt → Functions → Logs
2. Überprüfen Sie, dass der gesamte Code korrekt kopiert wurde
3. Stellen Sie sicher, dass Sie onRequest exportieren (nicht export default)

TypeScript-Fehler während des Build

Ursache: Fehlende Typdefinitionen.

Lösung: Option 1: Installieren Sie Cloudflare Workers Typen:

npm install --save-dev @cloudflare/workers-types

Option 2: Verwenden Sie stattdessen die JavaScript-Version (benennen Sie in [[path]].js um)

CORS-Fehler in der Konsole

Ursache: CORS-Header werden nicht korrekt hinzugefügt.

Lösung: Stellen Sie sicher, dass Ihre Funktion beide Punkte enthält:

1. Der OPTIONS-Handler für Preflight-Anfragen
2. responseHeaders.set('Access-Control-Allow-Origin', '*') in der Antwort

Geolokalisierung ist falsch

Ursache: Client-IP wird nicht weitergeleitet.

Lösung: Überprüfen Sie, dass Ihre Funktion folgendes enthält:

const clientIP = request.headers.get('CF-Connecting-IP') || ''
proxyHeaders.set('X-Zenovay-Real-IP', clientIP)

Script wird geladen, aber keine Daten im Dashboard

Ursache: Tracking-Code Mismatch.

Lösung:

1. Öffnen Sie DevTools Konsole (F12 → Console Tab) und suchen Sie nach Fehlern
2. Überprüfen Sie, dass Ihr data-tracking-code exakt mit dem in Ihrem Zenovay Dashboard übereinstimmt (case-sensitive!)
3. Stellen Sie sicher, dass die Domain in Zenovay registriert ist

Nächste Schritte

• Custom Events - Verfolgung von Benutzerinteraktionen
• Visitor Identification - Link Analytics zu Benutzern
• Troubleshooting - Mehr Hilfe bei Problemen