API DocsKnowledge BaseSystem StatusContact SupportContact Sales
Knowledge Base

Proxying Impressions Through Your Server

Suggest Edits

🚧

Proxying impressions is only available through the Decision API

Overview

You can proxy Kevel impression events through your own server. This allows you to:

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

🚧

These proxying instructions are applicable to Custom Events too - like tracking Likes, Social Shares, etc. You'll want to use the url found in the events object of the Response.

Understanding the Impression Pixel

An Kevel impression pixel consists of:

  • i.gif: The dimensionless pixel that counts the impression when fired.
  • e=: A base64 encoded shim unique to the impression.
  • 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.

To record an impression, a browser or script must GET the impression 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 impressions must be able to:

  • Ingest the ImpressionUrl from a Decision API response
  • Create a new impression URL using the domain of your web property
  • GET a Kevel impression URL using shim and signature data from the "native" URL

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

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

Here's an example of how the process works:

  • 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): http://AdzerkCustomer.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 2 months ago