Singular can send notifications about app installs, re-engagements, and in-app events to your BI platform in real time. These notifications are known as "internal BI postbacks" and you set them up through the Partner Configuration page.
- For the details of configuring postback options, see How to Configure an Attribution Partner.
- For how Singular maps data from Facebook, Google, Apple, Snapchat, Twitter, and Yahoo, see Internal BI Postbacks from Self-Attributed Networks: Field Mapping and Examples.
What do I need to consider before setting up internal BI postbacks?
Your system needs to be able to receive the postbacks and ingest the data properly. Make sure a technical team member is involved in the planning.
Note: There are other ways to get user-level attribution data from Singular:
- Downloading logs (see Export Logs and User-Level Data FAQ)
- Setting up data destinations to export your user-level data regularly from Singular to your system (see Singular Data Destinations (ETL) FAQ)
How do I set up internal BI postbacks?
- 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.
- Configure the other postback settings the same way you would for a partner postback (see How to Configure an Attribution Partner).
Note that some networks have special limitations on data sharing.
How are postbacks sent? How often does Singular retry sending if there was a problem?
- Singular makes an HTTP POST request with the data payload in JSON format (see structure below).
- If Singular receives an HTTPS response code between 500 and 599, it retries sending the postback (there is a maximum of 5 retries).
- Retries are attempted after 1, 5, 15, 30, and 60 minutes from the original send attempt.
- Singular posbacks are attempted from an CIDR IP range of 198.134.6.0/23 which covers the all the IP addresses 198.134.6.0 through 198.134.7.255.
What is the structure of a Singular postback?
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 |
