API DocsKnowledge BaseSystem StatusContact SupportContact Sales
Knowledge Base

Proxying events through your own server

Overview

You can proxy Kevel impression and custom event pixels through your own server. This allows you to:

  • Control the domains used for ad serving
  • Customize the format of tracking pixels
  • Minimize reporting discrepancies due to Ad Blockers

Understanding the Event Pixel

A Kevel tracking pixel consists of:

  • i.gif for impressions, or e.gif for custom events: the dimensionless pixel that records the event when fired.
  • e=: A base64 encoded shim unique to the event.
  • s=: A signature value to verify that the encoded shim is legitimate.

A complete pixel URL looks like:

https://e-1234.adzerk.net/i.gif?e=eyJhdiI6NDM3LCJhdCI6NSwiY&s=ujZhktar1g1emAP
📘

The number in e-1234.adzerk.net is your account's network ID.

In a Decision API response, the impression pixel URL is returned as the impressionUrl parameter. Custom event pixels are returned as the url of each entry in the events array, keyed by the event's id. Both are proxied the same way.

To record an event, a browser or script must GET its URL.

{
  "adId": 111,
  "creativeId": 222,
  "flightId": 333,
  "campaignId": 444,
  "clickUrl": "https://e-1234.adzerk.net/r?...",
  "impressionUrl": "https://e-1234.adzerk.net/i.gif?...",
  "events": [
        { "id": 12,
          "url": "https://e-1234.adzerk.net/e.gif?..."
        },
        { "id": 13,
          "url": "https://e-1234.adzerk.net/e.gif?..."
        },
        { "id": 14,
          "url": "https://e-1234.adzerk.net/e.gif?..."
        }
  ]
  ...
}

Creating a Proxy Server

A server for proxying events must be able to:

  • Ingest the impressionUrl, or the url of an entry in the events array, from a Decision API response
  • Create a new URL using the domain of your web property
  • GET the Kevel URL using shim and signature data from the "native" URL

The server that renders an ad on a page then renders the new "native" URL.

Finally, when a user's browser hits the new URL, the proxy server will count the event using the Kevel URL format.

The example below uses an impression. Custom events work identically, using the url of the relevant entry in the events array in place of impressionUrl.

  • When a user views a page, KevelCustomer.com makes a server-to-server Decision request to get an ad
  • As part of the process of rendering an ad, the proxy server ingests the impressionUrl from the Decision response and creates a new impression pixel that looks like this (for example): https://KevelCustomer.com/e=value/s=value
  • The server writes the new impression URL to the page with the ad contents
  • A user's browser GETs the new impression pixel
  • The proxy server uses the e=value and s=value passed on the new impression pixel to create a pixel in the Kevel format
  • The proxy server hits the Kevel impression pixel. Kevel counts the impression

Updated 3 days ago