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.

• Media Partner Integration Request Form

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.

Name	Parameter Name	Required	Description	Example
Click ID	click_id	Required	The unique click identifier used by the media platform.	click_id={Touchpoint_Id}
Publisher ID	sub_id	Required	The media's publisher id. If the media works with several different publishers, they can be identified through the value of sub_id	sub_id={PUBLISHER_ID}
Sub Publisher ID	sub_id_1 sud_id_2 sub_id_3	Recommended	The 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 )	sub_id_1={SUB_PUBLISHER_ID_1} sub_id_2={SUB_PUBLISHER_ID_2} sub_id_3={SUB_PUBLISHER_ID_3}
ADID (Android GAID or iOS IDFA)	ad_id	Required if possible	The 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)	ad_id={ADID}
GAID (Android only)	gaid_raw	Required if possible	"Google Advertising ID" for Android devices(GAID) (Google document)	gaid_raw={ANDROID_ADID}
IDFA (iOS only)	ifa_raw	Required if possible	"Identifier for Advertisers" for iOS devices (IDFA) (Apple document)	ifa_raw={IOS_IDFA}
IP	ip	Required for S2S integration	Device(client) IP Address (server to server click only)	ip={IP_ADDRESS}
User Agent	user_agent	Required for S2S integration	User Agent information - encoding is required (server to server click only)	user_agent={USER_AGENT}
Campaign	campaign	Optional	Campaign Name	campaign={CAMPAIGN}
Ad Group	ad_group	Optional	Ad Group	ad_group={AD_GROUP}
Ad Creative	ad_creative	Optional	Ad Creative	ad_creative={AD_CREATIVE}
Term	term	Optional	Keyword	term={KEYWORD}
Campaign ID	campaign_id	Optional	Campaign ID	campaign_id={CAMPAIGN_ID}
Ad Group ID	ad_group_id	Optional	Ad Group ID	ad_group_id={AD_GROUP_ID}
Ad Creative ID	ad_creative_id	Optional	Ad Creative ID	ad_creative_id={AD_CREATIVE_ID}
Term ID	term_id	Optional	Keyword ID	term_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.

Example)
https://abr.ge/@APP_NAME/MEDIA_NAME?click_id={CLICK_ID}&sub_id={SUB_ID}&gaid_raw={GAID}&ifa_raw={IDFA}

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)
https://abr.ge/@APP_NAME/MEDIA_NAME?click_id={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)
https://abr.ge/@airbridge/ab180_ads?click_id={TOUCHPOINT_ID}&ad_id={ADID}&sub_id={PUBLISHER_ID}
→ https://abr.ge/@airbridge/ab180_ads?click_id=abcf15142ads&ad_id=94ec0320-7f08-11e6-bdf4-0800200c9a6 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 Type	Events	Event Name (raw)
Standard Event	install	app_install
Standard Event	Launch / Open	app_open
Standard Event	Deeplink Launch	app_deeplink_open
Standard Event	Sign Up	airbridge.user.signup
Standard Event	Sign In	airbridge.user.signin
Standard Event	Sign Out	airbridge.user.signout
Standard Event	View Home	airbridge.ecommerce.home.viewed
Standard Event	View Product List	airbridge.ecommerce.productList.viewed
Standard Event	View Search Result	airbridge.ecommerce.searchResults.viewed
Standard Event	View Detailed Product	airbridge.ecommerce.product.viewed
Standard Event	Add To Cart	airbridge.ecommerce.product.addedToCart
Standard Event	Purchase	airbridge.ecommerce.order.completed
Standard Event	Ad Impression	airbridge.adImpression
Standard Event	Subscribe	airbridge.subscribe
Standard Event	Unsubscribe	airbridge.unsubscribe
Standard Event	Schedule	airbridge.schedule
Standard Event	Unlock Achievement	airbridge.unlockAchievement
Standard Event	Ad Click	airbridge.adClick
Standard Event	Add to Wishlist	airbridge.addToWishlist
Standard Event	Share	airbridge.share
Standard Event	Complete Tutorial	airbridge.completeTutorial
Standard Event	Achieve Level	airbridge.achieveLevel
Standard Event	Add Payment Info	airbridge.addPaymentInfo
Standard Event	Initiate Checkout	airbridge.initiateCheckout
Standard Event	Spend Credits	airbridge.spendCredits
Standard Event	Start Trial	airbridge.startTrial
Standard Event	Rate	airbridge.rate
Custom Event	Varies by advertiser	Varies 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.

• Airbridge Postback Specification

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).

Name	Type	Macro
Event Datetime	string	{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.

Name	Type	Macro
Airbridge Device ID	string	{device.deviceUUID}
Airbridge Device ID Type	string	{device.deviceUUIDType}
GAID	string	{device.gaid}
IDFA	string	{device.ifa}

[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.

Name	Type	Parameter Name
Product ID	string	eventData.goal.semanticAttributes.product[0].productID
Product Name	string	eventData.goal.semanticAttributes.product[0].name
Product Price	float	eventData.goal.semanticAttributes.product[0].price
Product Quantity	int	eventData.goal.semanticAttributes.product[0].quantity
Product Currency	string	eventData.goal.semanticAttributes.product[0].currency
Product Position	int	eventData.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.*}

JSON

[ 
{@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": {product.name} 
	}, 
{@endfor} 
]

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.

Example)
Postback URL Template:
https://api.example-ad-channel.com/postback/airbridge?touchpoint_id={attributionResult.attributedClickID}& ad_channel={attributionResult.attributedChannel}&event_timestamp={eventTimestamp}&customID={@trackin gLink.custom_param}
→
Actual Postback:
https://api.example-ad-channel.com/postback/airbridge?touchpoint_id=e7580180-7f04-11e6-bdf4-0800200c 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.