Airbridge Integration Guide

Airbridge provides a fast and easy integration process to become an integrated ad partner. Please fill out the request form below to get started. Our integration manager will reach out to you with further information once the form is submitted.

Please refer to the guide below and setup your tracking link templates and postback URLs.

Tracking Link Template Setup

Standard Parameters

Below are the parameters that can be sent through an Airbridge tracking link. Please note that some values are mandatory.

NameParameter NameRequiredDescriptionExample
Click IDclick_idRequiredThe unique click identifier used by the media platform.click_id={Touchpoint_Id}
Publisher IDsub_idRequiredThe media's publisher id. If the media works with several different publishers, they can be identified through the value of sub_idsub_id={PUBLISHER_ID}
Sub Publisher IDsub_id_1
RecommendedThe media's sub_publisher id. If the media’s publishers have additional sub publishers, they can be identified through the values of sub_id_1, sub_id_2, and sub_id_3.
* It should follow the structure of the sub publishers
( sub_id_1 > sub_id_2 > sub_id_3 )
ADID (Android GAID or iOS IDFA)ad_idRequired if possibleThe device’s Advertising ID (depends on device OS)
(Android GAID or iOS IDFA)
* It it used when only one parameter is used for the advertising ID, rather than using separate parameters (gaid_raw, ifa_raw)
GAID (Android only)gaid_rawRequired if possible"Google Advertising ID" for Android devices(GAID) (Google document)gaid_raw={ANDROID_ADID}
IDFA (iOS only)ifa_rawRequired if possible"Identifier for Advertisers" for iOS devices (IDFA) (Apple document)ifa_raw={IOS_IDFA}
IPipRequired for S2S integrationDevice(client) IP Address (server to server click only)ip={IP_ADDRESS}
User Agentuser_agentRequired for S2S integrationUser Agent information - encoding is required (server to server click only)user_agent={USER_AGENT}
CampaigncampaignOptionalCampaign Namecampaign={CAMPAIGN}
Ad Groupad_groupOptionalAd Groupad_group={AD_GROUP}
Ad Creativead_creativeOptionalAd Creativead_creative={AD_CREATIVE}
Campaign IDcampaign_idOptionalCampaign IDcampaign_id={CAMPAIGN_ID}
Ad Group IDad_group_idOptionalAd Group IDad_group_id={AD_GROUP_ID}
Ad Creative IDad_creative_idOptionalAd Creative IDad_creative_id={AD_CREATIVE_ID}
Term IDterm_idOptionalKeyword IDterm_id={TERM_ID}


[Highly Recommended] ADID in your tracking link template

Due to Apple's privacy policy, fingerprinting is no longer available for iOS 14.5 and later versions. Adding an IDFA value to your tracking link template enables us to leverage IDFA for attribution of users who opt-in for ATT(AppTrackingTransparency).

The mandatory parameters needed for Airbridge tracking links are "Click ID" and "Publisher ID". However, it is highly recommended to add as many parameters as possible to better optimize campaigns. If you have a list of parameters or relevant documents to share with us, we can create a tracking link template on your behalf and register it on our system.


Custom Parameters

Apart from the above parameters, you can add custom parameters to the tracking link template if you have specific data that you'd like to collect through the postback. Custom parameter key-values can be named however you prefer.

Custom parameter example){CLICK_ID}&sub_id={SUB_ID}&gaid_raw={GAID}&ifa_raw={IDFA}&custom_param1={MACRO1}&custom_param2={MACRO2}

Tracking Link Operation

When a user clicks or views an ad on a media platform, the configured tracking link will be filled with actual values and then transmit the data.

Example){TOUCHPOINT_ID}&ad_id={ADID}&sub_id={PUBLISHER_ID} 6&sub_id=abzdo_16345

Postback URL Template Setup

Airbridge clients are able to configure postbacks (attribution and events) in the Airbridge dashboard. Depending on these settings, Media channels can receive postbacks of attributions and events in real-time.
In order to receive postbacks, media platforms must register a postback URL template for each event type below on the Airbridge system.

  1. Postback URL template for "Installs"
  2. Postback URL Template for "In-App Events"

If the postback URL templates are the same for both event types, you only need to configure one and share the template with us. Please see below for detailed specifications on how to structure your postback URL templates.

Airbridge Event Types

Two types of events are available for postback, "Standard Events" and "Custom Events".

Event TypeEventsEvent Name (raw)
Standard Eventinstallapp_install
Standard EventLaunch / Openapp_open
Standard EventDeeplink Launchapp_deeplink_open
Standard EventSign Upairbridge.user.signup
Standard EventSign Inairbridge.user.signin
Standard EventSign Outairbridge.user.signout
Standard EventView Homeairbridge.ecommerce.home.viewed
Standard EventView Product Listairbridge.ecommerce.productList.viewed
Standard EventView Search Resultairbridge.ecommerce.searchResults.viewed
Standard EventView Detailed Productairbridge.ecommerce.product.viewed
Standard EventAdd To Cartairbridge.ecommerce.product.addedToCart
Standard EventPurchaseairbridge.ecommerce.order.completed
Standard EventAd Impressionairbridge.adImpression
Standard EventSubscribeairbridge.subscribe
Standard EventUnsubscribeairbridge.unsubscribe
Standard EventScheduleairbridge.schedule
Standard EventUnlock Achievementairbridge.unlockAchievement
Standard EventAd Clickairbridge.adClick
Standard EventAdd to Wishlistairbridge.addToWishlist
Standard EventShareairbridge.share
Standard EventComplete Tutorialairbridge.completeTutorial
Standard EventAchieve Levelairbridge.achieveLevel
Standard EventAdd Payment Infoairbridge.addPaymentInfo
Standard EventInitiate Checkoutairbridge.initiateCheckout
Standard EventSpend Creditsairbridge.spendCredits
Standard EventStart Trialairbridge.startTrial
Standard EventRateairbridge.rate
Custom EventVaries by advertiserVaries by advertiser

Airbridge Standard Event consists of the most common in-app events from an "Install" event to a "Purchase" event. Airbridge event values are defined by default but can be mapped with customized values. (e.g. for a "Purchase" event, use purchase instead of airbridge.ecommerce.order.complete). Numeric ID values used to represent an event (e.g. 7 is used instead of airbridge.user.signup) can also be mapped. Share the event mapping table with Airbridge and Airbridge will proceed with the necessary setup.

Custom events are configured per service by advertisers to track those events. Advertisers use different names for different events and the names are sent as-is within the postback URL. Please let Airbridge know if you want custom events to be mapped to different values for your postbacks.

Supported Data and Macros for Postback URL Templates

Please refer to the "Airbridge Postback Specificiations" below for the entire list of macros that Airbridge provides via postback.

Refer to the items marked as ‘1’ in column D(Web) and E(App) to determine the fields to be delivered through postbacks. When adding macros into postback URL templates, input the field value wrapped with curly brackets ({ }).
For example, in order to receive Airbridge Device ID via postbacks, map {device.deviceUUID} as your key.

[Required] Adding Mandatory Parameters to Postback URLs

There are two parameters that must be included in your postback URL in order to prevent any duplicate transmissions and to smoothly troubleshoot when issues arise.

Event Timestamp Parameter

If event time-related data is collected through postbacks, relevant parameters should be added to the postback URLs and mapped with the below macros. Even if event time data is not collected, please ensure that parameters regarding event time that we would add on your behalf such as airbridge_event_timestamp={eventTimestamp} will not cause any problems (at least one of the below parameters).

Event Datetimestring{eventDatetime}
Event Datetime GMT (UTC)string{eventDatetimeGMT}
Event Timestamp in Milliseconds (13 digits)int{eventTimestamp}
Event Timestamp in Seconds (10 digits)int{eventTimestampInSec}

Device Identifier parameter

If the device identifier is collected through postbacks, relevant parameters should be added to the postback URLs and mapped with the below macros. Even if device IDs are not collected, please ensure that the below parameters will not cause any problems when sent.

  • DeviceUUID consists of 4 different types of device IDs(GAID, IDFA, IDFV, & Random Generated), we highly recommend appending deviceUUIDType along the deviceID macro.
Airbridge Device IDstring{device.deviceUUID}
Airbridge Device ID Typestring{device.deviceUUIDType}

[Reference] Receiving Multiple Product-related Data

There may be several events (e.g. add to cart, order complete) related to a product. Airbridge can postback several product-related data as a single event in JSON format.

You can map a {@postback.jsonData} macro to the Postback URL, and compose a JSON Template with parameters regarding product information such as product name, product id, price, etc. Please refer to the table below for details.

NameTypeParameter Name
Product IDstringeventData.goal.semanticAttributes.product[0].productID
Product NamestringeventData.goal.semanticAttributes.product[0].name
Product PricefloateventData.goal.semanticAttributes.product[0].price
Product QuantityinteventData.goal.semanticAttributes.product[0].quantity
Product CurrencystringeventData.goal.semanticAttributes.product[0].currency
Product PositioninteventData.goal.semanticAttributes.product[0].position

When composing a JSON template, please use {@for ... in ...} and {@endfor} in order to distinguish the recurring and non-recurring parts of the data.
As shown in the below example, the data inside of {@for product in eventData.goal.semanticAttributes.products} and {@endfor} are recurring. Each product data can be accessed through {product.*} and you can refer to the table above for data that can be utilized with {product.*}

{@for product in eventData.goal.semanticAttributes.products} 
        "event_item_id": {product.productID}, 
        "quantity": {product.quantity}, 
        "unit_price": {product.price}, 
        "currency_code": {product.currency}, 
        "event_item_name": {} 

Postback URL Operation

If a media channel was attributed for any conversions, Airbridge will send a postback to the corresponding media channel with the values filled in.

In order to know that the parameter is a tracking link parameter, you must add a @trackingLink prefix for custom parameters when composing a postback URL. (e.g. {@trackingLink.custom_param}). Please refer to the below example.

Postback URL Template:{attributionResult.attributedClickID}& ad_channel={attributionResult.attributedChannel}&event_timestamp={eventTimestamp}&customID={@trackin gLink.custom_param}

Actual Postback: 9a66&ad_channel=sample_channel&event_timestamp=1479186394000&customID=4093721

Frequently Asked Questions

Do you provide timestamp values in seconds? Or does it have to be converted?

All timestamps from Airbridge are in milliseconds by default. You can add InSec at the end of the timestamp field to convert timestamps to seconds.
e.g. {requestTimestamp}{requestTimestampInSec}

Can I convert the boolean type fields to int?

Any boolean type fields in the Airbridge Postback Spec sheet into int by attaching :int to the value. true converts to 1 and false converts 0.
e.g. {@postback.isAttributedToTargetChannel}{@postback.isAttributedToTargetChannel:int}

If you have any further questions regarding media integration, please contact the Airbridge Platform Team.