Setting up the Klar Pixel via serverside tracking

How to set up the Klar tracking pixel by validating your domain, implementing the tracking script, and adjusting UTM parameters.

Do you want to start using the attribution report in Klar? Great choice 🎉

To power our fully integrated attribution solution, you need to configure the Klar Pixel datasource in Klar and implement a tracking script on your site. This should only take a few minutes.

1. Adding the Klar Pixel Datasource

If you have multiple domains, you should create a unique Pixel datasource for each of these stores.

Go to your Store Configurator page in Klar and click Connect Data Source

Select the Datasource Klar Pixel

Enter a name for the datasource - eg. Klar Tracking Script
Configure a basic tracking script and press configure.

2. Implementing the Klar script in your serverside environment

All Events should be sent to "https://september.durchsichtig.xyz/server-side-event/EVENT_NAME" with a POST request. The IP of the Customer has to be provided with the header "x-serverside-ip".

Implementation Requirements:

HTTP Headers

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

Endpoint

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

Where {EVENT_NAME} matches the "eventName" field in the payload.

Error Handling

The server returns a 400 status code with an "X-Klar-Failure" header for incorrect requests:

- "read-headers": Missing or invalid headers

- "get-body": Wrong format or missing request body

- "invalid-json": Invalid JSON format in request body

Notes

1. septemberId: Must be a 16-character nanoid used for consistent user tracking across sessions. (constant for the user, ideally persisted client-side in a cookie, nanoid can be generated for example with libraries like nanoid.)

2. Timestamps: All `createdAt` fields must be in ISO 8601 format

3. Optional Fields: Fields marked with `?` are optional but recommended when available

For the correct implementation you have to configure different events:

Events to implement

VisitEvent
ProductViewedEvent
AddToCartEvent
RemoveFromCartEvent
UpdateCheckoutEvent
PaymentInfoEvent
ShippingInfoEvent
OrderEvent
UpdateABGroupEvent
CustomConversionEvent

All these events are emitted by publishing a CustomEvent on the document. When the event has been successfully published a fetch event with the payload will be triggered.

Base 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

Triggered on every page visit across the website.

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

Example:

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

Triggered when a customer views a product page.

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
}

Example:

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

Triggered when a product is added to the shopping cart.

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
}

Example:

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

Triggered when a product is removed from the shopping cart.

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
}

Example:

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

Triggered when a customer enters the checkout area of your shop.

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

Example:

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

Triggered when payment information is entered during checkout.

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

Example:

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

Triggered when shipping information is entered during checkout.

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

Example:

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

Triggered on the "Checkout Finish" page, when the order has been placed by the customer.

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
}

Example:

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

Triggered when a user is assigned to an A/B testing group.

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
}

Example:

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

Setting Up Custom Conversion Events in KLAR

Navigate to Store Configurator → Open Store Settings.
Define Your Custom Conversions → Assign an ID to a descriptive name (e.g., 1 = Add to Cart), so they appear correctly in the frontend.
The Event ID is the one you need to set as customConversionId in your payload.

Triggered for custom conversion tracking with specific values.

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

Example:

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

When a request is incorrect, the server returns a 400 status code along with an "X-Klar-Failure" header. The header value indicates the specific error type:

"read-headers": Missing or invalid headers in the request
"get-body": Wrong format or missing request body
"invalid-json": Body was provided but contains invalid JSON format

In case you encounter any unknown errors or bugs, please contact Pascal our customer support.

3. Adding Data Privacy Snippets

Make sure to add our data privacy snippet in your privacy policy to inform your customers about the usage of Klar’s tracking pixel. You can find a German and English snippet in the Klar Pixel data source under the tracking script in a collapsed section called “Data Protection Snippet”.

4.Implementing Klar URL Parameters

To ensure that conversions and costs can be matched as accurately as possible, you need to implement the pre-defined Klar tracking codes in your ad accounts.

Here are guides on how to do that for each marketing channel:

🔵 URL Parameters for Meta Ads

🟢 URL Parameters for Google Ads

URL Parameters for TikTok Ads

🔴 URL Parameters for Pinterest Ads

✉️ URL Parameters for Klaviyo

😍 URL Parameters for Influencers/Affiliates

🟣 URL Parameters for Taboola

🟠 URL Parameters for Outbrain

URL Parameters for Bing

🎨 URL Parameters for All Other Channels