Postback

Kodo Ad Network advertisers can send conversion events to Kodo via a "postback URL". A postback URL is a simple setup involving a URL that needs to be called with an HTTP GET request. This is a simple and flexible approach to conversion reporting, and it can be set up to be called programmatically from the browser, as an HTML element (pixel), or server-to-server. The postback type of integration requires that you can store dynamic values provided by Kodo for later usage.

A typical flow would be something like this:

1. Customer engages with a Kodo Ad Network experience, clicking on your offer
2. Kodo directs the customer to your landing page, and along the way we include a few URL query parameters for you to send back to us when the customer converts
3. The customer completes whatever actions are required to convert
4. You call your Kodo-provided postback URL, including the parameters we sent to you earlier

Integration

The postback is a URL that should be called with an HTTP GET request, with a few dynamic parameters provided by Kodo. All integration types require the ability to accept query parameters and send them back to us later. We can send these query params in any way that works for you, but we have strict requirements for how they are returned to us.

For each integration type, our team will coordinate with you to provide your unique postback URL, ensure that we are sending our dynamic values in a format that works for you, and complete end-to-end testing of the integration.

Postback URL formats

Your postback URL can pass the click ID in the path or as a query parameter. Use whichever is easier for your platform:

https://thanks.is/postback/{your-key}/{click-id}
https://thanks.is/postback/{your-key}?clickid={click-id}

Parameter names are not case-sensitive and ignore underscores, so clickid, click_id, and ClickId are all accepted. Empty parameters are treated as missing.

Client side / browser

The browser integration can be set up to be called programmatically, or treated as a pixel.

Programmatic

Programmatic is probably the most common approach because it gives you the most control over when the client-side conversion is triggered.

1. We send the customer to your landing page with a few query parameters, for example:

   https://your-site.com/your/landing/page?queryParam1=dynamicValue1&queryParam2=dynamicValue2&...your query params

   The actual names for queryParam1/2 can be defined by you, and dynamicValue1/2 are dynamic values that must be saved for later.

2. When the customer completes the conversion event, call your unique postback URL with the click ID we provided earlier, for example:

   JavaScript

   fetch('https://thanks.is/postback/{your-key}/{click-id}');

Pixel-like

The pixel-like solution is the least technical and easiest to set up in a tool like Google Tag Manager, but also the least flexible.

1. We send the customer to your landing page with a few query parameters. The actual names for queryParam1/2 can be defined by you, and dynamicValue1/2 are dynamic values that must be saved for later.

   https://your-site.com/your/landing/page?queryParam1=dynamicValue1&queryParam2=dynamicValue2&...your query params

2. When the customer lands on a page where the conversion event is complete, add an image HTML tag to the page that acts as the pixel, using the click ID we provided earlier:

   HTML

   <img src="https://thanks.is/postback/{your-key}/{click-id}" width="0px" height="0px" />

Server to server (S2S)

An S2S integration is similar to the browser-based programmatic integration, but it is called from the server rather than the browser. You have total control over when the conversion event is sent to us.

1. We send the customer to your landing page with a few query parameters, for example:

   https://your-site.com/your/landing/page?queryParam1=dynamicValue1&queryParam2=dynamicValue2&...your query params

   The actual names for queryParam1/2 can be defined by you, and dynamicValue1/2 are dynamic values that must be saved for later.

2. When the customer completes the conversion event, call your unique postback URL with the click ID we provided earlier, for example:

   JavaScript

   fetch('https://thanks.is/postback/{your-key}/{click-id}');

This example is in JavaScript/Node, but you can use any language that supports HTTP requests.

Sending the commission

Some campaigns pay a commission that changes with each order, for example a percentage of the sale. For these campaigns, add the commission to the postback URL so we can record what each conversion earned:

https://thanks.is/postback/{your-key}/{click-id}?commission=12.50&sale_amount=125.00&currency=USD

Things to know:

• Your Kodo Ad Network agreement sets whether a campaign uses a variable commission. On a campaign with a fixed payout per conversion, we always use the fixed payout and ignore commission.
• Send the commission from your server (S2S), not from the browser. A browser request exposes your postback key, and anyone with the key could report a commission.
• The currency must match your campaign's currency. We do not convert between currencies.
• If commission is missing or is not a valid number, we still record the conversion, but at no commission. We then contact you to fix the integration.
• We record one conversion per click. A second postback for the same click is ignored.

If a tracking platform or affiliate network sends postbacks for you, map its payout, sale amount, and currency macros to these parameters in its postback settings.

Anonymized Postback Events

Pushing conversion events back to Kodo is important so that we can optimize where and how your offers are placed. The default postback setup with the click ID allows us to tie a conversion event to a specific session and make deep connections into the ideal customer profile for your offer. However, there may be cases where it is not possible or not desirable to tie the conversion event back to a specific session (for example, where regulations restrict the sharing of personal information). For these cases, Kodo supports an anonymized postback that lets a select subset of information be shared back to the network, without tying the event to a specific click or user. This information may include things like a creative ID or a placement ID. During the integration process, we will ensure that the data to be shared meets your needs.

There are a couple of key limitations with anonymized postback events:

1. With less data, Kodo is more limited in how well it can optimize your offer. We will always place the offer as best we can with the available data.
2. Without the ability to match to a specific click, Kodo cannot deduplicate events. We will ingest all events we receive as separate events, even if from your side they are coming from the same session and should be deduplicated.

Setup

The anonymized postback setup is very similar to the process described above.

1. Kodo sends a customer to your landing page with a link including query params that you will later pass back to us (see above for examples).

2. At conversion time, make an HTTP request like so:

   Text

   https://thanks.is/postback/{your-key}?creativeId=crtv-1234-abc&placementId=plcmt-1234-abcd

The key and precise query parameter names will be shared during integration.