Zum Hauptinhalt springen
Zenovaydocs
7 Min. Lesedauer

First-Party Tracking mit Netlify

Richten Sie einen First-Party-Proxy auf Netlify mit einfachen Weiterleitungsregeln ein. Funktioniert mit jeder statischen Website oder jedem Framework.

Schwierigkeit: Einfach - Fügen Sie einfach ein paar Zeilen zu einer Konfigurationsdatei hinzu.

Warum dies funktioniert (Same-Origin)

Dieser Ansatz verwendet /api/_z/script.js, die sich auf der gleichen Herkunft wie Ihre Website befindet. Firefox ETP und andere Trackingschutzmaßnahmen blockieren nur Cross-Origin-Anfragen.

  • Browser sieht: yourdomain.com/api/_z/script.js → Gleiche Herkunft ✅
  • Netlify leitet die Anfrage serverseitig an den Zenovay-Server weiter (Browser sieht dies nicht)
  • Alle Trackingschutzmaßnahmen werden umgangen, da die Anfrage First-Party ist

Bevor Sie beginnen

Stellen Sie sicher, dass Sie haben:

  • Ein Projekt, das auf Netlify bereitgestellt ist
  • Ihren Zenovay-Tracking-Code (zu finden unter Domains → Ihre Website → Allgemein, in der Tracking-Skript-Karte)
  • Zugriff auf die Build-Konfiguration Ihres Projekts

Format Ihres Tracking-Codes

Ihr Tracking-Code sieht wie folgt aus: ZV_XXXXXXXXXX

  • Beginnt mit ZV_
  • Gefolgt von 10 Zeichen (Buchstaben und Zahlen)
  • GROSS-/KLEINSCHREIBUNG BEACHTEN - kopieren Sie ihn genau
  • Beispiel: ZV_Q8U0GYD70WR
Domain-Einstellungsseite „Allgemein“ mit der Tracking-Skript-Karte und dem First-Party-Tab
Finden Sie Ihren Tracking-Code und den First-Party-Tab unter Domains → Ihre Website → Allgemein.

Option 1: Verwenden Sie die _redirects-Datei (Am einfachsten)

Der einfachste Weg zur Einrichtung des Proxys ist die Verwendung von Netlifys _redirects-Datei.

Schritt 1: Erstellen Sie die Weiterleitungsdatei

Erstellen Sie eine _redirects-Datei in Ihrem public/-Ordner (oder wo immer sich Ihre statischen Assets befinden):

public/_redirectsTEXT
# Zenovay First-Party-Tracking-Proxy
/api/_z/*  https://api.zenovay.com/fp/:splat  200

Wie es funktioniert: Der Status-Code 200 macht dies zu einem Rewrite (Proxy) anstelle einer Umleitung. Der Browser sieht Ihre Domain, aber Netlify ruft die Zenovay API im Hintergrund ab.

Schritt 2: Fügen Sie das Tracking-Skript hinzu

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

Schritt 3: Bereitstellen

TerminalBash
netlify deploy --prod

Oder führen Sie ein Push zu Ihrem Git-Repository durch, falls Sie kontinuierliche Bereitstellung konfiguriert haben.

Option 2: Verwenden Sie netlify.toml (Expliziter)

Für komplexere Konfigurationen verwenden Sie netlify.toml:

Schritt 1: Erstellen oder aktualisieren Sie netlify.toml

Fügen Sie die Weiterleitungsregel zu Ihrer netlify.toml im Projektstammverzeichnis hinzu:

netlify.tomlTOML
# Zenovay First-Party-Tracking-Proxy
[[redirects]]
from = "/api/_z/*"
to = "https://api.zenovay.com/fp/:splat"
status = 200
force = true

Wenn Sie bereits eine netlify.toml haben, fügen Sie die Umleitung zu Ihrer vorhandenen Datei hinzu:

netlify.toml (mit bestehender Konfiguration)TOML
[build]
command = "npm run build"
publish = "dist"

# Zenovay First-Party-Tracking-Proxy
[[redirects]]
from = "/api/_z/*"
to = "https://api.zenovay.com/fp/:splat"
status = 200
force = true

# Ihre anderen Umleitungen...
[[redirects]]
from = "/*"
to = "/index.html"
status = 200

Reihenfolge ist wichtig! Platzieren Sie die Zenovay-Umleitung VOR eventuellen Catch-All-Umleitungen (wie SPA-Fallbacks). Netlify verarbeitet Umleitungen in der angegebenen Reihenfolge.

Schritt 2: Fügen Sie das Tracking-Skript hinzu

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

Schritt 3: Bereitstellen

TerminalBash
netlify deploy --prod

Framework-spezifische Beispiele

React (Create React App)

public/_redirectsTEXT
/api/_z/*  https://api.zenovay.com/fp/:splat  200
public/index.htmlHTML
<!DOCTYPE html>
<html lang="en">
<head>
  <script defer data-tracking-code="YOUR_TRACKING_CODE" src="/api/_z/script.js"></script>
  <!-- other head elements -->
</head>
<body>
  <div id="root"></div>
</body>
</html>

Vue.js (Vite)

public/_redirectsTEXT
/api/_z/*  https://api.zenovay.com/fp/:splat  200
index.htmlHTML
<!DOCTYPE html>
<html lang="en">
<head>
  <script defer data-tracking-code="YOUR_TRACKING_CODE" src="/api/_z/script.js"></script>
</head>
<body>
  <div id="app"></div>
  <script type="module" src="/src/main.js"></script>
</body>
</html>

Gatsby

netlify.tomlTOML
[build]
command = "gatsby build"
publish = "public"

[[redirects]]
from = "/api/_z/*"
to = "https://api.zenovay.com/fp/:splat"
status = 200
force = true
gatsby-ssr.jsJSX
import React from 'react'

export const onRenderBody = ({ setHeadComponents }) => {
setHeadComponents([
  <script
    key="zenovay"
    defer
    data-tracking-code="YOUR_TRACKING_CODE"
    src="/api/_z/script.js"
  />
])
}

Hugo

static/_redirectsTEXT
/api/_z/*  https://api.zenovay.com/fp/:splat  200
layouts/partials/head.htmlHTML
<script defer data-tracking-code="YOUR_TRACKING_CODE" src="/api/_z/script.js"></script>

11ty (Eleventy)

src/_redirectsTEXT
/api/_z/*  https://api.zenovay.com/fp/:splat  200

Stellen Sie sicher, dass _redirects beim Build kopiert wird, indem Sie Ihre .eleventy.js hinzufügen:

.eleventy.jsJavaScript
module.exports = function(eleventyConfig) {
eleventyConfig.addPassthroughCopy("src/_redirects");
// ... rest of config
}

Überprüfen Sie, ob es funktioniert

Überprüfung im Netlify-Dashboard

  1. Gehen Sie zu Ihrer Website im Netlify-Dashboard
  2. Klicken Sie auf Sitenkonfiguration → Umleitungen
  3. Sie sollten Ihre /api/_z/*-Umleitung aufgelistet sehen

Überprüfen Sie den Netzwerk-Tab

  1. Besuchen Sie Ihre bereitgestellte Website
  2. Öffnen Sie DevTools (F12)
  3. Gehen Sie zum Netzwerk-Tab
  4. Laden Sie die Seite neu
  5. Suchen Sie nach /api/_z/script.js

Sie sollten sehen:

  • Status: 200
  • Domain: Ihre Netlify-Domain
  • Response: JavaScript-Code

Test im Firefox Strikten Modus

  1. Öffnen Sie Firefox
  2. Einstellungen → Datenschutz und Sicherheit → Verbesserter Tracking-Schutz: Streng
  3. Besuchen Sie Ihre Website
  4. Stellen Sie sicher, dass das Skript erfolgreich geladen wird

Fehlerbehebung

Umleitung gibt 404 zurück

Ursache: Die _redirects-Datei wird nicht veröffentlicht oder befindet sich am falschen Ort.

Lösung:

  1. Stellen Sie sicher, dass _redirects sich in Ihrem Veröffentlichungsverzeichnis befindet (normalerweise public/ oder dist/)
  2. Für Build-Tools müssen Sie sicherstellen, dass die Datei während des Builds kopiert wird
  3. Überprüfen Sie im Netlify-Dashboard → Umleitungen, ob es erkannt wird

Umleitung verursacht eine Schleife

Ursache: Eine andere Umleitung verursacht eine Störung.

Lösung:

  1. Verwenden Sie force = true in netlify.toml, um andere Regeln zu außer Kraft zu setzen
  2. Stellen Sie sicher, dass die Zenovay-Umleitung VOR Catch-All-Regeln kommt
  3. Überprüfen Sie auf konfliktierende _redirects- und netlify.toml-Regeln

Skript wird geladen, gibt aber HTML zurück

Ursache: Eine Catch-All-SPA-Umleitung fängt die Anfrage ab.

Lösung: Platzieren Sie die Zenovay-Umleitung VOR Ihrem SPA-Fallback:

netlify.tomlTOML
# Dies MUSS zuerst kommen
[[redirects]]
from = "/api/_z/*"
to = "https://api.zenovay.com/fp/:splat"
status = 200
force = true

# SPA-Fallback kommt danach
[[redirects]]
from = "/*"
to = "/index.html"
status = 200

Geolokalisierung zeigt den falschen Standort an

Ursache: Netlify's Proxy leitet die Client-IP nicht automatisch weiter.

Lösung: Leider unterstützen einfache Netlify-Umleitungen keine benutzerdefinierten Header. Die Geolokalisierung basiert auf dem Standort des Netlify-Kanten-Servers. Für genaue Geolokalisierung sollten Sie Folgendes in Betracht ziehen:

  1. Verwendung von Netlify Functions (Edge Functions) - komplexeres Setup
  2. Verwendung von Cloudflare Workers vor Netlify

Erweitert: Verwenden Sie Netlify Edge Functions

Für mehr Kontrolle (einschließlich IP-Weiterleitung) können Sie Netlify Edge Functions verwenden:

netlify/edge-functions/zenovay-proxy.tsTypeScript
import type { Context } from '@netlify/edge-functions'

export default async (request: Request, context: Context) => {
const url = new URL(request.url)
const path = url.pathname.replace('/api/_z/', '')
const targetUrl = `https://api.zenovay.com/fp/${path}${url.search}`

// Get client IP
const clientIP = context.ip || ''

const headers = new Headers(request.headers)
headers.set('X-Zenovay-Real-IP', clientIP)
headers.delete('Host')

const response = await fetch(targetUrl, {
  method: request.method,
  headers: headers,
  body: request.body,
})

const responseHeaders = new Headers(response.headers)
responseHeaders.set('Access-Control-Allow-Origin', '*')

return new Response(response.body, {
  status: response.status,
  headers: responseHeaders,
})
}

export const config = {
path: '/api/_z/*',
}

Vollständiges Beispiel

ProjektstrukturTEXT
my-netlify-site/
├── netlify.toml
├── public/
│   ├── _redirects
│   └── index.html
├── src/
│   └── ...
└── package.json
netlify.tomlTOML
[build]
command = "npm run build"
publish = "dist"

[[redirects]]
from = "/api/_z/*"
to = "https://api.zenovay.com/fp/:splat"
status = 200
force = true
public/index.htmlHTML
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My Site</title>
  <script defer data-tracking-code="YOUR_TRACKING_CODE" src="/api/_z/script.js"></script>
</head>
<body>
  <div id="app"></div>
</body>
</html>

Abschließende Checkliste

Bevor Sie fertig sind, überprüfen Sie ALLE diese Punkte:

  • _redirects oder netlify.toml hat die Zenovay-Weiterleitungsregel
  • Weiterleitungsregel kommt VOR eventuellen SPA-Catch-All-Regeln
  • Script-Tag verwendet /api/_z/script.js (nicht die direkte Zenovay-URL)
  • data-tracking-code-Attribut enthält Ihren korrekten Tracking-Code
  • Projekt wird bereitgestellt (nicht nur lokal ausgeführt)
  • In Firefox mit Enhanced Tracking Protection auf Streng getestet
  • Besuche erscheinen im Zenovay-Dashboard

Nächste Schritte

War diese Seite hilfreich?