Singular can send real-time notifications about app installs, re-engagements, in-app events and any other events to your BI platform. These notifications, known as internal BI postbacks (or callbacks), can be set up through the Partner Configuration page.
- For configuring postbacks to your partner networks, see How to Configure an Attribution Partner.
- To understands what postbacks will look like for Facebook, Google, Apple, Snapchat, Twitter, and Yahoo campaigns, see Internal BI Postbacks from Self-Attributed Networks: Field Mapping and Examples.
Troubleshooting
I've configured internal BI postbacks. How can I check if they are being sent successfully?
To view a log of the postbacks sent by Singular:
- In Singular, go to Attribution > Export Logs and select the relevant date range and the Postbacks log type.
- In the list of fields to be included in the log, make sure to select Response HTTP Code and Response HTTP Body.
- In the download file, check if the postbacks were sent successfully, and if not, see if you can identify why:
- The Response HTTP Code field tells you if the postback was delivered successfully. A 200 code means success; other values mean there was an error. When there's an error in sending, Singular retries the postback 5 more times, in intervals of 1, 5, 15, 30, and 60 minutes.
- The Response HTTP Body field may include additional details about the error.
If there is a problem, check your settings and contact Singular support.
Note: Singular doesn’t control how the data is processed in your platform. The data you see in the logs is the same data that Singular sent as postbacks to your BI.
FAQ
What do I need to consider before setting up internal BI postbacks?
Your system needs to be able to receive postbacks (also known as callbacks) 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.
- For an up-to-date list of IP addresses postbacks are sent from, see Postback Server IP Addresses.
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 | Whether the attribution is deterministic (device ID matching), probabilistic (Android only), or none (null value indicates an organic install). | 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 |
