Statt ein JS-Tracking-Skript auszuspielen, sendest du Events direkt per HTTP-POST-Requests an den serverseitigen Endpunkt von Klar. Du musst trotzdem zuerst eine Klar-Pixel-Datenquelle erstellen, um deine dataSourceId zu erhalten.

Schritt 1: Die Klar-Pixel-Datenquelle hinzufügen

Wenn du mehrere Domains hast, erstelle für jeden Store eine eigene Pixel-Datenquelle.

Gehe zu Store-Konfigurator → Datenquellen und klicke auf Neue Datenquelle hinzufügen
Wähle die Datenquelle Klar Pixel
Gib einen Namen ein – z. B. „Klar Tracking Script"
Wähle Basic-Tracking und klicke auf Configure

Warum Basic? Beim serverseitigen Tracking spielst du kein JavaScript-Tag aus, das unter deiner eigenen Subdomain läuft – du sendest Events direkt von deinem Server. Domain-validiertes Tracking ist nur für client-seitige Skripte relevant.

Kopiere die Datasource-ID aus dem Konfigurationsbildschirm – du brauchst sie als Feld dataSourceId in jedem Event-Payload

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

Schritt 2: Das Klar-Skript in den serverseitigen Events implementieren

Endpunkt

Alle Events werden als POST-Requests gesendet an:

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

Wobei {EVENT_NAME} dem Feld eventName im Payload entspricht.

Erforderliche Header

Content-Type: application/json

x-serverside-ip: <IP-Adresse des Kunden>

Der Header x-serverside-ip ist erforderlich, damit Klar die IP-Adresse für das Session-Stitching und die Identitätsauflösung nutzen kann – so, wie ein client-seitiges Skript sie automatisch erfassen würde.

Zentrales Feld: septemberId

Jedes Event benötigt eine septemberId – eine 16-stellige nanoid, die den Nutzer über Sessions hinweg identifiziert. Sie muss für alle Events desselben Nutzers denselben Wert haben, sollte also einmal generiert und client-seitig gespeichert werden (z. B. in einem First-Party-Cookie). Du kannst eine mit einer Bibliothek wie nanoid erzeugen.

Fehlerbehandlung

Wenn ein Request fehlerhaft ist, gibt der Server 400 mit einem X-Klar-Failure-Header zurück:

Header-Wert	Bedeutung
`read-headers`	Fehlende oder ungültige Header
`get-body`	Falsches Format oder fehlender Request-Body
`invalid-json`	Request-Body ist kein gültiges JSON

Basis-Event-Schema

Alle Events erweitern dieses Basis-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 (see above)
  googleAnalyticsId: string;   // Required — value of the _ga cookie
  facebookId: string;          // Required — value of the _fbp cookie
  dataSourceId: string;        // Required — datasource ID from Step 1
  referrer: string;            // Required — previous page URL
  hasGivenConsent: boolean;    // Required — user consent status
  customerId: string;          // Required — customer identifier
  screen: string;              // Required — screen resolution (e.g. "1920x1080")
  shopSystem: string;          // Required — e-commerce platform (e.g. "shopify")
}

Alle createdAt-Felder müssen im ISO-8601-Format sein. Mit ? markierte Felder in den Event-Schemas unten sind optional, aber empfohlen, wenn verfügbar.

2.1 VisitEvent

Löse es bei jedem Seitenbesuch aus.

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 ProductViewedEvent

Löse es aus, 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

}

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

Löse es aus, 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

Löse es aus, 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

Löse es aus, wenn ein Kunde den Checkout betritt.

interface UpdateCheckoutEvent extends BaseEvent {

eventName: "UpdateCheckoutEvent";

checkoutId: string; // Required — checkout session identifier

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

Löse es aus, wenn im Checkout Zahlungsinformationen eingegeben werden.

interface PaymentInfoEvent extends BaseEvent {

eventName: "PaymentInfoEvent";

checkoutId: string; // Required — checkout session identifier

}

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

Löse es aus, wenn im Checkout Versandinformationen eingegeben werden.

interface ShippingInfoEvent extends BaseEvent {

eventName: "ShippingInfoEvent";

checkoutId: string; // Required — checkout session identifier

}

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

Löse es auf der Bestellbestätigungsseite aus, nachdem der Kauf abgeschlossen ist.

interface CheckoutItem {

productId?: string; // Optional — either productId or productSku required if item present

productSku?: string; // Optional — 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 — checkout session identifier

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

Löse es aus, 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

Bevor du dieses Event auslöst, richte deine Custom Conversions in Klar ein:

Gehe zu Store-Konfigurator → Store-Einstellungen
Definiere deine Custom Conversions – weise einer ID einen aussagekräftigen Namen zu (z. B. 1 = Add to Cart). Diese ID ist die customConversionId, die du im Event-Payload übergibst.

interface CustomConversionEvent extends BaseEvent {

eventName: "CustomConversionEvent";

customConversionId: number; // Required — ID defined in Store Settings

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"
  }'

Schritt 3: Das Datenschutz-Snippet hinzufügen

Füge Klars Datenschutz-Snippet zur Datenschutzerklärung deines Shops hinzu. Du findest es in den Einstellungen der Klar-Pixel-Datenquelle, unterhalb des Tracking-Skripts, im eingeklappten Abschnitt „Data Protection Snippet" – auf Deutsch und Englisch verfügbar.

Schritt 4: Die Klar-URL-Parameter in deinen Werbekonten einrichten

Damit Conversions und Kosten kanalübergreifend genau zugeordnet werden, füge Klars Tracking-Parameter zu den URLs deiner Werbekonten hinzu:

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?

Klar beginnt sofort, Besucher und Kaufaktivität zu tracken. Attributionsdaten erscheinen ab dem nächsten Tag in deinen Reports – beachte, dass sie erst ab dem Zeitpunkt verfügbar sind, ab dem die Events ausgelöst wurden, nicht rückwirkend.

Falls Probleme auftreten, melde dich über den In-App-Chat.

Verwandte Artikel

Klar Pixel über serverseitiges Tracking einrichten

Schritt 1: Die Klar-Pixel-Datenquelle hinzufügen

Schritt 2: Das Klar-Skript in den serverseitigen Events implementieren

Endpunkt

Erforderliche Header

Zentrales Feld: septemberId

Fehlerbehandlung

Basis-Event-Schema

2.1 VisitEvent

2.2 ProductViewedEvent

2.3 AddToCartEvent

2.4 RemoveFromCartEvent

2.5 UpdateCheckoutEvent

2.6 PaymentInfoEvent

2.7 ShippingInfoEvent

2.8 OrderEvent

2.9 UpdateABGroupEvent

2.10 CustomConversionEvent

Schritt 3: Das Datenschutz-Snippet hinzufügen

Schritt 4: Die Klar-URL-Parameter in deinen Werbekonten einrichten

Was passiert als Nächstes?