Tracking

Getting tracking right is a fundamental pre-requisite for Kleio to optimize auctions and thereby your ad revenue.

Three events that can tracked: impressions, clicks, and conversions.

Impressions

The definition of an impression is fairly straightforward. Think of it as an ad having been shown to a user and the user having had the chance to interact with it.

You can either track impressions directly when you render the ad or sponsored product, or if you have a more sophisticated setup that accounts for viewable impressions (i.e. the ad was seen and visible on screen) then you might want to define this to be viewable impressions.

By default, an impression is tracked for each ad that is returned from an auction.

Clicks

You can think of a click as a user having interacted with the ad.

Conversions

The ad server tries to optimize for conversion. For example, when running an auction it looks at the bids associated with each ad in the context of how well they convert to maximize the expected revenue your system generates.

How you think of conversion depends on your use case: A conversion could be that an ad has been shown (this would be a typical "pay per impression" type setup), it could be that a user that saw the ad clicked on it (this would be a "pay per click" type setup), or it could be entirely custom to your application, for example, the user adding the product to their cart, or subsequently paying for it.

In most typical setups, you would never have to manually track a conversion. When creating an ad you can specify whether an impression or a click should constitute a conversion, which would take care of the conversion tracking for you. If however your definition of what a conversion is differs from impressions or clicks, you have to take care to track it yourself.

Why tracking is important

Getting tracking right directly influences the behavior of the auction system. Kleio tracks the ratio of conversions to impressions for each ad and product. Based on this ratio we calculate an estimated revenue per impressions for each ad, which in turn is what is used during the auction. This allows a well-performing ad with a low maximum bid to compete on an even footing with a poorly performing ad with a high maximum bid, and in turn, is designed to optimize the amount of revenue you might derive from the system. This mechanism only works as long as you ensure the tracking is correct.

Tracking code

Ads that are returned by the auction API endpoint include a tracking_code. The code itself encodes sufficient metadata for Kleio to later reconstruct which ad and which auction the code belongs to, and at what price the auction was won.

When using the tracking endpoints described below, the tracking_code is what should be passed in as the :tracking_code-property.

Properties

Track an impression

curl -X POST \
  https://example.com/api/v1/track/impression/ueRPvrlZ2KnHRHN5vN0VIfnd0maDHONIqH8pAxXZjCkAWbBfPBOXQTWeMs3OX_F3NpyG7Mf1q0aSnhEbl6r0KKIAAAAAAAAAZQAAAABlTiSn

Track a click

curl -X POST \
  https://example.com/api/v1/track/click/ueRPvrlZ2KnHRHN5vN0VIfnd0maDHONIqH8pAxXZjCkAWbBfPBOXQTWeMs3OX_F3NpyG7Mf1q0aSnhEbl6r0KKIAAAAAAAAAZQAAAABlTiSn

Track a conversion

curl -X POST \
  https://example.com/api/v1/track/conversion/ueRPvrlZ2KnHRHN5vN0VIfnd0maDHONIqH8pAxXZjCkAWbBfPBOXQTWeMs3OX_F3NpyG7Mf1q0aSnhEbl6r0KKIAAAAAAAAAZQAAAABlTiSn