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.

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.

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.*}

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