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 |
| network_tiktok_restricted | For view-through campaigns, subject to restrictions based on TikTok Ads' terms of service | string |
| campaign | Campaign name as specified in Attribution Tracking Tags | string |
| campaign_group | Campaign Group Name (available for certain Self-Attributing Partners) | string |
| campaign_tiktok_restricted | For view-through campaigns, subject to restrictions based on TikTok Ads' terms of service | 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 |
What are the different revenue events (__IAP__, __REVENUE__, __ADMON_ USER_LEVEL_REVENUE__)? Which one(s) should I configure postbacks for?
In the In-App (SDK) Events dropdown, you will see several different revenue-related events, some of which are overlapping.
To prevent duplicate postbacks being sent for the same in-app event follow the instructions below.
| Revenue Event Name |
Description |
|
__IAP__ |
An event triggered by any in-app purchases that have not been given a custom name in the SDK/S2S implementation. |
|
(Custom revenue events) |
In-app purchase events that have been given custom names in the SDK/S2S implementation also appear in the list. |
| __ADMON_ USER_LEVEL_REVENUE__ | An event triggered by revenue gained from ad monetization (if you have set up ad revenue attribution using the method of sending SDK events). |
| __REVENUE__ |
An event triggered by any revenue coming into the app (including __IAP__, purchase events with custom names, and ad revenue events). See warning below. |
What to do if you have only in-app purchase revenue:
- Set up mappings for __IAP__ and any custom purchase events.
- Or, alternatively, use __REVENUE__, which encompasses all your in-app purchase events.
What do do if you have both in-app purchase revenue and ad revenue:
- Set up mappings for __IAP__, any custom purchase events, and __ADMON_USER_LEVEL_REVENUE__.
- We don't recommend using the general event __REVENUE__ in this case, as it includes both purchases and ad revenue events, and mapping both types of revenue to the same revenue event on the network side may cause problems.
- Instead, map in-app purchase events to the network's purchase event, and the __ADMON_USER_LEVEL_REVENUE__ event to the network's admon or ad revenue event.
- If you're not sure what events to use on the network's side, contact the network for details.
Warning: If your existing configuration for a partner is sending __REVENUE__ postbacks, and you are starting to have ad revenue events in addition to in-app purchase events, this may cause problems if the partner network is not set up to receive ad revenue events or needs them to be mapped to a separate event. Check with the network to see if and how you should send ad revenue postbacks.
