Zum Hauptinhalt springen

Klar Pixel über serverseitiges Tracking einrichten

Verfasst von Franz May

Wie du den Klar-Tracking-Pixel einrichtest, indem du deine Domain validierst, das Tracking-Skript implementierst und die UTM-Parameter anpasst.

Möchtest du den Attributions-Report in Klar nutzen? Gute Wahl 🎉

Damit unsere voll integrierte Attributionslösung funktioniert, musst du in Klar die Klar-Pixel-Datenquelle konfigurieren und ein Tracking-Skript auf deiner Seite einbauen. Das dauert nur ein paar Minuten.

1. Die Klar-Pixel-Datenquelle hinzufügen

Wenn du mehrere Domains hast, solltest du für jeden dieser Stores eine eigene Pixel-Datenquelle erstellen.

  • Gehe in Klar zur Seite Store-Konfigurator und klicke auf Datenquelle verbinden

  • Wähle die Datenquelle Klar Pixel

  • Gib der Datenquelle einen Namen – z. B. Klar Tracking Script
    ​

  • Konfiguriere ein Basis-Tracking-Skript und klicke auf Konfigurieren.​

Von hier nimmst du einfach die ID, die dir das Skript gibt

Diese musst du dann als dataSourceId in allen Events verwenden, die du sendest.

2. Das Klar-Skript in deiner serverseitigen Umgebung einbauen

Alle Events sollten per POST-Request an „https://september.durchsichtig.xyz/server-side-event/EVENT_NAME" gesendet werden. Die IP des Kunden muss über den Header „x-serverside-ip" übergeben werden.

Implementierungs-Anforderungen:

HTTP-Header

- Content-Type: application/json
- x-serverside-ip: Customer's IP address (required for server-side tracking)

Endpunkt

POST https://september.durchsichtig.xyz/server-side-event/{EVENT_NAME}

Wobei {EVENT_NAME} dem Feld „eventName" im Payload entspricht.

Fehlerbehandlung

Der Server gibt bei fehlerhaften Requests einen Statuscode 400 mit einem „X-Klar-Failure"-Header zurück:

- „read-headers": Fehlende oder ungültige Header

- „get-body": Falsches Format oder fehlender Request-Body

- „invalid-json": Ungültiges JSON-Format im Request-Body

Hinweise

1. septemberId: Muss eine 16-stellige nanoid sein, die für konsistentes User-Tracking über Sessions hinweg genutzt wird. (konstant für den Nutzer, idealerweise client-seitig in einem Cookie gespeichert; eine nanoid lässt sich z. B. mit Bibliotheken wie nanoid erzeugen.)

2. Timestamps: Alle `createdAt`-Felder müssen im ISO-8601-Format sein

3. Optionale Felder: Mit `?` markierte Felder sind optional, aber empfohlen, wenn verfügbar

Für die korrekte Implementierung musst du verschiedene Events konfigurieren:
​

Zu implementierende Events

  • VisitEvent

  • ProductViewedEvent

  • AddToCartEvent

  • RemoveFromCartEvent

  • UpdateCheckoutEvent

  • PaymentInfoEvent

  • ShippingInfoEvent

  • OrderEvent

  • UpdateABGroupEvent

  • CustomConversionEvent

Alle diese Events werden ausgelöst, indem ein CustomEvent auf dem document veröffentlicht wird. Sobald das Event erfolgreich veröffentlicht wurde, wird ein Fetch-Event mit dem Payload ausgelöst.

Basis-Event-Schema:

interface BaseEvent {
  eventName: string;           // Required - The specific event type
  createdAt: string;          // Required - ISO 8601 timestamp
  pageUrl: string;            // Required - Current page URL
  septemberId: string;        // Required - 16 character nanoid for user tracking
  googleAnalyticsId: string;  // Required - Value of the _ga cookie
  facebookId: string;         // Required - Value of the _fbp cookie
  dataSourceId: string;       // Required - DataSource ID from Klar pixel configuration
  referrer: string;           // Required - Previous page URL
  hasGivenConsent: boolean;   // Required - User consent status for tracking
  customerId: string;         // Required - Customer identifier
  screen: string;             // Required - Screen resolution (e.g., "1920x1080")
  shopSystem: string;         // Required - E-commerce platform (e.g., "shopify")
}

2.1 VisitEvent

Wird bei jedem Seitenbesuch auf der gesamten Website ausgelöst.

interface VisitEvent extends BaseEvent {
  eventName: "VisitEvent";
  pageTitle: string;          // Required - Title of the current page
}

Beispiel:

curl -X POST https://september.durchsichtig.xyz/server-side-event/VisitEvent \
  -H "Content-Type: application/json" \
  -H "x-serverside-ip: 192.168.1.100" \
  -d '{
    "eventName": "VisitEvent",
    "pageTitle": "Best Product of the World",
    "createdAt": "2024-04-11T11:11:15.783Z",
    "pageUrl": "https://getklar.com/dogs",
    "septemberId": "a1b2c3d4e5f6g7h8",
    "googleAnalyticsId": "GA1.2.1234567890.1234567890",
    "facebookId": "fb.1.1234567890.1234567890",
    "dataSourceId": "klar-shopify-pixel-01",
    "referrer": "https://google.de",
    "hasGivenConsent": true,
    "customerId": "cust_123456",
    "screen": "1920x1200",
    "shopSystem": "shopify"
  }'

2.2 ProductViewEvent

Wird ausgelöst, wenn ein Kunde eine Produktseite ansieht.

interface ProductViewedEvent extends BaseEvent {
  eventName: "ProductViewedEvent";
  productId: string;          // Required - Either productId OR productSku must be provided
  productSku: string;         // Required - Either productId OR productSku must be provided
  productTitle?: string;      // Optional - Product name/title
}

Beispiel:

curl -X POST https://september.durchsichtig.xyz/server-side-event/ProductViewedEvent \
  -H "Content-Type: application/json" \
  -H "x-serverside-ip: 192.168.1.100" \
  -d '{
    "eventName": "ProductViewedEvent",
    "productId": "46667923652922",
    "productTitle": "Best Dog TransportBOX",
    "productSku": "F0011",
    "createdAt": "2024-04-11T11:22:43.984Z",
    "pageUrl": "https://getklar.com/dogs/transport",
    "septemberId": "a1b2c3d4e5f6g7h8",
    "googleAnalyticsId": "GA1.2.1234567890.1234567890",
    "facebookId": "fb.1.1234567890.1234567890",
    "dataSourceId": "klar-shopify-pixel-01",
    "referrer": "https://getklar.com/dogs",
    "hasGivenConsent": true,
    "customerId": "cust_123456",
    "screen": "1920x1200",
    "shopSystem": "shopify"
  }'

2.3 AddToCartEvent

Wird ausgelöst, wenn ein Produkt in den Warenkorb gelegt wird.

interface AddToCartEvent extends BaseEvent {
  eventName: "AddToCartEvent";
  productId: string;          // Required - Either productId OR productSku must be provided
  productSku: string;         // Required - Either productId OR productSku must be provided
  productTitle?: string;      // Optional - Product name
  productQuantity: number;    // Required - Quantity added
  productPrice?: number;      // Optional - Product price
}

Beispiel:

curl -X POST https://september.durchsichtig.xyz/server-side-event/AddToCartEvent \
  -H "Content-Type: application/json" \
  -H "x-serverside-ip: 192.168.1.100" \
  -d '{
    "eventName": "AddToCartEvent",
    "productId": "46667923652922",
    "productSku": "F0011",
    "productTitle": "Best Dog TransportBOX",
    "createdAt": "2024-04-11T11:27:06.262Z",
    "pageUrl": "https://getklar.com/dogs/transport",
    "septemberId": "a1b2c3d4e5f6g7h8",
    "googleAnalyticsId": "GA1.2.1234567890.1234567890",
    "facebookId": "fb.1.1234567890.1234567890",
    "shopSystem": "shopify",
    "dataSourceId": "klar-shopify-pixel-01",
    "referrer": "https://getklar.com/dogs",
    "hasGivenConsent": true,
    "customerId": "cust_987654321",
    "screen": "3840x2160"
  }'

2.4 RemoveFromCartEvent

Wird ausgelöst, wenn ein Produkt aus dem Warenkorb entfernt wird.

interface RemoveFromCartEvent extends BaseEvent {
  eventName: "RemoveFromCartEvent";
  productId: string;          // Required - Either productId OR productSku must be provided
  productSku: string;         // Required - Either productId OR productSku must be provided
  productTitle?: string;      // Optional - Product name
  productQuantity: number;    // Required - Quantity removed
  productPrice?: number;      // Optional - Product price
}

Beispiel:

curl -X POST https://september.durchsichtig.xyz/server-side-event/RemoveFromCartEvent \
  -H "Content-Type: application/json" \
  -H "x-serverside-ip: 192.168.1.100" \
  -d '{
    "eventName": "RemoveFromCartEvent",
    "productId": "46667923652922",
    "productSku": "F0011",
    "productTitle": "Best Dog TransportBOX",
    "productQuantity": 1,
    "productPrice": 8.5,
    "createdAt": "2024-04-11T11:35:45.000Z",
    "pageUrl": "https://getklar.com/cart",
    "septemberId": "m1n2b3v4c5x6z7l8",
    "googleAnalyticsId": "GA1.2.3456789012.3456789012",
    "facebookId": "fb.1.3456789012.3456789012",
    "shopSystem": "shopify",
    "dataSourceId": "klar-shopify-pixel-01",
    "referrer": "https://getklar.com/product/f0011",
    "hasGivenConsent": true,
    "customerId": "cust_2468101214",
    "screen": "2560x1440"
  }'

2.5 UpdateCheckoutEvent

Wird ausgelöst, wenn ein Kunde den Checkout-Bereich deines Shops betritt.

interface UpdateCheckoutEvent extends BaseEvent {
  eventName: "UpdateCheckoutEvent";
  checkoutId: string;         // Required - Associated checkout session
  cartId?: string;            // Optional - Shopping cart identifier
}

Beispiel:

curl -X POST https://september.durchsichtig.xyz/server-side-event/UpdateCheckoutEvent \
  -H "Content-Type: application/json" \
  -H "x-serverside-ip: 192.168.1.100" \
  -d '{
    "eventName": "UpdateCheckoutEvent",
    "checkoutId": "7297e4e6e7c95f2e8c3da4c66d60f7e7",
    "createdAt": "2024-04-11T11:29:32.929Z",
    "pageUrl": "https://getklar.com/checkouts/cn/Z2NwLWV1cm9wZS13ZkVKSz",
    "septemberId": "a1b2c3d4e5f6g7h8",
    "googleAnalyticsId": "GA1.2.1234567890.1234567890",
    "facebookId": "fb.1.1234567890.1234567890",
    "dataSourceId": "klar-shopify-pixel-01",
    "referrer": "https://getklar.com/dogs/transport",
    "hasGivenConsent": true,
    "customerId": "cust_123456",
    "screen": "3840x2160",
    "shopSystem": "shopify"
  }'

2.6 PaymentInfoEvent

Wird ausgelöst, wenn während des Checkouts Zahlungsinformationen eingegeben werden.

interface PaymentInfoEvent extends BaseEvent {
  eventName: "PaymentInfoEvent";
  checkoutId: string;         // Required - Associated checkout session
}

Beispiel:

curl -X POST https://september.durchsichtig.xyz/server-side-event/PaymentInfoEvent \
  -H "Content-Type: application/json" \
  -H "x-serverside-ip: 192.168.1.100" \
  -d '{
    "eventName": "PaymentInfoEvent",
    "checkoutId": "chk_def456",
    "createdAt": "2024-04-11T11:30:10.512Z",
    "pageUrl": "https://getklar.com/checkout/payment",
    "septemberId": "z9y8x7w6v5u4t3s2",
    "googleAnalyticsId": "GA1.2.2345678901.2345678901",
    "facebookId": "fb.1.2345678901.2345678901",
    "shopSystem": "shopify",
    "dataSourceId": "klar-shopify-pixel-01",
    "referrer": "https://getklar.com/checkout/shipping",
    "hasGivenConsent": true,
    "customerId": "cust_123456789",
    "screen": "1920x1080"
  }'

2.7 ShippingInfoEvent

Wird ausgelöst, wenn während des Checkouts Versandinformationen eingegeben werden.

interface ShippingInfoEvent extends BaseEvent {
  eventName: "ShippingInfoEvent";
  checkoutId: string;         // Required - Associated checkout session
}

Beispiel:

curl -X POST https://september.durchsichtig.xyz/server-side-event/ShippingInfoEvent \
  -H "Content-Type: application/json" \
  -H "x-serverside-ip: 192.168.1.100" \
  -d '{
    "eventName": "ShippingInfoEvent",
    "checkoutId": "chk_jkl012",
    "createdAt": "2024-04-11T11:40:00.000Z",
    "pageUrl": "https://getklar.com/checkout/shipping",
    "septemberId": "o9p8q7r6s5t4u3v2",
    "googleAnalyticsId": "GA1.2.4567890123.4567890123",
    "facebookId": "fb.1.4567890123.4567890123",
    "shopSystem": "shopify",
    "dataSourceId": "klar-shopify-pixel-01",
    "referrer": "https://getklar.com/checkout/cart",
    "hasGivenConsent": true,
    "customerId": "cust_135791113",
    "screen": "1280x800"
  }'

2.8 OrderEvent

Wird auf der „Checkout Finish"-Seite ausgelöst, wenn die Bestellung vom Kunden abgeschickt wurde.

interface CheckoutItem {
  productId?: string;         // Optional - Product identifier (either productId or productSku required if item present)
  productSku?: string;        // Optional - Product SKU (either productId or productSku required if item present)
  productTitle?: string;      // Optional - Product name
  productQuantity?: number;   // Optional - Quantity ordered
  productPrice?: number;      // Optional - Product price
}

interface OrderEvent extends BaseEvent {
  eventName: "OrderEvent";
  orderId: string;            // Required - Unique order identifier
  checkoutId: string;         // Required - Associated checkout session
  customerId?: string;        // Optional - Customer identifier
  cartId?: string;            // Optional - Shopping cart identifier
  checkoutItems?: CheckoutItem[]; // Optional - Array of purchased items
  shippingTotal?: number;     // Optional - Shipping cost
  checkoutTax?: number;       // Optional - Tax amount
  checkoutTotal?: number;     // Optional - Total order amount
}

Beispiel:

curl -X POST https://september.durchsichtig.xyz/server-side-event/OrderEvent \
  -H "Content-Type: application/json" \
  -H "x-serverside-ip: 192.168.1.100" \
  -d '{
    "eventName": "OrderEvent",
    "orderId": "5916248703148",
    "checkoutId": "7282c2584c907ddcd9f17dd01f374137",
    "customerId": "cust_123456",
    "checkoutItems": [{
      "productId": "42897447452844",
      "productSku": "12345",
      "productTitle": "Dog BOX",
      "productQuantity": 1,
      "productPrice": 0
    }],
    "shippingTotal": 0,
    "checkoutTax": 0,
    "checkoutTotal": 629.95,
    "createdAt": "2024-04-11T11:35:18.474Z",
    "pageUrl": "https://getklar.com/checkouts/cn/Z2NwLWV1cm9wZS13ZkVKSz",
    "septemberId": "a1b2c3d4e5f6g7h8",
    "googleAnalyticsId": "GA1.2.1234567890.1234567890",
    "facebookId": "fb.1.1234567890.1234567890",
    "shopSystem": "shopify",
    "dataSourceId": "klar-shopify-pixel-01",
    "referrer": "https://getklar.com/dogs/transport",
    "hasGivenConsent": true,
    "screen": "3840x2160"
  }'

2.9 UpdateABGroupEvent

Wird ausgelöst, wenn ein Nutzer einer A/B-Testgruppe zugewiesen wird.

interface UpdateABGroupEvent extends BaseEvent {
  eventName: "UpdateABGroupEvent";
  projectName?: string;       // Optional - A/B test project name
  variantName: string;        // Required - Assigned variant (e.g., "VariantA", "VariantB")
  experimentName: string;     // Required - Experiment identifier
}

Beispiel:

curl -X POST https://september.durchsichtig.xyz/server-side-event/UpdateABGroupEvent \
  -H "Content-Type: application/json" \
  -H "x-serverside-ip: 192.168.1.100" \
  -d '{
    "eventName": "UpdateABGroupEvent",
    "projectName": "HomepageRedesign",
    "variantName": "VariantB",
    "experimentName": "Spring2024Experiment",
    "createdAt": "2024-04-11T11:50:00.000Z",
    "pageUrl": "https://getklar.com/landing/ab-test",
    "septemberId": "r5t6y7u8i9o0p1q2",
    "googleAnalyticsId": "GA1.2.5678901234.5678901234",
    "facebookId": "fb.1.5678901234.5678901234",
    "shopSystem": "shopify",
    "dataSourceId": "klar-shopify-pixel-01",
    "referrer": "https://getklar.com/home",
    "hasGivenConsent": true,
    "customerId": "cust_1112131415",
    "screen": "1920x1080"
  }'

2.10 CustomConversionEvent

Custom-Conversion-Events in KLAR einrichten

  1. Gehe zum Store-Konfigurator → Öffne die Store-Einstellungen.
    ​

  2. Definiere deine Custom Conversions → Weise einer ID einen aussagekräftigen Namen zu (z. B. 1 = Add to Cart), damit sie im Frontend korrekt erscheinen.

    Die Event-ID ist die, die du als customConversionId in deinem Payload setzen musst.
    ​
    ​


​
Wird für das Custom-Conversion-Tracking mit spezifischen Werten ausgelöst.

interface CustomConversionEvent extends BaseEvent {
  eventName: "CustomConversionEvent";
  customConversionId: number; // Required - Custom conversion identifier
  customConversionValue?: number; // Optional - Conversion value
}

Beispiel:

curl -X POST https://september.durchsichtig.xyz/server-side-event/CustomConversionEvent \
  -H "Content-Type: application/json" \
  -H "x-serverside-ip: 192.168.1.100" \
  -d '{
    "eventName": "CustomConversionEvent",
    "customConversionId": 101,
    "customConversionValue": 49.99,
    "createdAt": "2024-04-11T12:00:00.000Z",
    "pageUrl": "https://getklar.com/thank-you",
    "septemberId": "g7h8j9k0l1m2n3b4",
    "googleAnalyticsId": "GA1.2.6789012345.6789012345",
    "facebookId": "fb.1.6789012345.6789012345",
    "shopSystem": "shopify",
    "dataSourceId": "klar-shopify-pixel-01",
    "referrer": "https://getklar.com/checkout/complete",
    "hasGivenConsent": true,
    "customerId": "cust_1617181920",
    "screen": "1440x900"
  }'

Troubleshooting

Wenn ein Request fehlerhaft ist, gibt der Server einen Statuscode 400 zusammen mit einem „X-Klar-Failure"-Header zurück. Der Header-Wert gibt den konkreten Fehlertyp an:
​

  • „read-headers": Fehlende oder ungültige Header im Request

  • „get-body": Falsches Format oder fehlender Request-Body

  • „invalid-json": Body wurde übergeben, enthält aber ungültiges JSON-Format

Falls dir unbekannte Fehler oder Bugs begegnen, kontaktiere bitte Pascal von unserem Kundensupport.

3. Datenschutz-Snippets hinzufügen

Achte darauf, unser Datenschutz-Snippet in deine Datenschutzerklärung aufzunehmen, um deine Kunden über die Nutzung des Klar-Tracking-Pixels zu informieren. Ein deutsches und ein englisches Snippet findest du in der Klar-Pixel-Datenquelle unterhalb des Tracking-Skripts in einem eingeklappten Abschnitt namens „Data Protection Snippet".
​

4. Klar-URL-Parameter implementieren

Damit Conversions und Kosten so genau wie möglich zugeordnet werden können, musst du die vordefinierten Klar-Tracking-Codes in deinen Werbekonten einbauen.

Hier findest du Anleitungen dazu für jeden Marketing-Kanal:

🔵 URL-Parameter für Meta Ads

🟢 URL-Parameter für Google Ads

URL-Parameter für TikTok Ads

🔴 URL-Parameter für Pinterest Ads

✉️ URL-Parameter für Klaviyo

😍 URL-Parameter für Influencer/Affiliates

🟣 URL-Parameter für Taboola

🟠 URL-Parameter für Outbrain

URL-Parameter für Bing

🎨 URL-Parameter für alle anderen Kanäle

Was passiert als Nächstes?

Ab jetzt können wir Besucher auf deiner Seite und ihre Kaufaktivität tracken, um unser Attributions-Reporting zu speisen.

Ab morgen siehst du Daten in deinen Reports – allerdings erst ab dem Zeitpunkt, zu dem du das Skript hinzugefügt hast.

Verwandte Artikel
Hat dies deine Frage beantwortet?