Sample Network Integrations

Last Updated: Aug 15, 2015 02:12PM PDT

About this Article


The purpose of this article is to serve as supplemental knowledge to understanding Apsalar's attribution and postback system in the context of an ad network integration.  Although Apsalar does not have officially recommended integrations, here, you can find the most common integrations as a reference.  Your ad network's integration does not have to follow the examples presented in this article.  If you have any questions, please reach out to our support team at support@apsalar.com.

Before reviewing this article, it is assumed that there is a basic understanding of the purpose of attribution tracking tags and postbacks.  For more information on mobile attribution methods supported by Apsalar, please see our attribution guide.

Disclaimer: This article was written using examples of Apsalar's legacy attribution tracking tags, and does not provide examples of Apsalar smart tags.  However, the ad network integration process remains the same.

Click Tag Configuration

For the below example(s), we will assume the following Apsalar configuration values as configured by the advertiser:
 
Apsalar Account Name AdvertiserApsalarAccountName
Campaign Name (iOS) iOSCampaignName
Campaign Group Name (iOS) iOSGroup1
Campaign Name (Android) AndroidCampaignName
Campaign Group Name (Android) AndroidGroup1
iOS Bundle ID com.sample.iosapp
Android Bundle ID com.sample.androidapp
Ad Network Name SampleAdNetwork
 
Apsalar supports a variety of campaign related values for our advertisers to ingest into Apsalar reporting interface.  These values are passed via the attribution tracking tags.  Apsalar attribution tracking tags (and postbacks) are configured per platform, so there will be examples per iOS and Android.

These tracking tags are generated by the advertiser in the Apsalar dashboard, and are provided to the network for tracking the campaign in Apsalar. Once an ad network is integrated, tracking tags generated for said ad network will automatically contain any applicable parameters and network-side macros as defined during the ad network integration process.

Using the above Apsalar configuration values, a base attribution tracking tag with no additional ad network specific integration points, resembles the following:

iOS:
http://ad.apsalar.com/api/v1/ad?re=0&a=AdvertiserApsalarAccountName&i=com.sample.iosapp&ca=iOSCampaignName&an=SampleAdNetwork&p=iOS&pl=iOSGroup1&h=c232ac188ed718090dad62d59306d1cbdb956764


Android:
http://ad.apsalar.com/api/v1/ad?re=0&a=AdvertiserApsalarAccountName&i=com.sample.androidapp&ca=AndroidCampaignName&an=SampleAdNetwork&p=Android&pl=AndroidGroup1&h=e72051e29cdb02fdb09da1509bcbaff1628cf280

Please note the h= parameter and value is generated by the Apsalar system and is a security hash.  Do not remove/modify the h= that is provided in the click template.  Similarly, values in bold are generated by the Apsalar system and should not be modified in order for attribution to proceed. 

While the above base tracking tag will allow Apsalar to track a campaign, by officially integrating with Apsalar, our system can incorporate the ad networks' custom macros on top of the base attribution tracking tags.  Doing this will allow the ad network to pass key data points that allow Apsalar to more effectively track attributions for campaigns.  The following examples will show some how some of these data points are passed to Apsalar.  To begin, we will assume the following network-side macros (note: your ad networks' macros may be different):
 
Macro Example Value Description
{transaction_id} abcdef123456 Transaction ID that uniquely identifies the attribution session (web supported format only)
{idfa} 20A1562C-13C2-480D-96AB-4A5BE5D87C7E Apple Advertising ID (upper-case only)
{aifa} 79f427ff-bf0f-4a12-aa00-ce729d6e0b54 Android Advertising ID (lower-case only)
{andi} 2f4247b4e40b7779 Android Device ID (lower-case only)
{creative} creative1234 Creative name or value (web supported format only)
{source} source1234 Source application or site (web supported format only)
 

Click Tag - Transaction ID

To be able to track unique attributions, a transaction or click ID is usually provided to Apsalar.  This transaction ID may be used as a passthrough in the postback to the ad network.  Other passthrough values may include values such as goal IDs, user IDs, or any other custom value useful for the network.

An attribution tag that includes only the transaction ID will resemble the following.

iOS:
http://ad.apsalar.com/api/v1/ad?re=0&a=AdvertiserApsalarAccountName&i=com.sample.iosapp&ca=iOSCampaignName&an=SampleAdNetwork&p=Android&pl=iOSGroup1&h=c232ac188ed718090dad62d59306d1cbdb956764&cl={transaction_id}


Android:
http://ad.apsalar.com/api/v1/ad?re=0&a=AdvertiserApsalarAccountName&i=com.sample.androidapp&ca=AndroidCampaignName&an=SampleAdNetwork&p=Android&pl=AndroidGroup1&h=c232ac188ed718090dad62d59306d1cbdb956764&cl={transaction_id}

Click Tag - Device and Advertising IDs

Though the above tracking tags is all that is sufficient for tracking attributions per device, the above will rely on fingerprinting for tracking.  As such, we recommend that device or advertising IDs be supplied in the attribution URL as follows:

iOS:
http://ad.apsalar.com/api/v1/ad?re=0&a=AdvertiserApsalarAccountName&i=com.sample.iosapp&ca=iOSCampaignName&an=SampleAdNetwork&p=iOS&pl=iOSGroup1&h=c232ac188ed718090dad62d59306d1cbdb956764&cl={transaction_id}&idfa={idfa}


Android (w/ Android Advertising ID):
http://ad.apsalar.com/api/v1/ad?re=0&a=AdvertiserApsalarAccountName&i=com.sample.androidapp&ca=AndroidCampaignName&an=SampleAdNetwork&p=Android&pl=AndroidGroup1&h=c232ac188ed718090dad62d59306d1cbdb956764&cl={transaction_id}&aifa={aifa}


Android (w/ Android ID):
http://ad.apsalar.com/api/v1/ad?re=0&a=AdvertiserApsalarAccountName&i=com.sample.androidapp&ca=AndroidCampaignName&an=SampleAdNetwork&p=Android&pl=AndroidGroup1&h=c232ac188ed718090dad62d59306d1cbdb956764&cl={transaction_id}&andi={andi}

 

Click Tag - Additional Campaign Values

Providing device or advertising IDs will allow the most accurate tracking available.  However, Apsalar also supports receiving various campaign related values, such as the creative source or name as follows.  Though not required, passing the below values offers the advertiser greater insight into their campaigns and it's performance.

iOS:
http://ad.apsalar.com/api/v1/ad?re=0&a=AdvertiserApsalarAccountName&i=com.sample.iosapp&ca=iOSCampaignName&an=SampleAdNetwork&p=iOS&pl=iOSGroup1&h=c232ac188ed718090dad62d59306d1cbdb956764&cl={transaction_id}&idfa={idfa}&cr={creative}&s={source}


Android (w/ Android Advertising ID):
http://ad.apsalar.com/api/v1/ad?re=0&a=AdvertiserApsalarAccountName&i=com.sample.androidapp&ca=AndroidCampaignName&an=SampleAdNetwork&p=Android&pl=AndroidGroup1&h=c232ac188ed718090dad62d59306d1cbdb956764&cl={transaction_id}&aifa={aifa}&cr={creative}&s={source}


Android (w/ Android ID):
http://ad.apsalar.com/api/v1/ad?re=0&a=AdvertiserApsalarAccountName&i=com.sample.androidapp&ca=AndroidCampaignName&an=SampleAdNetwork&p=Android&pl=AndroidGroup1&h=c232ac188ed718090dad62d59306d1cbdb956764&cl={transaction_id}&andi={andi}&cr={creative}&s={source}

 

Postback Configuration

Apsalar supports a variety of values that may be passed to an ad network's endpoint as a result of events triggered in an attribution flow.  There are three types of actions that can trigger a postback.  These are the install (re-engagement), revenue, and custom event actions.  The following example(s) will demonstrate common use cases and how a postback is built with Apsalar macros.  You can find a list of our supported macros here

For the below examples(s), we will assume the following iOS attribution click template was used to trigger the attribution flow:

iOS:
http://ad.apsalar.com/api/v1/ad?re=0&a=AdvertiserApsalarAccountName&i=com.sample.iosapp&ca=iOSCampaignName&an=SampleAdNetwork&p=iOS&pl=iOSGroup1&h=c232ac188ed718090dad62d59306d1cbdb956764&cl={transaction_id}&idfa={idfa}&cr={creative}&s={source}
 

The Install Postback

An install action occurs when a device opens an advertiser app for the first time.  First app open is linked to and defined by the first session start for a particular device ID or device advertiser ID.  Following an install action, a postback can be configured by the advertiser, to report the action to an endpoint.

The following is an example of what may be passed in an install postback, with Apsalar macros:
http://yournetworkdomain.com/postbackendpoint?cl={cl?SampleAdNetwork}&idfa={IDFA}&creative={CREATIVE}&source={SOURCE}&eventtimestamp={UTC}&eventname={EVTNAME}


The {cl?SampleAdNetwork} is the Apsalar macro for the passthrough value for {transaction_id} that was provided in the click.  Other macros and their values can be found in our postback guide here.  
 

The Revenue Postback

A revenue action is a post-install action that occurs when a user performs an in-app purchase, or an advertiser defined event that has an associated revenue amount.  Following a revenue action, a postback can be configured by the advertiser, to report the action to an endpoint.

The following is an example of what may be passed in a revenue postback, with Apsalar macros:
http://yournetworkdomain.com/postbackendpoint?cl={cl?SampleAdNetwork}&idfa={IDFA}&creative={CREATIVE}&source={SOURCE}&eventtimestamp={UTC}&eventname={EVTNAME}&amount={AMOUNT}&currency={CURRENCY}

 

The Custom Event Postback

A custom event action is a post-install action that occurs when a user performs an advertiser defined event that has an associated revenue amount.  Following a revenue action, a postback can be configured by the advertiser, to report the action to an endpoint.

The following is an example of what may be passed in a custom event postback, with Apsalar macros:
http://yournetworkdomain.com/postbackendpoint?cl={cl?SampleAdNetwork}&idfa={IDFA}&creative={CREATIVE}&source={SOURCE}&eventtimestamp={UTC}&eventname={EVTNAME}&eventparam={EVTATTR:attribute_name}


The {EVTATTR:attribute_name} macro is a macro that evaluates to the value of the attribute_name variable that is passed as an argument into the event via the Apsalar SDK. The attribute_name will vary from advertiser to advertiser, and is dependent on how the advertiser has implemented the Apsalar SDK in their app.

Macro Parameters

Sometimes an ad network may require advertisers to use ad network required values in a postback.  Though uncommon, Apsalar can implement macro parameters which prompt an advertiser to enter a value for.  These macro parameters can be provided at per advertiser, application, or postback. A common use of an advertiser parameter is an account ID.  A common use of an application parameter is an application ID.  A common use of a postback parameter is an event name required by an ad network.

The following is an example of how an ad network assigned 'account ID' can be incorporated into an install postback template:
http://yournetworkdomain.com/postbackendpoint?cl={cl?SampleAdNetwork}&idfa={IDFA}&creative={CREATIVE}&source={SOURCE}&eventtimestamp={UTC}&eventname={EVTNAME}&account_id={{account_id}}

In the above example, the {{account_id}} macro will be replaced by a value the advertiser is prompted to enter when the postback is being configured in the advertiser Apsalar dashboard.  
support@apsalar.com
http://assets3.desk.com/
apsalarinc
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
Invalid characters found
/customer/en/portal/articles/autocomplete