In addition to tracking ad impressions, clicks, and other derivatives of these parameters, BidTheatre supports tracking user defined "conversions" (also known as "actions"). These commonly indicate that site users have reached a target point in the site - a newsletter signup, a purchase order, etcetera.

Post View & Post Click conversions

When a conversion tracker is fired, the user's data profile will be analyzed for previous points of contact. Registered conversions will be shown in Campaigns / Conversions.

If the user previously has clicked an ad from the same advertiser as the conversion tracker, a post click conversion will be registered. Post click conversions are computed each hour.
If the user previously has seen, but not clicked, an ad from the the same advertiser as the conversion tracker, a post view conversion will be registered. Post view conversions are computed each hour.

Note: A conversion tracker is linked to the advertiser, not to a specific campaign. This means that all campaigns under the same advertiser will automatically track conversions. There is no need to link the script to any particular campaign unless you want to optimize for a specific conversion tracker. In that case, select the conversion tracker as the campaign's KPI to focus optimization on that particular tracker.

Expiry times

The default setting for days that can pass from the impression until the conversion for a post view conversion to be registered is 7 days.
The default setting for days that can pass from the click until the conversion for a post click conversion to be registered is 30 days.

Setting up Conversion Tracking

Create your tracker via Assets / Tracking / Conversion Trackers.

To enable conversion tracking, clients need to facilitate that the Bidtheatre tracking URL is called at the appropriate time, this is normally done by placing a tag or pixel at the site but can also be done in a server to server context, read more about the prerequisites for server to server tracking in the Server to Server-section.

Tags and tracking urls are generated via the tag-icon in the conversion tracking section of Bidtheatre Studio

Default tag

Supported formats for site includes are JavaScript (recommended), image pixel and amp pixel. The site implementation and trigger rules are normally configured by using a product like Google Tag Manager (GTM). If GTM is used select the the "Custom HTML" tag type when creating the new tag. If a custom JavaScript solution based on XMLHttpRequests is used to fire the tracking URL make sure the withCredentials property is set to true.

Config parameter conversionId and advertiserId is fixed for a given conversion tracker and should not be altered, see the section Conversion tracking parameters for a walkthrough of configurable parameters.

Server to server

If the default tag can't be used Bidtheatre also support direct calls to the conversion endpoint from a server environment. To make this work Bidtheatre will communicate an ID to the advertiser site upon ad clicks, this ID must be retrieved and stored in the user session and then included in the conversion tracking request.

To make Bidtheatre include this ID in the click redirect all that is needed is to include the macro {kuid} at a parameter of your choice in the campaign or ad click target url, i.e. https://www.bidtheatre.com?bt_id={kuid}
The site must retrieve the parameter value that holds the ID and store the ID in the user session to be able to use it when an action that should be conversion tracked occurs.

At the time of the conversion append the ID to a parameter called kuid on the Bidtheatre conversion url before making the request, i.e.

https://adsby.bidtheatre.com/action?e=892&uid=[UNIQUE_ID]&sum=[SUM]&output=pixel&gdpr=${GDPR}&gdpr_consent=${GDPR_CONSENT_30}&kuid=1897c285-dcd7-465d-84ad-97622daa8e68

Conversion tracking parameters

Besides the identifier that identifies the conversion tracker several other optional parameters can be included in the request.

Unique ID

uid is an optional parameter that associates the action with a client chosen ID. This can be used to understand what a particular action in Bidtheatre represents in the client's backend system. Any unique number-character combination is valid, but try to stay within 0-9 and A-Z. i.e. unix-timestamp or md5 on Linux/Apache/PHP, or use the guid-generator with hyphens removed on IIS/.NET.

To avoid duplication of conversion data a unique value needs to be added. Replace UNIQUE_ID with a unique client side value. If not added, Bidtheatre will add a random value server side.

If added by Bidtheatre the value will be unique and can cause duplicated conversion data.

Sum

sum is also optional, and indicates order value if the action is a sale. This can be used to reward publishers related to the order value.

KUID

Only used in conjunction with server to server integrations.

Checksum

Bidtheatre also supports the use of a checksum to ensure the authenticity of an action. The checksum is calculated by the back-end system at the advertisers site and appended to the tracker config as field chksum. The checksum is then re-calculated and verified by Bidtheatre when the action is reported.

The checksum is the SHA1-hash of the string concatenation of an action unique secret provided by Bidtheatre, the unique action id generated by the advertisers back-end system and the order value. These are provided to Bidtheatre as part of the conversion script in the uid- and sum-parameters respectively.

An implementation in Java could look something like this.

String plain = bidtheatreSecret + advertiserUniqueActionID + saleSum; 
SHA1 sha1 = SHA1.getInstance(); 
String checksum = sha1.hashData(plain.getBytes());

Custom parameters

BidTheatre also supports that the conversion script passes any parameter and corresponding value as part of the tracking url to be linked to this particular conversion. These parameters do need to be defined beforehand and is done so via the Edit parameters-link in the conversion section.

How to Check if a Conversion Tracker is Triggered

To verify if a conversion tracker is triggered, you need access to the page where the pixel is implemented or you can perform a live conversion while inspecting the site.

Inspect the Page: Right-click anywhere on the page and select Inspect
Click on the Network tab at the top of the developer tools window.
Type "action" in the search field within the Network tab.
Refresh the Page or Trigger a Conversion: Refresh the page or perform a live conversion. If the tracker is triggered, you should see a network request with the same ID as the conversion tracker in the list: