Adjust Report Service API
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 |
|---|---|---|---|---|---|---|---|---|
| Report Service API | API | Aggregated metrics | ✅ | ✅ | ✅ | ✅ | ✅ |
Adjust's Report Service API provides aggregated metric data, including cost, revenue, impressions, clicks, conversions, and more.
Integration process
The process for connecting Adjust Report Service API data is as follows:
- In the Adjust dashboard, get the Adjust API token and app token
- Log in to the AE backend, go to the Third-party Integration module, add an Adjust Report Service API integration plan, and complete the related configuration
- Check whether the AE system receives the data successfully, and build reports
1. Get the Adjust API token and app token
1.1 Get the Adjust API token
Before getting data from the Report Service API, you need to get the Adjust API token. In Adjust Suite, you can find it under Account settings > My profile. In the classic dashboard, find User details on the My account > Your data tab and click the gear button at the bottom to get it.
The image below shows the Adjust Suite interface. The API token is the API Token in the image:
1.2 Get the app token
Next, you also need to get the Adjust app token, which determines which Adjust project the pulled data comes from.
Go to the Adjust dashboard, find the app, and click the caret (^) in the app options. The app token (App Token) is on the project card on the left. You can also click All settings on the project card and then click Show app details to get the app token.
2. Plan configuration
After getting the Adjust API token and app token, log in to the AE system and configure the new plan in the Third-party Integration module. The image below shows the configuration page of the Adjust Report Service API. Follow this section to create the plan:
2.1 Authorization information configuration
Click the Configure authorization information button under Authorization Information, and enter the App ID (the app ID in Adjust) and API Token in the pop-up
2.2 Sync Schedule
In the Sync Schedule module, you can set the policy for the AE system to pull Adjust Report Service API data on a schedule. You can choose to pull data for a period of time at a specific time every day or every hour. Because pulled data also counts toward the data volume, avoid pulling data for overly long periods on a schedule
2.3 Pull time zone
You can also set the time zone of the pulled data. The default is UTC+8
2.4 Receive Settings
You can control whether the data is written as events. We recommend that you enable event data ingestion.
2.5 Configuration
Finally, in the Configuration module, you can control the detailed settings of data pulling, including the time aggregation granularity of the data, the metric fields and dimensions to pull, and 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_name | Event name after ingestion; customizable |
| source | metrics | Metrics in the data; list type; customizable |
| group_by | Grouping dimensions in the data; list type; customizable | |
| time_granularity | Time aggregation granularity of the data; string type; for values, see time granularity in 2.5.2 Grouping dimensions; template default: day |
You can modify the configuration as needed
2.5.1 Included metrics
Included metrics correspond to source.metrics in the configuration. Because Report Service supports a very wide range of metrics, this section shows only some commonly used ones. For the detailed metric list, see the Adjust official documentation. To change the metrics, enter the field names of the metrics you need in source.metrics.
- Conversion metrics
| Field | Definition | Formula | Field name | Used by default in template |
|---|---|---|---|---|
| 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 | |
| Total sessions | Total sessions include installs and reattributions | base_sessions + installs + reattributions | sessions | Yes |
- Cost metrics
| Field | Definition | Formula | Field name | Used by default in template |
|---|---|---|---|---|
| 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 | Used by default in template |
|---|---|---|---|---|
| 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 |
2.5.2 Grouping dimensions
The following are the grouping dimensions supported by Report Service. They include time granularity (only one can be selected; it corresponds to source.time_granularity in the configuration, and the template default is day) and grouping dimensions (multiple can be selected; they correspond to source.group_by in the configuration). To change the dimensions, enter the field names of the dimensions you need in source.group_by.
- Time granularity
| Dimension | Data type | Description | Example | Used by default in template |
|---|---|---|---|---|
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 | Used by default in template |
|---|---|---|---|---|
os_name | String | OS | 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 |
2.5.3 Ingestion rules
- 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 used in the template is adjust_report_service_ad_spend. To change it, adjust sink_event.event_name
- All other metric and dimension fields are stored
2.6 Standardized fields
The following are the standardized fields of the Report Service API:
| Original field | Standardized field | Description |
|---|---|---|
| campaign_network | te_ads_object.campaign_name | Campaign name |
| campaign_id_network | te_ads_object.campaign_id | Campaign ID |
| adgroup_network | te_ads_object.ad_group_name | Ad group name, or the Unit name for monetization ads |
| adgroup_id_network | te_ads_object.ad_group_id | Ad group ID, or the Unit ID for monetization ads |
| creative_network | te_ads_object.ad_name | Ad name |
| creative_id_network | te_ads_object.ad_id | Ad ID |
| partner_name | te_ads_object.media_source | Media source or monetization channel |
| store_id | te_ads_object.app_id | App ID |
| app | te_ads_object.app_name | App name |
| os_name | te_ads_object.platform | Platform, such as Android or iOS |
| country_code | te_ads_object.country | Country or region code |
| currency_code | te_ads_object.currency | Currency of the cost or revenue |
| impressions | te_ads_object.impressions | Impressions |
| clicks | te_ads_object.clicks | Clicks |
| installs | te_ads_object.installs | Conversions (installs) |
| cost | te_ads_object.cost | User acquisition cost |
| revenue | te_ads_object.revenue | Monetization revenue |
3. Next steps
3.1 Check data ingestion
You can check on the Management page whether the event adjust_report_service_ad_spend has been stored
3.2 Pull data once
If you want to connect data from an earlier period, such as historical data or data that failed to be pulled, open the plan page again after saving the plan and click the Single pull task button in the upper right corner to pull data for a specific time range once. Note that if the period of the pulled data overlaps with earlier pulls, for example, you pull data for 2023-08-01 and data for that day was already pulled before, the most recently pulled data overwrites the earlier data:
3.3 The ad_spend_mode parameter
https://help.adjust.com/zh/article/how-ad-spend-source-affects-your-data
To adapt to new API capabilities, the parameter AE uses by default has changed from cost_mode to ad_spend_mode, and the default value of the parameter is network.
If ad_spend_source is set to mixed, ad spend is determined as follows:
- If the partner uses Adjust's ad spend API integration, ad spend = ad spend (network). In this case, you need to add the account on the Connections page. Otherwise, the value is shown as 0.
- In all other cases where the partner has no API integration with Adjust, ad spend = ad spend (attribution).