Tracking conversions on 3p sites

Overview

When a conversion happens on a site you do not control, such as an advertiser's own site, Kevel cannot observe it directly. Instead, Kevel issues a conversion ID with each click. You or the advertiser call Kevel's conversion endpoint with that ID at the point the conversion fires, and Kevel credits the ad that the ID belongs to.

Because the ID travels with the click, the advertiser can make the call from their own system without any further integration on your side.

Setting It Up

1. Add the macro ?conv=%conversionid% to the Click URL when Setting up a Creative, such as https://www.nike.com/?conv=%conversionid%. Kevel expands this into a unique conversion ID per click, giving a landing page URL like https://www.nike.com/?conv=1231242.

2. When the user clicks the ad, they arrive on the advertiser's site with conv=GUID in the URL. The advertiser reads the ID from the query string and keeps it tied to the user for the rest of the session, typically by persisting conv=GUID across their own page navigation or storing it against a logged-in user.

3. When the conversion happens, the advertiser makes a GET request to the conversion endpoint with that ID appended. Because the ID is tied to a specific ad, Kevel registers a conversion against that ad and adds it to reporting. The ID does not expire.

The endpoint is: https://e-{networkId}.adzerk.net/conv/{GUID}

📘

Note

The conversion macro does not unfurl until after the click is called, so the conversion ID cannot be read from the Decision API response itself, only from the click URL.

🚧

This is not a turn-key setup for the advertiser

Steps 2 and 3 happen in the advertiser's own system, so they need to do development work on their side. Confirm they can read a query parameter and make a server-side call before you sell a campaign that depends on this.

If the conversion happens on a property you control rather than the advertiser's, you can carry out steps 2 and 3 yourself using the same endpoint. See Sending conversions directly for the other methods available in that case.

Additional Parameters

Some additional parameters that can be appended to the endpoint are:

• override: replaces the revenue value of the conversion (e.g. appending ?override=1.23 would set the revenue to $1.23)
• additional: adds the specified value to the original revenue value of the conversion (e.g. appending ?additional=1.23 would add $1.23 to the original revenue for the conversion)
• gmv: records the Gross Merchandise Value of the conversion (e.g. appending ?gmv=1.64 sets a GMV of $1.64). This is what drives the ROAS figure in reporting, so pass it if the advertiser is measuring return on ad spend. See GMV, ROAS, and Autobid.
• eventMultiplier: records the call as several conversions at once (e.g. appending ?eventMultiplier=3 counts three conversions), scaling the conversion count and the conversion's own revenue together. Use it in place of firing the endpoint several times. See Event Multipliers for the accepted range and how it interacts with revenue.

curl -g https://e-1234.adzerk.net/conv/1231221?override=1.23&gmv=1.64

A parameter that appears more than once in the same URL is ignored. When both override and additional are passed, override is applied first and additional is added to the result, so ?override=1.23&additional=0.50 records revenue of $1.73.

❗️

An empty value is read as zero, not ignored

?override= sets the revenue to $0.00, ?gmv= sets the GMV to $0.00, and ?additional= adds nothing. Pass a parameter only when you have a value for it, rather than templating it from an order field that can be empty.

Retries and Repeat Calls

The conversion ID is a lookup key rather than a one-time token, and calling the endpoint does not consume it. Each call to the same ID records another conversion, with its own count, revenue and GMV, and returns 200.

The endpoint returns:

• 200 - the conversion was recorded. The response body is empty.
• 400 - the conversion ID is missing or not recognised. Nothing is recorded.
• 401 - the network requires an API key on event requests, and it was absent or invalid.
• 429 - the request was throttled.
• 500 - an internal error.

Kevel records what the caller reports here, because the caller is the one running the attribution. Call the endpoint at most once per transaction, keyed on your own order or transaction ID:

• Store the fact that a conversion has been sent before sending it, and check that store before sending.
• If a call times out, treat the outcome as unknown rather than retrying, since a retry that follows a call Kevel already received is counted twice.

additional applies to the revenue stored with the conversion, not to a running total. Two calls with ?additional=1.23 record two conversions of the original revenue plus $1.23 each, rather than one conversion with $2.46 added.

Conversions on a CPA-priced Flight are that Flight's revenue event, so a repeated call spends against its budget as well as appearing in reporting. On Flights priced by impression or click, a repeated call carries no revenue, and affects the conversion count, GMV and ROAS figures.