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 | Snapchat | Yahoo | ||
|---|---|---|---|---|---|---|
| Network name in Singular: | (multiple values) e.g. Google Search, Google Display | iOS Search Ads | Snapchat | 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 |
|
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. |
|
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. |
