Singular integration plan
Note that data generated by third-party data integration counts toward the cluster's data consumption
Summary
Interface overview
| Interface | Type | Granularity | Attribution | Cost | Revenue | Impressions | Clicks | Conversions |
|---|---|---|---|---|---|---|---|---|
| Internal BI Postbacks | Callback | User level | ✅ | ✅ | ✅ |
Singular provides a partner postback feature, which you can use to send back user-level data, including attribution data, ad revenue, and conversion data
Before you start connecting Singular data, make sure that you have read the AE system's user identification rules and understand how AE identifies a user through #distinct_id and #account_id
Integration process
- Integrate the Singular client SDK and the AE client SDK, and set the AE user identification ID in the Singular SDK
- Log in to the AE backend, go to the Third-party Integration module, add a Singular postback plan, complete the related configuration, and get the callback URL
- Add an Internal BI postback in the Singular dashboard
- Check whether the AE system receives the data successfully, and build reports
1. Client SDK configuration
To connect Singular callback data with user data in the AE project, report the account ID and distinct ID of the AE project in the Singular SDK.
We strongly recommend that you initialize the AE SDK first, and set the distinct ID of the AE SDK as Singular's custom user ID when you initialize the Singular SDK. The following is a code sample for Android:
// Initialize the AE SDK
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);
// Get the AE distinct ID, which corresponds to #distinct_id in AE
String te_distinct_id = TDAnalytics.getDistinctId();
// Pass the AE distinct ID in SingularConfig as the custom user ID, and initialize
SingularConfig config = new SingularConfig("SDK KEY","SDK SECRET")
.withCustomUserId(te_distinct_id);
Singular.init(context, config);
2. Plan configuration
After completing the SDK configuration, log in to the AE backend and configure the Singular plan in the Third-party Integration module. The image below shows the configuration page of the Singular Internal BI Postbacks plan:
2.1 User identification fields
Because Singular Internal BI Postbacks data is user-level data, you need to set user identification rules for it, that is, the AE system's user identification ID set in the Singular SDK. Based on this configuration, the AE system sets these fields as the user identification fields of the data when it converts the callback data.
If you configured the client SDK as described in the previous step of this document, use the following configuration:
- Field associated with the account ID: none
- Field associated with the distinct ID: user_id
2.2 Event Data Configuration
After you turn on the Event Data Configuration switch, all data sent back by Singular is written to the event table. We recommend that you enable event data ingestion.
2.3 User Properties Configuration
By default, the AE system does not write Singular data to user properties. To write some fields, such as user attribution fields, to the user table, first turn on the rule so that it runs, and then use the property mapping feature to add the fields to write to the user table. For the source property name, enter the field's ingested name:
We recommend that you set the user property ingestion rule as follows:
- Turn off Include all events
- Source event name: singular_install
- Ingestion rule: user_setOnce
- Configure the property fields as follows:
| Source data name | Target property name | Description |
|---|---|---|
| network | te_ads_object.media_source | Media source |
| tracker_campaign_name | te_ads_object.campaign_name | Campaign name |
| tracker_sub_campaign_name | te_ads_object.ad_group_name | Ad group name |
| tracker_creative_name | te_ads_object.ad_name | Ad name |
2.4 Configuration
In the Configuration module, you can control the detailed settings of data pulling, such as the event name after ingestion
The content of the configuration is a JSON, which you can customize as follows:
| Module | Name | Description |
|---|---|---|
| sink_event | event_mapping | Event name after ingestion. Customizable. The key is the event name in the Singular callback data, and the value is the event name after ingestion. Events not listed here are ingested with the singular_ prefix added to their event names in the callback data |
2.5 End Point
End Point shows the URL where the AE system receives Singular callback data. Copy this URL directly, and enter it when you configure the Singular postback in the next step:
If no URL is displayed here, open Project Settings → Settings → Implementation from the menu in the upper-right corner and configure the URL for public network. This URL is the data reporting URL configured in the AE SDK. After configuring it, go back to End Point on the Singular configuration page and copy the endpoint URL.
Finally, remember to click the save button in the upper-right corner to save the Singular plan.
3. Configure callbacks and data ingestion
3.1 Configure callbacks
After creating the Singular plan, log in to the Singular dashboard and go to the Attribution > Partner Configuration page. In the field for adding a channel partner, search for Thinking Data and click it to start adding the postback configuration for the AE system.
Go to the Configuration page and first select the App and Site to send back data for
Next, enter the callback URL of the Singular integration plan in the AE system in Postback URL
Finally, Singular sends back install events (install) and re-engagement events (Re-Engagement) by default. If you also have in-app events to send back, switch to the In app Events Postback tab at the top and add the events to send back in the list below. For revenue events, select them in the Revenue Events Postbacks menu:
Note: The SDK event list includes the following revenue event options:
-
__IAP__ refers to all in-app purchase events without custom names
-
Revenue events displayed directly by event name are in-app purchase events that have been renamed
-
__ADMON_USER_LEVEL_REVENUE__ refers to ad revenue events (if you have configured Ad Revenue Attribution)
-
__REVENUE__ includes:
- All in-app purchase events (including __IAP__ and custom in-app purchase events)
- Ad revenue events (if you have configured Ad Revenue Attribution)
- It also combines all revenue data into a single event for the postback
When configuring postbacks, check whether in-app purchase events have already been reported through the AE SDK. If they have, we do not recommend sending back __IAP__ or other in-app purchase events from Singular, to avoid duplicate data
In addition, because __REVENUE__ combines all revenue events into one event, if your project records both in-app purchase events and ad revenue events, we recommend configuring each revenue event separately instead of configuring __REVENUE__, so that you can better distinguish in-app purchase data from ad monetization data
3.2 Event ingestion rules
-
The user_id field in the data is used as the user's distinct ID
-
The event_utc_timestamp field in the data, that is, the time when the event occurred, is used as the #event_time of the data
-
The data event name is the event_name in the data with the singular_ prefix added. Unnamed revenue events are named as follows:
- __IAP__：singular_iap
- __ADMON_ USER_LEVEL_REVENUE__：singular_ad_revenue
- __REVENUE__：singular_revenue
-
All other fields are ingested. The following are the fields sent back by Internal BI Postbacks:
| Field | Description |
|---|---|
| app_name | App name |
| longname | Bundle ID of the app |
| platform | Operating system. Valid values: iOS or Android |
| event_name | Event name |
| idfa | IDFA on iOS |
| idfv | IDFV on iOS |
| aifa | Advertising ID of the Android device |
| android_id | Android ID. Reported only when AIFA is unavailable |
| singular_id | (Deprecated) Reported only when the iOS device limits data tracking (LAT enabled); uses the Singular internal ID |
| event_utc_timestamp | UNIX timestamp when the event occurred |
| click_utc_timestamp | UNIX timestamp of the click |
| install_utc_timestamp | UNIX timestamp of the install |
| is_organic | 1 means the user is organic; 0 means the user is non-organic |
| is_viewthrough | 1 means the user is view-through attributed; 0 means otherwise |
| network | Media source the user is attributed to |
| campaign | Campaign name identified by Singular |
| campaign_group | Campaign group name identified by Singular (available for some platforms) |
| creative | Creative name or creative ID identified by Singular |
| site | Source site & Sub Site for click. Available if passed in click |
| user_id | Custom user ID. Based on the configuration in 2.1, the value should equal the AE system's distinct ID |
| singular_click_id | Unique click ID generated by Singular |
| is_reengagement | 1 means the user returned through a re-engagement ad; 0 means otherwise |
| click_ip | IP address when the ad was clicked |
| os_version | OS version when the ad was clicked |
| app_version | App version at install or when the event occurred |
| country | Country (region) of the user at install |
| city | City of the user at install |
| limit_ad_tracking | 1 means limit ad tracking is enabled; 0 means otherwise |
| device_model | Device model |
| device_brand | Device brand |
| match_type | Attribution match type. Valid values: deterministic (device ID match, exact match), probabilistic (Android only, fuzzy match), or none (organic). |
| amount | Sent back only for revenue data. Revenue value in USD |
| currency | Sent back only for revenue data. ISO 4217 three-letter currency code of the revenue currency |
| is_first_event | 1 means the event (revenue or custom event) is the first event of the device; 0 means it is not the first event |
| tracker_campaign_name | Campaign name sent back by the network |
| tracker_campaign_id | Campaign ID sent back by the network |
| tracker_sub_campaign_name | Sub-campaign name sent back by the network |
| tracker_sub_campaign_id | Sub-campaign ID sent back by the network |
| tracker_creative_name | Creative name sent back by the network |
| tracker_creative_id | Creative ID sent back by the network |
| tracker_publisher_id | Hashed app ID sent back by the network |
| tracker_publisher_sub_id | Publisher SUB ID sent back by the network |
| tracker_publisher_site_name | App name sent back by the network |
| tracker_publisher_site_id | App ID sent back by the network |
| tracker_publisher_sub_site_name | Sub-publisher name sent back by the network |
| tracker_publisher_sub_site_id | Sub-publisher ID sent back by the network |
| tracker_name | Tracked campaign name |
| network_tiktok_restricted | This restricted field is present in view-through attributed user data from TikTok. See the appendix for details |
| campaign_tiktok_restricted | This restricted field is present in view-through attributed user data from TikTok. See the appendix for details |
| fb_campaign_id | Facebook campaign ID. Subject to Facebook's terms of service. See the appendix for details |
| fb_campaign_name | Facebook campaign name. Subject to Facebook's terms of service. See the appendix for details |
| fb_adset_id | Facebook Ad Set (ad group) ID. Subject to Facebook's terms of service. See the appendix for details |
| fb_adset_name | Facebook Ad Set (ad group) name. Subject to Facebook's terms of service. See the appendix for details |
| fb_ad_id | Facebook ad ID. Subject to Facebook's terms of service. See the appendix for details |
| fb_ad_name | Facebook ad name. Subject to Facebook's terms of service. See the appendix for details |
| twitter_campaign_name | Twitter campaign name. Subject to Twitter's terms of service. See the appendix for details |
| twitter_campaign_id | Twitter campaign ID. Subject to Twitter's terms of service. See the appendix for details |
| twitter_line_id | Twitter Line Item (ad group) ID. Subject to Twitter's terms of service. See the appendix for details |
| fraud_status | Fraud detection result. Sent back only when fraud postbacks are enabled. Valid values: "valid"/"suspicious"/"rejected" |
| fraud_reason | Name of the rule that identified the data as fraudulent. Sent back only when fraud postbacks are enabled |
3.3 Standardized fields
The AE system standardizes some fields in the Singular callback data:
| Field | Standardized field | Description |
|---|---|---|
| app_name | te_ads_object.app_name | App name |
| longname | te_ads_object.app_id | App ID |
| platform | te_ads_object.platform | Platform, such as Android or iOS |
| country | te_ads_object.country | Country or region code |
| amount | te_ads_object.revenue | Monetization revenue |
| currency | te_ads_object.currency | Revenue currency |
| network | te_ads_object.media_source | Media source |
| tracker_campaign_name | te_ads_object.campaign_name | Campaign name |
| tracker_campaign_id | te_ads_object.campaign_id | Campaign ID |
| tracker_sub_campaign_name | te_ads_object.ad_group_name | Ad group name, or the Unit name for monetization ads |
| tracker_sub_campaign_id | te_ads_object.ad_group_id | Ad group ID, or the Unit ID for monetization ads |
| tracker_creative_name | te_ads_object.ad_name | Ad name |
| tracker_creative_id | te_ads_object.ad_id | Ad ID |
4. Appendix
Some platforms restrict sending user-level data to other third-party platforms, including sending it to the AE system through Internal BI Postbacks. The following table shows the restriction rules of these platforms:
| Platform | Restriction rule |
|---|---|
| Facebook user-level data is deleted 6 months after attribution, so 6 months after attribution, users attributed to Facebook are marked as "Organic" in Singular. In addition, the end-user agreement does not allow obtaining user-level data for Facebook view-through attribution, so the attribution information of users attributed to Facebook through view-through is marked as "Unattributed" | |
| Google Ads (Adwords) | Google Ads user-level data is deleted 6 months after attribution, so 6 months after attribution, users attributed to Google Ads are marked as "Organic" in Singular |
| Snapchat | Snapchat's data sharing policy prohibits sharing any Snapchat data with third parties |
| TikTok | TikTok user-level data is deleted 6 months after attribution, so 6 months after attribution, users attributed to TikTok are marked as "Organic" in Singular. In addition, the end-user agreement does not allow obtaining user-level data for TikTok view-through attribution, so from 2022-05-02 onward, the attribution information of users attributed to TikTok through view-through is marked as "TikTok Restricted" |
Make sure that your Twitter endpoint is eligible to receive Twitter's device-level attribution data Twitter user-level data is deleted 6 months after attribution, so 6 months after attribution, users attributed to Twitter are marked as "Organic" in Singular. In addition, Twitter end users have the right to have their data deleted from third parties. Their data does not appear in user-level data but is still counted in aggregated data |