> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kontext.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Advertiser pixel

> Track conversions and custom events on your website and attribute them to clicks on your Kontext ads.

The Kontext pixel is a small JavaScript tag for advertisers. Install it on your website, fire an event when something you care about happens, such as a purchase or a sign-up, and we connect that event to the ad click that brought the visitor to you.

Before you start, ask your Kontext contact for your **pixel token**.

## Install the pixel

Paste this snippet into the `<head>` of every page where you want to track events, and replace `YOUR_PIXEL_TOKEN` with your token. You can also add it through a tag manager, as a custom HTML tag that runs on every page.

```html theme={null}
<!-- Kontext pixel -->
<script>
  !function(k,e){if(k.kontext)return;var f=k.kontext=function(){f.q.push(arguments)};
  f.q=[];f.l=+new Date;var s=e.createElement('script');s.async=1;
  s.src='https://server.megabrain.co/pixel.js';
  var t=e.getElementsByTagName('script')[0];t.parentNode.insertBefore(s,t)}(window,document);
  kontext('init', 'YOUR_PIXEL_TOKEN');
  kontext('track', 'PageView');
</script>
```

The `PageView` line is what records the page view: the pixel doesn't track anything on its own. Calls made before the script finishes loading are queued and sent once it's ready.

## Track events

Call `kontext('track', ...)` from your page when the event happens:

```js theme={null}
kontext('track', 'Purchase', { value: 9.99, currency: 'USD', order_id: 'ORDER-123' });
kontext('track', 'Lead');
kontext('track', 'TicketSelected', { match: 'home-opener' });
```

| Argument | Required | Description |
| - | - | - |
| `'track'` | Yes | The command. Always this exact string. |
| Event name | Yes | Any name you choose, up to 128 characters. Names are stored as sent, so use one spelling for each event. |
| Parameters | No | An object with the fields below. |

| Parameter | Type | Description |
| - | - | - |
| `value` | Number | The monetary value in major units: `9.99` means 9.99 USD. A value sent as a string is ignored. |
| `currency` | String | An ISO 4217 code such as `USD`. |
| Anything else | Any | Stored with the event as custom data. A request can be up to 16 KB in total. |

### Single-page apps

If your site changes pages without a full reload, call `kontext('track', 'PageView')` yourself on each route change.

## How attribution works

1. When someone clicks your ad, they land on your site with a `kontext_click_id` parameter in the URL. We set this up with your campaign. Any redirect on your side must keep the parameter.
2. The pixel reads the parameter and stores it in a first-party cookie, `__kx_clk`, that lasts 7 days. A new click replaces the old one and restarts the 7 days.
3. Every event sent while the cookie exists carries that click ID, so a conversion within 7 days of the click is tied to the last click.

Events from visitors who didn't click an ad are still recorded, but as unattributed.

### Checkout on another domain

A cookie doesn't follow visitors to a different hostname, and that includes another subdomain of your site. If your checkout lives elsewhere, pass its hostname when you initialize the pixel:

```js theme={null}
kontext('init', 'YOUR_PIXEL_TOKEN', { checkoutDomain: 'checkout.example.com' });
```

The pixel then adds the click ID to links and forms that point to that hostname. Install the pixel on the checkout pages too, so it can pick the click ID up there.

## Content security policy

If your site uses a content security policy, allow our host, and allow the inline snippet the way your policy allows other inline scripts, for example with a nonce:

```
script-src https://server.megabrain.co;
connect-src https://server.megabrain.co;
```

## Check your installation

Open the page with your browser's developer tools on the **Network** tab, then fire an event. To test attribution, add `?kontext_click_id=` and a test UUID such as `01977ad2-1f45-799a-9ee7-35540aac4456` to the URL.

| Request | Response | Meaning |
| - | - | - |
| `GET /pixel.js` | `200` | The pixel loaded. |
| `POST /pixel/track` | `204` | The event was recorded. |
| `POST /pixel/track` | `400` | The event was rejected. Usually the `kontext_click_id` in the URL isn't a valid UUID. |
| `POST /pixel/track` | `401` | The pixel token is wrong. |

If a test URL had an invalid `kontext_click_id`, clear the `__kx_clk` cookie before you try again. The invalid value stays in the cookie and later events are rejected too.

## Limitations

* Attribution needs the first-party cookie, so visitors who block cookies aren't attributed.
* Attribution only works in the browser where the ad was clicked. A visitor who clicks on their phone and buys on their laptop isn't attributed.
* Ad blockers may block the pixel.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.