Implementing Server Postback Tracking

Both networks and advertisers take part in implementing server postback tracking. This article walks you through the steps of that process and the various ways that advertisers can process and return conversion data.

Important: When tracking via server postbacks, advertisers are responsible for returning conversion data. TUNE customer support cannot assist in this.

Before continuing with this article, you should understand the fundamentals of server postback tracking. Below, we’ll focus on server postback tracking with transaction ID. For information on tracking with partner ID, see the related section in the above article.

Overview of Steps

First, the network sets the offer’s tracking protocol. This can happen either during offer creation or afterwards when editing the offer.

Then, the network configures the default offer URL to provide an identifier and other optional information to the advertiser on click.

Once a click happens, the advertiser stores session information using one of a few mechanisms.

Finally, if the user converts on the offer, the advertiser fires a postback to TUNE with the session identifier and other information.

Setting the Offer Tracking Protocol

When creating an offer, set the Conversion Tracking setting to one of the server postback options:

conversion tracking menu tidYou can always change this setting after the offer is created. However, existing tracking links will cease to function and need to be replaced with newly generated ones.

To change an offer’s tracking protocol, start on the offer’s page. In the Details panel, click Edit at the top. On the page that appears, set Conversion Tracking to the tracking protocol of your choice, and click Save once you’re finished.

Configuring the Default Offer URL

To provide an advertiser with an offer’s session information, you’ll need to configure your default offer URL. This process connects clicks with conversions that happen in the same session.

For server postbacks with transaction ID, this means passing the transaction ID value to the advertiser through a parameter in the default offer URL. From your offer’s page, you can find its default offer URL by going to the Details panel and clicking Edit at the top.

In your default offer URL, match your advertiser’s session parameter with the TUNE placeholder macro for your tracking protocol. For example, the placeholder macro for transaction ID is {transaction_id}.

Parameters themselves can vary in name, so you need to be aware of what parameters your advertiser is expecting. For example, if the advertiser’s server expects the transaction ID in a parameter called session_id, then your default offer URL should have session_id={transaction_id} in its query string.

As another example, your advertiser might ask you to include the campaign and source parameters in addition to the session_id parameter. Your default offer URL would then look something like this:

http://advertiser.example.com/offer/ad?offer=102&session_id={transaction_id}&campaign={aff_sub}&source={source}

After TUNE fills in values for the macros, the user is directed to a URL that looks similar to this:

http://advertiser.example.com/offer/ad?offer=102&session_id=10214043256817052076618466&campaign=109581A&source=awesomepub

For more details on offer URL parameters, read our article on passing values to an offer URL.

Advertiser Stores Session Identifier

The advertiser needs to have some way of keeping track of the transaction ID so it can report on sessions that convert. Because it wholly depends on the advertiser’s technology, this is the most varied step in the process. Some common methods are: storing the ID in a database, storing the ID in a cookie, and passing the ID through each URL.

Storing in a Database

In cases where the advertiser stores session information in a database, the transaction ID can be stored as one of the parameters in the advertiser’s database. This is the most robust way of using server postback tracking, though it can require a developer to modify the advertiser’s software to accommodate.

storing in a database

This method benefits from being able to track user conversions across devices and touchpoints. Because the transaction ID is stored in a database and relates to a specific user, conversions are tracked independently of how the user entered the offer.

Storing in a Cookie

In many cases, the advertiser’s site takes the transaction ID and stores it as a cookie in the user’s browser.
passing through each URLUpon conversion, the advertiser retrieves the transaction ID value from the cookie in the user’s browser. This is simpler for advertisers to implement, and a natural choice for those already tracking user sessions primarily with cookies.

However, if the cookie gets cleared or if the user converts on another browser or device, then the conversion won’t be recorded. As a result, we recommend avoiding this method when using server postback tracking.

Passing via Page URLs

Rarely, transaction IDs are instead passed as a parameter through page URLs on the advertiser’s site. The value is passed from one page in the funnel to the next as a parameter in the URL.
storing in a cookie This can work for very short offer funnels. However, the primary shortcoming is that users can leave the offer funnel and later return without the same transaction ID in the URL. As a result, the conversion won’t be tracked.

We recommend another method for offer funnels that have more than four pages or allow users to branch away. Additionally, because the transaction ID is exposed in the URL, users can tamper with it directly.

Advertiser Returns ID upon Conversion

When a user completes a conversion on an advertiser’s site, the advertiser needs to tell TUNE about the conversion. We call this “firing a postback”. The advertiser’s site does this by sending a signal to our servers that uses two elements:

  • The offer’s postback URL
  • The transaction ID for that session

The postback URL is found in the offer’s tracking settings and looks something like this:

http://examplenetwork.go2cloud.org/aff_lsr?offer_id=26&transaction_id=TRANSACTION_ID

In the above URL, the advertiser replaces TRANSACTION_ID with the transaction ID that they stored for that session. For example, if the advertiser had earlier received a transaction ID of “1027c887059b47bc69c699f45466b9” from TUNE, then the postback URL becomes:

http://examplenetwork.go2cloud.org/aff_lsr?offer_id=26&transaction_id=1027c887059b47bc69c699f45466b9

At the same time, the advertiser also fills in other parameters in the postback URL (like advertiser sub IDs and sale amounts). To learn more about postback URL parameters, read our article on customizing a conversion link.

Note: The advertiser should use a HTTP GET request to fire postbacks to TUNE.

Advertiser HTTP Request

Finally, the advertiser makes a HTTP request to the postback URL. For example, they can make the HTTP request via cURL on the server-side, or even just type the postback URL into a browser. In any case, TUNE validates the conversion based on the transaction ID.

If the conversion is valid, TUNE responds to the HTTP request with:

success=true;

If the conversion is invalid, TUNE responds instead with an error message. This can be seen when the advertiser’s system records an incomplete transaction ID and sends a conversion with that incomplete ID. The following message is returned:

success=false; err_msg=Invalid Trans. ID #1027c887059b47b.;

Error messages are intended for use by advertisers and networks as diagnostic tools. Other error messages reported in the server logs include:

  • Duplicate conversion
  • No referral URL
  • IP address not whitelisted
  • Wrong tracking protocol
  • Duplicate conversion by unique ID
  • Invalid advertiser security token

Important: You will receive a “200 OK” HTTP response code if we attempt to process the postback, even if unsuccessful. This lets you know TUNE received the request, and to not resubmit it as you might for a 4xx or 5xx response code.