Adjust data integration solution
Last updated: 2023-03-24
1. Integration plan overview
Note that data generated by third-party data integration counts toward the cluster's data consumption
Summary
This document describes how to send Adjust data back to Agentic Engine (hereinafter the AE system). This solution supports:
- Sending back user-level raw data through the real-time callback feature, covering conversion, monetization, and other data
- Sending back aggregated data through the Report Service API, covering impressions, clicks, costs, monetization, and other data
- If you plan to report raw data with real-time callbacks, read the AE system user identification rules to learn how AE identifies a user through
#distinct_idand#account_id. - If you plan to get aggregated results through Report Service, make sure you have read the AE system data rules and understand AE's data structure. We also recommend that you give the information needed to pull data to our customer success manager, using the format in the data integration configuration template.
Process
- If you use the real-time callback solution, follow this process to connect your data:
- Integrate the Adjust client SDK and the AE client SDK. Set the AE user identification ID in the Adjust SDK, and set the Adjust ID and the Android ID / IDFA / Web UUID in the AE SDK (we recommend reporting custom registration/character creation events in the Adjust SDK)
- In the Adjust dashboard, set up a global callback or single event callbacks
- ThinkingAI staff complete the data pull development, including retroactively linking user data
- Build dashboards and reports in the AE backend, and complete data validation
- If you use Report Service to send back aggregated data, follow this process:
- In the Adjust dashboard, get the Adjust User Token (API Token) and the Adjust App Token, and provide them to ThinkingAI staff
- Determine the data dimensions, metric types, time range, and time granularity to pull
- ThinkingAI staff complete the data pull development
- Build dashboards and reports in the AE backend, and complete data validation
2. Real-time callback solution
| Interface | API type | Productized | Data granularity | Attribution | Cost | Revenue | Impressions | Clicks | Conversions |
|---|---|---|---|---|---|---|---|---|---|
| Real-time callbacks | Push | Yes | User level | Yes | Yes | Yes |
Adjust provides real-time callbacks for a range of events. Select the data types to send back in the Adjust dashboard and set the AE system's callback link as the callback URL to receive detailed user-level data.
2.1 Configure the client SDK
2.1.1 Set the user ID
Option 1 (automatic association):
If the AE SDK version you integrated is 2.8.0~2.8.1, you can use this option directly
If the AE SDK version you integrate is 2.8.2 or later, you also need to install the third-party data plugin
For details, see Android SDK third-party data and iOS SDK third-party data
// Initialize the AE SDK
ThinkingAnalyticsSDK instance = ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID, TA_SERVER_URL);
// Enable Adjust ID association
instance.enableThirdPartySharing(TDThirdPartyShareType.TD_ADJUST);
// Initialize the Adjust SDK
// ...
// After registration or character creation, call login to set the account ID, then sync the data again (optional)
instance.login("account_id");
instance.enableThirdPartySharing(TDThirdPartyShareType.TD_ADJUST);
This option works by automatically calling the Adjust SDK's addSessionCallbackParameter() method internally to pass in the distinct ID and account ID of the AE project.
Option 2:
In this option, you manually call the Adjust SDK's addSessionCallbackParameter() method to set the distinct ID and account ID of the AE project.
// Get the AE distinct ID, which corresponds to #distinct_id in AE
String distinctId = ThinkingAnalyticsAPI.GetDistinctId();
// Your account ID (or character ID), which corresponds to #account_id in AE
String accountId = "{your_account_id}";
Adjust.addSessionCallbackParameter("ta_distinct_id", distinctId);
Adjust.addSessionCallbackParameter("ta_account_id", accountId);
// Initialize the Adjust SDK
// ...
To make sure the AE user IDs can be obtained correctly, don't use addCallbackParameter in the Adjust SDK to report the AE account ID and distinct ID again
2.1.2 Set a registration or character creation event (optional)
To make sure user binding works as expected, set a custom event based on the type of account ID you set in the AE SDK:
- If the account ID is the user's account ID: report the event with the Adjust SDK when the user creates an account
- If the account ID is a character ID (gaming industry): you can report the event with the Adjust SDK when the user creates a character
2.1.3 Web configuration
Because the web differs greatly from mobile, you need to get web_uuid in the Adjust Web SDK with the following code, report it through the AE SDK, and set it as a user property:
const webUUID = Adjust.getWebUUID();
Then, when you configure the callback link later, use the {web_uuid} placeholder in the callback so that the data can be associated with the user data of the AE project.
2.2 Configure the callback link
After you configure the client SDK, set up the real-time callback interface in the Adjust dashboard so that you can receive user-level detailed data from Adjust.
2.2.1 Choose a callback method
Adjust supports configuring a global callback as well as single event callbacks. Because ad revenue events don't support the global callback, we recommend that you configure a separate callback for each event.
The following are the events that Adjust supports for callbacks, and the events we recommend connecting:
| Event | Event name | Recommended |
|---|---|---|
| Impressions | impressions | |
| Clicks | clicks | |
| Install | install | Yes |
| Ad revenue (with Ad Revenue package) | ad revenue (with Ad Revenue package) | Yes |
| Ad spend | ad spend | |
| Conversations | sessions | |
| App events | app events | As needed |
| Reattributions | reattributions | |
| Uninstalls | uninstalls | |
| Reinstalls | reinstalls | |
| Reattribution reinstalls | reattribution reinstalls | |
| Updated attributions | updated attributions | |
| Erased users (GDPR) | erased users (GDPR) | |
| SAN clicks | SAN clicks | |
| SAN impressions | SAN impressions | |
| SKAdNetwork installs | SKAdNetwork installs | |
| SKAdNetwork events | SKAdNetwork events | |
| Subscriptions | subscriptions | |
| ATT status updates (iOS) | ATT status updates (iOS) | |
| Rejected installs | rejected installs | |
| Rejected reattributions | rejected reattributions |
2.2.2 Configure callback links
We recommend that you list all the events you need callbacks for in the data integration configuration template and send the template to ThinkingAI staff. ThinkingAI staff will send you the callback link for each event. Set each callback URL in the position marked by the red box in the image below.
2.2.3 Configure callback placeholders
A callback placeholder is an expression in a callback link that specifies a callback parameter, usually enclosed in {}. For example, the {campaign_name} placeholder means that the callback data will carry the value of campaign_name. Different callback data supports different placeholders. You can visit the Adjust placeholder documentation for more information. If you need to add placeholders, find the properties to add in the document above and specify them in the data integration configuration template.
2.3 Data ingestion rules
By default, we write the pulled data into the AE project as events, one event per callback record:
ta_distinct_idandta_account_idin the data are used as the user identification IDs of the AE project- The created_at_milli field in the data is used as the event's #event_time. If created_at_milli does not exist, the value of created_at is used as #event_time
- The event name is the Adjust event name with the prefix adjust_ (for example, the impression event is stored as adjust_impression)
- All other fields configured in the callback link are stored
By default, if ta_distinct_id and ta_account_id can't be obtained from the data, the record is treated as invalid and discarded. If you want to keep this data, contact ThinkingAI staff to configure it. This data is then recorded in the event table with the fixed distinct ID "without_id", and no user properties are stored for it
2.3.1 Link impression, click, and cost data afterward
The callback data for impression, click, and Ad spend doesn't contain the user identification ID of the AE project. If you want to connect this kind of data, the AE system automatically attaches it to a "virtual user".
Then, if these events contain fields that can identify users (such as adjust_id and Android ID/IDFA, or web_uuid), and the user properties also contain the corresponding fields, ThinkingAI staff can link these events to AE users on a schedule by backfilling the data
| Data type | Description | Event name in AE | Virtual user of the event |
|---|---|---|---|
| impression | Impressions | adjust_impression | adjust_impression_vu |
| click | Clicks | adjust_click | adjust_click_vu |
| cost_update | Cost | adjust_cost_update | adjust_cost_update_vu |
3. Report Service API
Adjust's user-level data (the real-time callback interface) doesn't include cost data from self-attributing networks (Google, Facebook, etc.), so you can get aggregated cost data across all networks through Report Service.
For details, see: https://help.adjust.com/zh/article/reports-endpoint
Basic interface information
| Interface | API type | Productized | Data granularity | Attribution | Cost | Revenue | Impressions | Clicks | Conversions |
|---|---|---|---|---|---|---|---|---|---|
| Report Service API | Pull | No | Aggregated data | Yes | Yes | Yes | Yes | Yes |
3.1 Before you begin
Get the following parameters and send them to ThinkingAI staff:
- Adjust User Token (the user's API Token)
- You can get your API Token in the Adjust dashboard. Click the menu in the upper left corner and select Account settings (admin users select My account, find User details on the Your data tab, and click the gear button at the bottom), then click API token to get your API Token
- Adjust App Token
- You can get the App Token of the app you want to connect in the Adjust dashboard
3.2 Data pull
3.2.1 Analysis dimensions
The following are the analysis dimensions that Report Service supports, including time granularity (select only one) and grouping dimensions (multiple selections allowed)
- Time granularity
| Dimension | Data type | Description | Example | Default |
|---|---|---|---|---|
hour | Date | Date value in ISO format: YYYY-MM-DDTHH:MM:SS | 2021-05-11T17:00:45 | |
| day | Date | Date value format: YYYY-MM-DD | 2021-05-11 | Yes |
- Grouping dimensions
| Dimension | Data type | Description | Example | Default |
|---|---|---|---|---|
os_name | String | Operating system | Values: android, Bada, blackberry, iOS, Linux, Mac OS, server, symbian, unknown, WebOS, Windows, windows-phone | Yes |
device_type | String | Device Type | Values: bot, console, iPod, Mac, PC, phone, server, simulator, tablet, TV, unknown | Yes |
| app | String | App name | - | Yes |
| app_token | String | App ID in Adjust | - | Yes |
| store_id | String | Store app ID | com.random.app | Yes |
| store_type | String | Store the app was installed from | google_play | Yes |
app_network | String | App identifier | Format: <store_type>:<store_id> Example: google_play:com.random.app | Yes |
| currency | String | Currency | Euro | Yes |
| currency_code | String | 3-character ISO 4217 currency code | EUR | Yes |
network | String | Name of the ad network | Values: Organic, AppLovin, Facebook Installs, Instagram Installs | |
| campaign | String | Includes the campaign name and ID | - | Yes |
| campaign_network | String | Campaign name from the network | - | Yes |
| campaign_id_network | String | Campaign ID from the network | - | Yes |
| adgroup | String | Includes the ad group name and ID | - | Yes |
| adgroup_network | String | Ad group name from the network | - | Yes |
| adgroup_id_network | String | Ad group ID from the network | - | Yes |
| source_network | String | Optional value depending on the network, usually the same as adgroup_network | - | Yes |
| source_id_network | String | source_app value | - | Yes |
| creative | String | Includes the creative name and ID | - | Yes |
| creative_network | String | Creative name from the network | - | Yes |
| creative_id_network | String | Creative ID from the network | - | Yes |
| country | String | Country/region name | United States of America | Yes |
| country_code | String | 2-character ISO 3166 country/region code | US | Yes |
| region | String | Business region | APAC | Yes |
| partner_name | String | Partner name in the Adjust system | AppLovin | Yes |
| partner_id | String | Partner ID in the Adjust system | 34 | Yes |
3.2.2 Included metrics
Report Service supports a wide range of metrics. This section shows only some commonly used ones. You can visit the Adjust documentation for the detailed metric list. If you need to customize the metrics to pull, note them in the data integration configuration template
- Conversion metrics
| Field | Definition | Formula | Field name | Default |
|---|---|---|---|---|
| Average DAUs | Average daily active users in the selected period | (D0 DAU + D1 DAU + DAY N DAU) / number of days in the selected period | daus | Yes |
| Average MAUs | Average MAU in the selected period | (M0 MAU + M1 MAU + MONTH N MAU) / number of months in the selected period | maus | Yes |
| Average WAUs | Average WAU in the selected period | (W0 WAU + W1 WAU + WEEK N WAU) / number of weeks in the selected period | waus | Yes |
Base sessions | Number of user sessions, excluding installs and reattributions | - | base_sessions | Yes |
| Clicks | Number of tracked clicks | - | clicks | Yes |
| Clicks (network) | Number of clicks reported by the network API | - | network_clicks | Yes |
| Click conversion rate (CCR) | Ratio of installs to clicks | Installs / clicks | click_conversion_rate | Yes |
| Click-through rate (CTR) | Ratio of clicks to impressions | Clicks / impressions | ctr | Yes |
| Deattributions | Number of deattributions | - | deattributions | Yes |
| GDPR forgets | Number of users who exercised the right to be forgotten under the EU GDPR. Adjust permanently deletes the personal data of these users | - | gdpr_forgets | Yes |
| Impressions | Number of tracked ad impressions | - | impressions | Yes |
| Impressions (network) | Number of ad impressions reported by the network API | - | network_impressions | Yes |
| Impression conversion rate | Ratio of installs to impressions | Installs / impressions | impression_conversion_rate | Yes |
| Installs | Number of tracked users who installed your app | - | installs | Yes |
| Installs (network) | Number of installs reported by the network API | - | network_installs | Yes |
| Install difference | Difference between installs and the installs reported by the network API | Installs - installs (network) | network_installs_diff | Yes |
| Installs per mille (IPM) | Number of installs per 1,000 ad impressions | 1000 * impression conversion rate | installs_per_mile | Yes |
| Limit ad tracking installs | Number of installs from devices with limit ad tracking (LAT) enabled | - | limit_ad_tracking_installs | Yes |
| Limit ad tracking install rate | Ratio of limit ad tracking installs to installs | Limit ad tracking installs / installs | limit_ad_tracking_install_rate | Yes |
| Limit ad tracking reattributions | Number of reattributions from devices with limit ad tracking (LAT) enabled | - | limit_ad_tracking_reattributions | Yes |
| Limit ad tracking reattribution rate | Ratio of limit ad tracking reattributions to reattributions | Limit ad tracking reattributions / reattributions | limit_ad_tracking_reattribution_rate | Yes |
| Non-organic installs | Number of installs from users not attributed as organic | - | non_organic_installs | Yes |
| Organic installs | Number of installs from users attributed as organic | - | organic_installs | Yes |
| Reattributions | Number of reattributed users | - | reattributions | Yes |
| Reattribution reinstalls | Number of reinstalls by reattributed users | - | reattribution_reinstalls | |
| Reinstalls | Number of reinstalls Requires the Uninstall and Reinstall Growth Solution | - | reinstalls (otherwise the request returns an error) | |
| Total sessions | Total sessions include installs and reattributions | base_sessions + installs + reattributions | sessions | Yes |
- Cost metrics
| Field | Definition | Formula | Field name | Default |
|---|---|---|---|---|
| Ad spend | Total ad spend (determined by the pull parameters) | Click spend + impression spend + install spend | cost | Yes |
| Ad spend (attribution) | Ad spend tracked by Adjust | Click spend + impression spend + install spend | adjust_cost | Yes |
Ad spend (network) | Ad spend reported by the network API | Click spend + impression spend + install spend | network_cost | Yes |
| Ad spend difference | Difference between ad spend (attribution) and ad spend (network) | Ad spend (attribution) - ad spend (network) | network_cost_diff | Yes |
| Click cost | Cost spent on ad clicks | - | click_cost | Yes |
| Paid clicks | Number of ad clicks with ad spend | - | paid_clicks | Yes |
| eCPI (all installs) | Average effective spend across all installs | Ad spend / installs | ecpi_all | Yes |
| eCPI (network) | Average effective spend per install reported by the network API | Ad spend reported by the network API / installs reported by the network API | network_ecpi | Yes |
| eCPI (paid installs) | Average effective spend per paid install | Ad spend reported by the network API / paid installs | ecpi | Yes |
| eCPM (attribution) | eCPM data reported from attribution data | (Ad spend / paid impressions) * 1000 | ecpm | Yes |
| eCPM (network) | eCPM data reported by the network API | (Network spend / network paid impressions) * 1000 | network_ecpm | Yes |
| eCPC | Average effective spend per click | Ad spend / paid clicks | ecpc | Yes |
| Impression cost | Cost spent on impressions | - | impression_cost | Yes |
| Paid impressions | Number of paid impressions with ad spend | - | paid_impressions | Yes |
| Install cost | Cost spent on installs | - | install_cost | Yes |
| Paid installs | Number of paid installs with ad spend | - | paid_installs | Yes |
- Revenue metrics
| Field | Definition | Formula | Field name | Default |
|---|---|---|---|---|
| Ad impressions | Total number of ad impressions | - | ad_impressions | Yes |
| Ad revenue | Total ad revenue | - | ad_revenue | Yes |
| Cohort ad revenue | Ad revenue to date from users who installed during the selected period Example: if the selected period is 1/1 to 1/31 and today is 5/1, the ad revenue up to 5/1 from users who installed between 1/1 and 1/31 is calculated | - | cohort_ad_revenue | Yes |
| Ad RPM | Average revenue per 1,000 ad impressions | (Ad revenue / ad impressions) * 1000 | ad_rpm | Yes |
| IAP revenue | IAP revenue | - | revenue | Yes |
| Cohort IAP revenue | IAP revenue to date from users who installed during the selected period Example: if the selected period is 1/1 to 1/31 and today is 5/1, the IAP revenue up to 5/1 from users who installed between 1/1 and 1/31 is calculated | - | cohort_revenue | Yes |
| Total revenue | Total revenue including ad revenue and IAP revenue | Ad revenue + IAP revenue | all_revenue | Yes |
| Cohort total revenue | Total revenue to date from users who installed during the selected period Example: if the selected period is 1/1 to 1/31 and today is 5/1, the total revenue up to 5/1 from users who installed between 1/1 and 1/31 is calculated | Cohort IAP revenue + cohort ad revenue | cohort_all_revenue | Yes |
| ARPU (all) | Average revenue per active user, including all revenue | Total revenue / total DAU | arpdau | Yes |
| ARPU (ads only) | Average revenue per active user, including ad revenue only | Ad revenue / total DAU | arpdau_ad | Yes |
| ARPU (IAP only) | Average revenue per active user, including IAP revenue only | IAP revenue / total DAU | arpdau_iap | Yes |
| Gross profit | Total revenue minus total cost | Total revenue - total cost | gross_profit | Yes |
| Cohort gross profit | Gross profit of users who installed during the selected period | Cohort total revenue - cost | cohort_gross_profit | Yes |
| Cohort ROI | Gross profit of users who installed during the selected period divided by cost | Cohort gross profit / cost | return_on_investment | Yes |
| IAP events | Number of tracked in-app purchase events | - | revenue_events | Yes |
| Revenue to cost ratio (RCR) | Ratio of revenue to cost for users who installed during the selected period | Cohort total revenue / total cost | revenue_to_cost | Yes |
| ROAS (total revenue) | ROAS calculated on total revenue | (Ad revenue + IAP revenue) / cost | roas | Yes |
| ROAS (ad revenue) | ROAS calculated on ad revenue only | Ad revenue / cost | roas_ad | Yes |
| ROAS (IAP revenue) | ROAS calculated on IAP revenue only | IAP revenue / cost | roas_iap | Yes |
3.2.3 API parameters
-
Time:
- Data can be pulled by day
- The time zone can be customized
3.2.4 Ingestion rules
- Because Report Service returns aggregated data, we use a fixed value as the user identifier. You can think of all the data as attached to one virtual user
- The day or hour field in the data, that is, the date of the data, is set as the #event_time of the aggregated data
- The event name for Report Service data is adjust_report_service_ad_spend
- All other metric and dimension fields are stored
3.3 Data integration configuration template
After reading the documentation above, we recommend that you fill in the following template and send it to your customer success manager at ThinkingAI. We will pull the Adjust Report Service data based on this template:
Data interface: Adjust Report Service
---------
Company name: XXX
AE project environment: (SAAS/on-premises)
AE project name: XXX
AE project APP ID: XXX
Data receiving URL push_url: XXX
---------
Adjust User Token (API Token): XXX
Adjust App Token: XXX
---------
API configuration
Time range for historical data pull: yyyy/mm/dd - yyyy/mm/dd
Pull data for the last X days on a schedule (Adjust corrects data after the fact, so we recommend pulling the last few days of data on a schedule to make sure you get the corrected data)
Time granularity: (day/hour)
Grouping dimensions: xxx,xxx
Aggregated metrics: xxx,xxx
4. Integration testing and data usage after integration
- Integration testing
You can view the related attribution data on the Management > User properties page:
| Adjust callback field | Description | User property name in AE | Data type |
|---|---|---|---|
| network_name | Channel | #adjust_network_name | Text |
| campaign_name | Campaign | #adjust_campaign_name | Text |
| adgroup_name | Ad group | #adjust_adgroup_name | Text |
| creative_name | Ad creative | #adjust_creative_name | Text |
If you have enabled event table ingestion, view the related event data on the Management > Events page. The event names are the same as those defined in Adjust. The event mapping for impression, click, cost_update, and ad_revenue is as follows:
| Value of activity_kind | Description | Event name in AE |
|---|---|---|
| impression | Impressions | adjust_impression |
| click | Clicks | adjust_click |
| cost_update | Cost | adjust_cost_update |
| ad_revenue | Revenue | adjust_ad_revenue |
5. FAQ
See the Adjust FAQ section
6. Empty channel name for Facebook (Meta)
See the article Adjust attribution channel name shows Unattributed