Configuring Internal BI Postbacks

Setup Instructions

To activate postbacks to your internal BI platform, log into your Singular account, go to Attribution > Partner Configuration, and select the Internal BI partner.

In the configuration window, make sure to provide a postback URL (e.g., https://my_company_name.com/bi/event_endpoint?app=12). This is where Singular will send the postback through a POST request.

Note that some networks have special limitations on data sharing.

Postback Structure

Singular sends postbacks as a JSON object with the following fields:

Key Value  
app_name Display Name of application string
longname Long name (bundle ID) of application string
platform iOS or Android string
event_name Name of the event. Some events sent in postbacks are auto-tracked or generated events. These events include installs, sessions, uninstalls, reinstalls, and revenue events. See Auto-Tracked Events. string
idfa Unhashed iOS advertising identifier of device string
idfv Unhashed iOS identifier for vendor string
aifa Unhashed Android advertising identifier of device string
android_id Unhashed Android ID. Available only if aifa (android advertising ID) is not available string
singular_id Deprecated - Used when LAT is enabled for iOS devices. Use IDFV. Singular internal ID string
event_utc_timestamp Event UNIX Timestamp number
click_utc_timestamp Click UNIX Timestamp number
install_utc_timestamp Install UNIX Timestamp number
is_organic 1 if event is Organic, 0 if attributed number
is_viewthrough 1 if attributed event is a view-through conversion, 0 otherwise number
network Name of network to which install is attributed, when available string
campaign Campaign name as specified in Attribution Tracking Tags string
campaign_group Campaign Group Name (available for certain Self-Attributing Partners) string
tracker_campaign_name Campaign Name as passed by the network. Available if passed in click in the pcn string
tracker_campaign_id Campaign ID as passed by the network. Available if passed in click in the pcid string
tracker_sub_ campaign_name Sub-campaign name as passed by the network. Available if passed in click in the pscn string
tracker_sub_ campaign_id Sub-campaign ID as passed by the network. Available if passed in click in the pscid string
tracker_creative_name Campaign creative name as passed by the network. Available if passed in click in the pcrn string
tracker_creative_id Campaign creative ID as passed by the network. Available if passed in click in the pcrid string
tracker_publisher_id Publisher ID as passed by the network. Available if passed in the click in ps string
tracker_publisher_ sub_id Publisher SUB ID as passed by the network. Available if passed in the click in pssn string
tracker_publisher_ site_name Publisher name as passed by the network. Available if passed in click in the psn string
tracker_publisher_ site_id Publisher ID as passed by the network. Available if passed in click in the psid string
tracker_publisher_ sub_site_name Sub-publisher name as passed by the network. Available if passed in click in the pssn string
tracker_publisher_ sub_site_id Sub-publisher ID as passed by the network. Available if passed in click in the pssid string
tracker_name Campaign name as specified in Attribution Tracking Tags string
partner_campaign Deprecated - Use tracker_campaign_name or tracker_campaign_id Campaign ID or Name as passed by the network. Available if passed in click string
partner_sub_campaign Deprecated - Use tracker_sub_campaign_name or tracker_sub_campaign_id Sub Campaign Name or ID as passed by the network. Available if passed in click string
partner_site Deprecated - Use tracker_publisher_site_name or tracker_publisher_site_id Source site or application for click. Available if passed in click string
partner_sub_site Deprecated - Use tracker_publisher_sub_site_name or tracker_publisher_sub_site_id Source sub site or application for click. Available if passed in click string
creative Creative Name or ID. Available only if provided in click string
site Source site & Sub Site for click. Available if passed in click string
user_id Custom user ID. Available if passed by the SDK string
singular_click_id Singular assigned click ID string
is_reengagement Will return '1' if attributed to a re-engagement campaign, '0' if not number
click_ip IP of the device at the time of the clicked ad string
os_version OS version of the device at the time of the clicked ad string
app_version App version of the device at the time of the install/event number
country Country from which user installed string
city City from which user installed string
limit_ad_tracking Do not track flag is set active will return '1', all other conditions will return '0' number
device_model Device model string
device_brand Device Brand string
match_type Indicates whether and attribution is Organic (null value), deterministic (device id matching) or with fingerprinting methodology string
amount Revenue event postbacks only - The transaction amount in dollars and cents number
currency Revenue event postbacks only - The three-letter ISO 4217 currency code for the transaction string
is_first_event Returns '1' for first occurrence of an event (revenue or custom), '0' for every subsequent event from the same device ID number
fb_campaign_id Numeric Facebook Campaign ID. Subject to restrictions based on Facebook's terms of service number
fb_campaign_name Facebook Campaign name. Subject to restrictions based on Facebook's terms of service string
fb_adset_id Numeric Facebook Ad Set ID. Subject to restrictions based on Facebook's terms of service number
fb_adset_name Facebook Ad Set name. Subject to restrictions based on Facebook's terms of service string
fb_ad_id Numeric Facebook Ad ID. Subject to restrictions based on Facebook's terms of service number
fb_ad_name Facebook Ad name. Subject to restrictions based on Facebook's terms of service string
twitter_campaign_name Twitter Campaign Name. Subject to restrictions based on Twitter's terms of service string
twitter_campaign_id Twitter alphanumeric Campaign ID. Subject to restrictions based on Twitter's terms of service string
twitter_line_id Twitter alphanumeric Line Item ID. Subject to restrictions based on Twitter's terms of service string
fraud_status Fraud decision for installation. Available only when fraud postbacks are enabled. Possible values are "valid"/"suspicious"/"rejected" string
fraud_reason Name of rule that decided the fraud status (for example, the name of the rule that rejected the install). Available only when fraud postbacks are enabled. string

Field Mapping for Self-Attributed Networks

The data that Singular gets from self-attributed networks (SANs), such as Facebook and Twitter,  reflects the network's individual reporting hierarchy. Singular standardizes the data by mapping it to Singular's reporting hierarchy before passing it on to you through BI postbacks.

The table below contains the details of the mapping. Reference it when you build your data processing pipeline in the BI platform.

Note that values are only populated when they are provided by the network. For example, creative_id may only be available for certain campaign types.

Partner Name: Google Ads (AdWords) Apple Search Ads Facebook Snapchat Twitter Yahoo
Network name in Singular: (multiple values) e.g. Google Search, Google Display iOS Search Ads Facebook Snapchat Twitter Yahoo Gemini
tracker_ campaign_ name campaign_name iad-campaign-name Campaign Name campaign_name campaign_name campaign_name
tracker_ campaign_ id campaign_id iad-campaign-id Campaign ID campaign_id campaign_id campaign_id
tracker_sub_ campaign_ name   iad-adgroup-name AdSet Name ad_squad_name   adgroup_name
tracker_sub_ campaign_id adgroup_id iad-adgroup-id AdSet ID ad_squad_id line_item_id adgroup_id
tracker_ creative_ name     Ad Name ad_name   creative_name
tracker_ creative_ id creative_id or video_id   Ad ID ad_id tweet_id creative_id
tracker_ publisher_ id placement   "Facebook", "Instagram", "Audience Network"   publisher_app_id  
tracker_ publisher_ site_ name     "Facebook", "Instagram", "Audience Network"      
tracker_ publisher_ site_ id placement       publisher_app_id  

Sample Postback Data

The following are some examples of JSON objects you may receive in postbacks. Note that if a piece of data is not present (not made available by the partner to Singular), the key (column) is not provided in the postback.

Sample Postback: Source - AdWords
{
  "aifa": "123456-abcd-4821-8011-0e9f189a6f27",
  "amount": 0,
  "app_name": "MyAppName",
  "app_version": "3.2.1",
  "campaign": "1234567 - Bidalgo_Android_UAC_tCPA_US_12345 (555-555-5555)",
  "campaign_group": "N/A",
  "city": "San Francisco",
  "click_ip": "10.77.202.1",
  "click_utc_timestamp": 1523845213,
  "country": "US",
  "creative": "N/A",
  "currency": "USD",
  "device_brand": "samsung",
  "device_model": "SM-G965U",
  "event_name": "registration",
  "event_utc_timestamp": 1558611339,
  "install_utc_timestamp": 1523845519,
  "is_first_event": 0,
  "is_organic": 0,
  "is_reengagement": 0,
  "is_viewthrough": 0,
  "limit_ad_tracking": 0,
  "longname": "com.singular.MyAppName",
  "match_type": "deterministic",
  "network": "Google Search - UAC",
  "os_version": 9,
  "partner_site": "GoogleSearch",
  "platform": "Android",
  "singular_click_id": "Q2425hH3_btICGtsxnjhC-xKXin4dF4Xex_mFkdbZGUjnULllQRyzKmovfrnbo9JS94aIulUX9Hdi0771u-mQ",
  "site": "GoogleSearch",
  "tracker_name": "1234567 - Bidalgo_Android_UAC_tCPA_US_12345 (555-555-5555)",
  "user_id": "8934570q38-283c-4adc-b96c-214280222d69",
  "fraud_status": "valid",
  "fraud_reason": ""
}
Sample Postback: Source - Apple Search Ads
{
  "amount": 0,
  "app_name": "MyAppName",
  "app_version": "3.2.0",
  "campaign": "UK:12345639",
  "campaign_group": "brand_exact_copy:12341801",
  "city": "London",
  "click_ip": "10.132.219.1",
  "click_utc_timestamp": 1518649915,
  "country": "GB",
  "creative": "-:-",
  "currency": "USD",
  "device_brand": "Apple",
  "device_model": "iPhone8,2",
  "event_name": "__START__",
  "event_utc_timestamp": 1558594525,
  "idfa": "92dfsd872D18-4433-4D65-8239-7A9454551C17",
  "idfv": "1dsdfdsf984-749B-4FB5-A5B4-8FD0B252D8900",
  "install_utc_timestamp": 1518649971,
  "is_first_event": 0,
  "is_organic": 0,
  "is_reengagement": 0,
  "is_viewthrough": 0,
  "limit_ad_tracking": 0,
  "longname": "com.singular.MyAppName",
  "match_type": "deterministic",
  "network": "iOS Search Ads",
  "os_version": 12.2,
  "partner_site": "MyAppName",
  "platform": "iOS",
  "singular_click_id": "bKcOHKO23602895pJHHOYUIG392rjbhLKJDJbFIFleEwaST3sGkHV8wgyxrLf8KtuVayjH2hyXjFFUvkqSxJ66qUYUI2WqTJ9wmnH0hlLNZKzbXXi8",
  "site": "MyAppName",
  "tracker_name": "UK:12345639",
  "user_id": "aj3jgljg-867c-4d6f-aa56-e35cadfdfdb17",
  "fraud_status": "valid",
  "fraud_reason": ""
}
Sample Postback: Source - Facebook
{
  "aifa": "a987598598-c892-4a69-8abc-fec93c993988",
  "amount": 0,
  "app_name": "MyAppName",
  "app_version": "3.2.0",
  "campaign": "Singular_Android_ABC-NonUS:1234567894420770",
  "campaign_group": "Singular_Android_AutoBid_VO_FB-AllCreatives_24-45_M_1day_ROAS1%:12345678910111213",
  "city": "Santiago de Cali",
  "click_ip": "67.49.84.32",
  "click_utc_timestamp": 1557433018,
  "country": "CO",
  "creative": "Singular_LightVsDarkUI_Video_30s_Square:1234abcd5678",
  "currency": "USD",
  "device_brand": "samsung",
  "device_model": "SM-A520F",
  "event_name": "LevelUp",
  "event_utc_timestamp": 1558627132,
  "fb_ad_id": 1234abcd5678,
  "fb_ad_name": "Singular_LightVsDarkUI_Video_30s_Square",
  "fb_adset_id": 12345678910111213,
  "fb_adset_name": "Singular_Android_AutoBid_VO_FB-AllCreatives_24-45_M_1day_ROAS1%",
  "fb_campaign_id": 1234567894420770,
  "fb_campaign_name": "Singular_Android_ABC-NonUS",
  "install_utc_timestamp": 1557433113,
  "is_first_event": 0,
  "is_organic": 0,
  "is_reengagement": 0,
  "is_viewthrough": 0,
  "limit_ad_tracking": 0,
  "longname": "com.Singular.MyAppName",
  "match_type": "deterministic",
  "network": "Facebook",
  "os_version": "8.0.0",
  "partner_campaign": 1234567894420770,
  "partner_site": "Facebook",
  "partner_sub_campaign": 12345678910111213,
  "platform": "Android",
  "singular_click_id": "sddjhhasdf7a6498y42jbasdjfhp9804r5WqHobec5AbSaHocUAbU4XAe72FMaoE0oYkEeMNOMaFjgn8xYgV6v9F3BqRo9VXUZ-095083c",
  "site": "Facebook",
  "tracker_campaign_id": 1234567894420770,
  "tracker_campaign_name": "Singular_Android_ABC-NonUS",
  "tracker_creative_id": 1234abcd5678,
  "tracker_creative_name": "Singular_LightVsDarkUI_Video_30s_Square",
  "tracker_name": "Singular_Android_ABC-NonUS:1234567894420770",
  "tracker_publisher_id": "Facebook",
  "tracker_publisher_site_name": "Facebook",
  "tracker_sub_campaign_id": 12345678910111213,
  "tracker_sub_campaign_name": "Singular_Android_AutoBid_VO_FB-AllCreatives_24-45_M_1day_ROAS1%",
  "user_id": "0f496ff6-c7f7-4633-899a-7610259861058",
  "fraud_status": "valid",
  "fraud_reason": ""
}
Sample Postback: Source - IronSource
{
  "amount": 0,
  "app_name": "MyAppName",
  "app_version": "3.2.1",
  "campaign": "MyAppName_iOS_DeviceAssist_setup",
  "campaign_group": "MyAppName_iOS_DeviceAssist_setup",
  "city": "Napa",
  "click_ip": "17.120.49.42",
  "click_utc_timestamp": 1558525701,
  "country": "UA",
  "creative": 66775,
  "currency": "USD",
  "device_brand": "Apple",
  "device_model": "iPhone9,3",
  "event_name": "__SESSION__",
  "event_utc_timestamp": 1558597538,
  "idfa": "4251434ew-C312-477D-9766-927744B09A38",
  "idfv": "sdaf32337-5D5D-4ED2-B1F2-8C35A6C98946",
  "install_utc_timestamp": 1558597538,
  "is_first_event": 1,
  "is_organic": 0,
  "is_reengagement": 0,
  "is_viewthrough": 0,
  "limit_ad_tracking": 0,
  "longname": "com.singular.MyAppName",
  "match_type": "deterministic",
  "network": "ironSource",
  "os_version": 12.2,
  "partner_campaign": 345678,
  "partner_site": "Idle World !",
  "platform": "iOS",
  "singular_click_id": "L5X9RN9urXZrtxdduVd_gt2A3gOggW-7Wev3U8-ehfDgfse35hppwuvfDXTc8n_dsq5rTYrSd7nyUISAehxyD6LBov-uW5Cn0iY1vgkZgEg",
  "site": "236335_",
  "tracker_campaign_id": 345678,
  "tracker_campaign_name": "Focus_iOS_CPI_RON_10+_T3T4_Video",
  "tracker_creative_id": 66775,
  "tracker_creative_name": "Influencer_720x1280_30s",
  "tracker_name": "MyAppName_iOS_DeviceAssist_setup",
  "tracker_publisher_id": "World1",
  "tracker_publisher_site_id": "com.someapp.game",
  "tracker_publisher_site_name": "SomeApp Game",
  "fraud_status": "valid",
  "fraud_reason": ""
}

Data Sharing Policies

Some partners limit access to user-level data to third parties, and this includes data passed in internal BI postbacks. In order to be able to get data from the following partners, note the following conditions:

Source Name Conditions
Facebook

You have to accept the Facebook advanced mobile measure agreement on your tracked Facebook apps.

Facebook user-level data is removed after 6 months of original attribution.  After 6 months, users attributed to Facebook as treated/marked as "Organic" and reflected as such in both aggregate and user-level reporting in Singular.

Acess to user-level view-through data is not allowed in the interest of protecting end-user privacy.  Any fields normally identifying an attributed Facebook view-through attribution is marked as "Unattributed" for any data porocessed after April 22nd, 2020.  

Google Ads (Adwords)

Google Ads user-level data is removed after 6 months of original attribution.  After 6 months, users attributed to Google Ads as treated/marked as "Organic" and reflected as such in both aggregate and user-level reporting in Singular.

Twitter

Ensure with your Twitter point of contact that your Twitter ad account is eligible to receive device-level attributed Twitter data.

Twitter user-level data is removed after 6 months of original attribution.  After 6 months, users attributed to Twitter as treated/marked as "Organic" and reflected as such in both aggregate and user-level reporting in Singular.

Twitter's end-users have the ability to opt out of sharing data with thirds parties.  Singular respects this value by not reporting these users as attributed to Twitter in user-level data (BI postbacks, exports), but they are still included in aggregate reporting.

Snapchat

Snapchat data sharing policies prevent the sharing of "Snapchat data" to third parties. "Snapchat data" encompasses any data pertaining to an advertising ID belonging to a Snapchat user.

Was this article helpful?