From bcfcb75b0ec481a52104ba12383e61d9a256dc80 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Thu, 26 Sep 2024 15:31:20 +0200 Subject: [PATCH 01/10] Add initial icon work --- markdoc.config.mjs | 10 +++ src/components/Icon.astro | 13 ++++ src/components/Layout/Icons.astro | 112 ++++++++++++++++++++++++++++++ 3 files changed, 135 insertions(+) create mode 100644 src/components/Icon.astro diff --git a/markdoc.config.mjs b/markdoc.config.mjs index 8aae611f2..d35ad1ea6 100644 --- a/markdoc.config.mjs +++ b/markdoc.config.mjs @@ -76,6 +76,16 @@ export default defineMarkdocConfig({ } } }, + icon: { + render: component("src/components/Icon.astro"), + attributes: { + type: { + type: String, + required: true, + matches: ["Trash", "Pencil", "Person", "CogWheel", "Check", "Cross"] + } + } + }, listcolumns: { render: component("src/components/ListColumns.astro"), }, diff --git a/src/components/Icon.astro b/src/components/Icon.astro new file mode 100644 index 000000000..1f80c91b1 --- /dev/null +++ b/src/components/Icon.astro @@ -0,0 +1,13 @@ +--- +interface Props { + type: string; +} + +const { type } = Astro.props; +--- + + + + + + diff --git a/src/components/Layout/Icons.astro b/src/components/Layout/Icons.astro index 42c5dfbb7..15d537ea9 100644 --- a/src/components/Layout/Icons.astro +++ b/src/components/Layout/Icons.astro @@ -229,4 +229,116 @@ > + + + + + + From 1871011a33ddd3996bd9e44dd8109961f1d3f5a5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Thu, 24 Oct 2024 18:03:23 +0200 Subject: [PATCH 02/10] Rework RS API docs --- astro.config.mjs | 5 +- src/content/docs/en/api/_authentication.mdoc | 26 + src/content/docs/en/api/reports-service.mdoc | 699 ++++++++++++++++++ .../docs/en/api/rs-api/authentication.mdx | 38 - src/content/docs/en/api/rs-api/csv.mdx | 199 ----- src/content/docs/en/api/rs-api/events.mdx | 120 --- .../docs/en/api/rs-api/filters-data.mdx | 190 ----- src/content/docs/en/api/rs-api/index.mdx | 27 - src/content/docs/en/api/rs-api/pivot.mdx | 267 ------- src/content/docs/en/api/rs-api/reports.mdx | 219 ------ src/redirects.json | 9 +- 11 files changed, 737 insertions(+), 1062 deletions(-) create mode 100644 src/content/docs/en/api/_authentication.mdoc create mode 100644 src/content/docs/en/api/reports-service.mdoc delete mode 100644 src/content/docs/en/api/rs-api/authentication.mdx delete mode 100644 src/content/docs/en/api/rs-api/csv.mdx delete mode 100644 src/content/docs/en/api/rs-api/events.mdx delete mode 100644 src/content/docs/en/api/rs-api/filters-data.mdx delete mode 100644 src/content/docs/en/api/rs-api/index.mdx delete mode 100644 src/content/docs/en/api/rs-api/pivot.mdx delete mode 100644 src/content/docs/en/api/rs-api/reports.mdx diff --git a/astro.config.mjs b/astro.config.mjs index fc24158a0..3d573bfa7 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -33,7 +33,10 @@ const prependLocaleToJSON = (input, locales) => { for (const [key, value] of Object.entries(input)) { const localeRegex = /^\/[a-z]{2}\//; - if (localeRegex.exec(value)) return; + if (localeRegex.exec(key)) { + result[key] = value; + continue; + } locales.forEach((locale) => { result[`/${locale}${key}`] = `/${locale}${value}`; }); diff --git a/src/content/docs/en/api/_authentication.mdoc b/src/content/docs/en/api/_authentication.mdoc new file mode 100644 index 000000000..019406d7f --- /dev/null +++ b/src/content/docs/en/api/_authentication.mdoc @@ -0,0 +1,26 @@ +## Authentication {% #authentication %} + +Adjust uses [Bearer tokens](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) for authentication. You MUST include your Adjust API token in an `Authorization` header with each request you make to Adjust's APIs. + +If your organization has enabled Single Sign-On (SSO), contact your Adjust representative or email support@adjust.com for help with finding your API token. + +For non-SSO accounts, API tokens are located in a user's **profile**. To find your token, follow these steps: + +1. Select the account icon ({% icon type="Person" /%}). +1. Select **Account settings**. +1. Select the **My profile** tab. +1. Your **API Token** is shown with your **User Details**. Select the copy button ({% icon type="Copy" /%}) to copy the token to your system clipboard. + +### Reset your Adjust API token {% #reset-your-adjust-api-token %} + +You can reset your Adjust API token at any time. Resetting your token invalidates the old token. If you reset your Adjust API token, you MUST replace your old token anywhere that you're using it. Requests made with an invalidated token are rejected by Adjust. + +To reset your Adjust API token: + +1. Select the account icon ({% icon type="Person" /%}). +1. Select **Account settings**. +1. Select the **My Profile** tab. +1. Your **API Token** is shown with your **User details**. +1. Select **Reset API token**. +1. Enter your account password in the modal that appears and select **Reset** to reset your API token. A confirmation appears in the top right of the screen. +1. Select the copy button ({% icon type="Copy" /%}) next to the **API Token** to copy the token to your system clipboard. diff --git a/src/content/docs/en/api/reports-service.mdoc b/src/content/docs/en/api/reports-service.mdoc new file mode 100644 index 000000000..3b370d5c8 --- /dev/null +++ b/src/content/docs/en/api/reports-service.mdoc @@ -0,0 +1,699 @@ +--- +title: Reports Service API +description: Use the Reports Service API to fetch aggregated data for your apps. +category-title: Reports Service API +sidebar-position: 1 +--- + +Use the Reports Service API to query Adjust's reporting dataset for aggregated data about your apps and campaigns. + +{% partial file="./_authentication.mdoc" /%} + +### Use multiple accounts {% #use-multiple-accounts %} + +By default, the Reports Service API queries only data relating to the first account your user is associated with. To query data from another account, follow these steps: + +1. Select the account icon ({% icon type="Person" /%}) +1. Select **Change account**. +1. Search for the account you want to query in the pop-up that appears. The account ID is written in parentheses after the account name. + +To specify which account you want to query data for, pass your account ID as an `X-Account-ID` header in each request. + +```console +curl --location "https://automate.adjust.com/reports-service/filters_data?required_filters=overview_metrics%2Ccost_metrics§ion=cost&overview_metrics__contains=ecpi&cost_metrics__contains=Ad%20spend" \ +--header "Authorization: Bearer {YOUR_API_TOKEN}" +--header "X-Account-ID: {YOUR_ACCOUNT_ID}" +``` + +## Response codes {% #response-codes %} + +The Reports Service API returns the following response codes for each endpoint: + +| Response | Message | Notes | +| --------------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------- | +| `200` | `Success` | Returns report information | +| `204` | `No content` | Returned if the response object is empty | +| `400` | `Bad request` | Returned if your request is malformed or contains unsupported parameters | +| `401` | `Unauthorized` | Returned if your credentials are incorrect or absent | +| `403` | `Forbidden` | Returned if you try to access information you don't have permission to view | +| `429` | `Too many requests` | Returned if you exceed 50 simultaneous requests | +| `503` | `Service unavailable` | Returned if the server can't be reached | +| `504` | `Gateway timeout` | Returned if the query takes too long to return a response | + +## Fetch required information {% #fetch-required-information %} + +The Reports Service API + +### Retrieve filters {% #retrieve-filters %} + +When querying the Reports Service API, you need to filter your reporting data. The Reports Service API supports different filters such as metrics and dimensions. A full list of metrics is available in the [Datascape metrics glossary](https://help.adjust.com/en/article/datascape-metrics-glossary) and a full list of dimensions is available in the [Datascape dimensions glossary](https://help.adjust.com/en/article/datascape-dimensions-glossary). + +You can fetch filters programatically using the `filters_data` endpoint. This endpoint returns a full representation of all matching filters. + +```http +GET https://automate.adjust.com/reports-service/filters_data +``` + +#### Parameters + +You MUST pass the following as a **query parameter**: + +{% deflist %} +`required_filters`: `String` + +: A comma-separated list of filters. +{% /deflist %} + +The following filters are available: + +| Filter | Description | +| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| `apps` | Returns a list of your apps. | +| `apps_network` | Returns a list of your apps and their associated store IDs. | +| `overview_metrics` | Returns a list of overview metrics. | +| `skad_metrics` | Returns a list of metrics relating to SKAdNetwork. | +| `cohort_maturity` | Returns a list of metrics relating to the maturity of a cohort. Example: mature, immature. | +| `cohort_metrics` | Returns a list of metrics relating to your cohorts. | +| `event_metrics` | Returns a list of metrics relating to your events. All metrics are duplicated per event. | +| `cost_metrics` | Returns a list of metrics relating to cost. | +| `etl_metrics` | Returns a list of metrics relating to ETL (extract, transform, load) between Adjust and another system. | +| `dimensions` | Returns a list of dimensions. | +| `countries` | Returns a list of countries. | +| `currencies` | Returns a list of currencies. | +| `os_names` | Returns a list of operating system names. | +| `networks` | Returns a list of networks. | +| `partners` | Returns a list of partners. | +| `ad_revenue_sources` | Returns a list of ad revenue sources. | +| `iap_revenue_mode` | Returns a list of ad revenue modes. | +| `attribution_type` | Returns a list of attribution types. Examples: all, click, impression. | +| `attribution_source` | Returns a list of attribution sources. | +| `attribution_status` | Returns a list of attribution statuses. | +| `ad_spend_mode` | Returns a list of cost modes. Examples: attribution, network, mixed. | +| `ad_spend_mode` | Returns a list of ad spend modes. Examples: attribution, network, mixed. | +| `utc_offset` | The offset (in hours) from UTC. Defaults to 0 (UTC). | +| `attributes` | Returns a list of attributes. | +| `index` | Returns a list of key metrics that relate to all apps. | +| `period_over_period` | Returns a list of time periods used for data comparison. | +| `cohort_metric_names` | Returns a list of readable names for cohort metrics. | +| `full_cohort_periods` | Returns a list of time periods related to cohorts. | +| `store_type` | Returns a list of app stores. | +| `skad_time_adjustment` | Returns a list of valid SKAdNetwork activity windows. | + +You MAY pass the following as **query parameters**: + +{% deflist %} +`section`: `String` + +: The section you want to filter items by. + +`[required_filters]__contains`: `String` + +: A search term to filter your selected required filters by. +{% /deflist %} + +The following sections are available: + +| Section | Description | +| ----------------------------------------------------- | ----------------------------------------------------- | +| `conversion` | Metrics relating to click and impression conversions. | +| `fraud` | Metrics relating to fraud prevention. | +| `cost` | Metrics relating to cost. | +| `revenue` | Metrics relating to app revenue. | +| `retention` | Metrics relating to cohort-based user retention. | +| `events` | Metrics relating to events. | +| `conversion_events` | Metrics relating to SKAdNetwork conversion events. | +| `installs` | Metrics relating to app installs and reinstalls. | +| `conversion_values` | Metrics relating to SKAdNetwork conversion values. | + +#### Response format + +```json +{ + "required_filters_1": [ + { + "id": "string", + "name": "string", + "short_name": "string", + "section": "string", + "formatting": "string", + "description": "string", + "increase_is_negative": false + } + ] +} +``` + +#### Example + +```console +curl --location "https://automate.adjust.com/reports-service/filters_data?required_filters=overview_metrics%2Ccost_metrics§ion=cost&overview_metrics__contains=ecpi&cost_metrics__contains=Ad%20spend" \ +--header "Authorization: Bearer {YOUR_API_TOKEN}" +``` + +```json +{ + "cost_metrics": [ + { + "id": "network_ad_spend_skan", + "name": "Ad spend (SKAN)", + "short_name": "", + "section": "Cost", + "formatting": "money", + "description": "The amount spent on ads for SKAN campaigns as reported by the network API", + "increase_is_negative": false + }, + { + "id": "network_cost", + "name": "Ad spend (network)", + "short_name": "", + "section": "Cost", + "formatting": "money", + "description": "Ad spend data retrieved via the network API", + "increase_is_negative": true + }, + { + "id": "network_cost_diff", + "name": "Ad spend diff (network)", + "short_name": "", + "section": "Cost", + "formatting": "money", + "description": "Difference between the attribution and network data sources", + "increase_is_negative": true + } + ], + "overview_metrics": [ + { + "id": "skad_ecpi", + "name": "eCPI (SKAN)", + "short_name": "", + "section": "Cost", + "formatting": "decimal", + "description": "Effective cost per install, calculated by dividing the amount spent on ads for SKAN campaigns by installs", + "increase_is_negative": false + }, + { + "id": "ecpi_all", + "name": "eCPI (all installs)", + "short_name": "eCPI (all)", + "section": "Cost", + "formatting": "money", + "description": "Effective cost per install", + "increase_is_negative": true + }, + { + "id": "ecpi", + "name": "eCPI (paid installs)", + "short_name": "eCPI (paid)", + "section": "Cost", + "formatting": "money", + "description": "Effective cost per paid install", + "increase_is_negative": true + } + ] +} +``` + +### Retrieve event slugs {% #retrieve-event-slugs %} + +If you want to query your reporting data using your Adjust events, you need to retrieve the slugs for your events by calling the `events` endpoint. This endpoint enables you to search for events using their readable names and returns useful information about each one. + +```http +GET https://automate.adjust.com/reports-service/events +``` + +#### Parameters + +You MAY pass the following as a **query parameter**: + +{% deflist %} +`events__contains`: `String` + +: A search term to filter your events by. + +`app_token__in`: `String` + +: A comma-separated list of app tokens to filter events by. + +`tokens_mapping`: `Boolean` + +: If `true`, the response contains the App token to Event token mapping. +{% /deflist %} + +#### Response format + +```json +[ + { + "id": "string", + "name": "string", + "short_name": "", + "section": "", + "formatting": "money", + "description": "", + "app_token": [ + "string" + ], + "tokens": [ + "string" + ], + "is_skad_event": true, + "app_token_x_event_tokens_mapping": { + "property1": [ + "string" + ], + "property2": [ + "string" + ] + } + } +] +``` + +#### Example + +```console +curl --location "https://automate.adjust.com/reports-service/events?events__contains=purchase&tokens_mapping=true" \ +--header "Authorization: Bearer {YOUR_API_TOKEN}" +``` + +```json +[ + { + "id": "purchase", + "name": "Purchase Event", + "short_name": "PUR", + "section": "Revenue", + "description": "", + "app_token": [ + "4zb92bmajmrd" + ], + "tokens": [ + "abc123" + ], + "is_skad_event": false, + "app_token_x_event_tokens_mapping": { + "4zb92bmajmrd": [ + "abc123" + ] + } + } +] +``` + +## Fetch reporting data {% #fetch-reporting-data %} + +Once you've collected the required filters for your report, you can fetch reporting data from Adjust in different formats using the reporting endpoints. + +### Parameters {% #report-parameters %} + +For each reporting endpoint, you MUST pass the following **query parameters**: + +{% deflist %} +`dimensions`: `String` + +: A comma-separated list of dimensions to group results by. You can fetch dimensions from the [`filters_data` endpoint](#retrieve-filters) or find a full list in the [Datascape dimensions glossary](https://help.adjust.com/en/article/datascape-dimensions-glossary). + +`metrics`: `String` + +: A comma-separated list of metrics to report on. You can fetch metrics from the [`filters_data` endpoint](#retrieve-filters) or find a full list in the [Datascape metrics glossary](https://help.adjust.com/en/article/datascape-metrics-glossary). + +`date_period`: `String` + +: The start and end dates for the report. There are 3 supported formats for dates: + +- Logical dates. For example: `this_month_until_yesterday`, `today`, `this_month`. +- Absolute dates. For example: `2020-12-31:2021-01-01`. +- Relative dates. For example: `-10d:-3d` (from 10 days ago to 3 days ago). +{% /deflist %} + +You MAY pass the following as **query parameters**: + +{% deflist %} +`cohort_maturity`: `String` + +: Whether to include all cohort metric values (`immature`) or only mature cohorts `mature`. If you pass `mature`, any values for immature cohorts are displayed as zeros. + +`utc_offset`: `String` + +: The timezone used in the report. Formatted as `utc_offset=+01:00`. + +`attribution_type`: `String` + +: The type of engagement the attribution awards. + +- `click` (default) +- `impression` +- `all` + +`attribution_source`: `String` + +: Whether in-app activity is assigned to the user's install source (`first`) or divided among the install source and subsequent sources of reattribution (`dynamic`). Defaults to `dynamic`. + +`reattributed`: `String` + +: Filter reattributed users. + +- `all`: Show all users. +- `false`: Show only users who aren't reattributed. +- `true`: Show only reattributed users. + +`iap_revenue_mode`: `String` + +: The percentage of gross ad revenue. + +- `GROSS_100` +- `GROSS_85` +- `GROSS_70` +- `GROSS_60` + +`ad_revenue_sources`: `String` + +: A comma-separated list of ad revenue sources. + +`os_names`: `String` + +: A comma-separated list of operating system names. For example: `ios,android`. + +`ad_spend_mode`: `String` + +: Which ad spend source is applied in calculations. See [How ad spend source affects your data](https://help.adjust.com/en/article/how-ad-spend-source-affects-your-data) for more information. + +- `adjust` +- `network` +- `mixed` + +`sandbox`: `Boolean` + +: Whether to use sandbox data (`true`) or production data (`false`). Defaults to `false`. + +`sort`: `String` + +: A comma-separated list of metrics or dimensions to sort your report by. Use `-` to sort by descending order. For example: `sort=-clicks,installs`. + +`index`: `String` + +: A comma-separated list of dimensions used to index the report. + +`format_dates`: `Boolean` + +: Whether to format dates (`true`) or return them in ISO format (`false`). Defaults to `true`. + +`period_over_period`: `String` + +: The period for comparing report data. For example: `period_over_period=previous_week`. + +`currency`: `String` + +: The currency used to convert money-related metrics. + +`[dimension]__in`: `String` + +: A comma-separated list of values to filter a given dimension's value by. Returns only exact matches. + +`[dimension]__not_in`: `String` + +: A comma-separated list of values to filter a given dimension's value by. Excludes only exact matches. + +`[dimension]__contains`: `String` + +: A substring to filter a given dimension's value by. Returns partial or exact matches. + +`[dimension]__exclude`: `String` + +: A substring to filter a given dimension's value by. Exludes partial or exact matches. + +`[dimension]__starts_with`: `String` + +: A substring to filter a given dimension by prefix. Case insensitive. + +`[dimension]__not_starts_with`: `String` + +: A substring to filter a given dimension by prefix. Case insensitive. + +`[dimension]__ends_with`: `String` + +: A substring to filter a given dimension by suffix. Case insensitive. + +`[dimension]__not_ends_with`: `String` + +: A substring to filter a given dimension by suffix. Case insensitive. + +`[metric]__lt`: `String` + +: "Less than" filter. Returns only values lower than the specified value for the specified metric. + +`[metric]__lte`: `String` + +: "Less than or equal to" filter. Returns only values lower than or equal to the specified value for the specified metric. + +`[metric]__gt`: `String` + +: "Greater than" filter. Returns only values higher than the specified value for the specified metric. + +`[metric]__gte`: `String` + +: "Greater than or equal to" filter. Returns only values greater than or equal to the specified value for the specified metric. + +`[metric]__eq`: `String` + +: "Equal to" filter. Returns only values equal to the specified value for the specified metric. + +`[metric]__ne`: `String` + +: "Not equal to" filter. Returns only values not equal to the specified value for the specified metric. +{% /deflist %} + +### Fetch a JSON report {% #fetch-json-report %} + +The `report` endpoint enables you to combine data from many services in a single report. Request installs, revenue, ad spend, and SKAdNetwork data divided by day, app, and ad network. + +```http +GET https://automate.adjust.com/reports-service/report +``` + +#### Response format + +```json +{ + "rows": [], + "totals": {}, + "data_warnings": [], + "debug": { + "service_urls": [ + { + "method": "string", + "url": "string", + "params": {}, + "data": {}, + "status_code": 0, + "duration": 0 + } + ], + "cached_at": "2019-08-24T14:15:22Z" + }, + "currencies": [], + "immature_cohorts": {} +} +``` + +#### Example + +```console +$ curl --location "https://automate.adjust.com/reports-service/report?ad_spend_mode=network&app_token__in={app_token1},{app_token2}&date_period=2024-05-01:2024-05-02&dimensions=app,partner_name,campaign,campaign_id_network,campaign_network&metrics=installs,network_installs,network_cost,network_ecpi" \ +--header "Authorization: Bearer {YOUR_API_TOKEN}" +``` + +```json +{ + "rows": [ + { + "attr_dependency": { + "campaign_id_network": "unknown", + "partner_id": "-300", + "partner": "Organic" + }, + "app": "Test app", + "partner_name": "Organic", + "campaign": "unknown", + "campaign_id_network": "unknown", + "campaign_network": "unknown", + "installs": "10", + "network_installs": "0", + "network_cost": "0.0", + "network_ecpi": "0.0" + } + ], + "totals": { + "installs": 10.0, + "network_installs": 0.0, + "network_cost": 0.0, + "network_ecpi": 0.0 + }, + "data_warnings": [], + "pagination": null +} +``` + +### Fetch a pivot report {% #fetch-pivot-report %} + +The `pivot_report` endpoint delivers data in a structured, pivot-table format. It allows you to group and aggregate data across multiple dimensions, making it easier to summarize and compare key metrics. This is useful when you want to analyze patterns or trends without having to manually manipulate the raw data. + +```http +GET https://automate.adjust.com/reports-service/pivot_report +``` + +#### Parameters + +In addition to the [mandatory parameters for each endpoint](#report-parameters), you MUST pass the following **query parameter** when calling the `pivot_report` endpoint: + +{% deflist %} +`index`: `String` + +: A comma-separated list of dimensions used to index the report. +{% /deflist %} + +#### Response format + +```json +{ + "rows": [], + "totals": {}, + "data_warnings": [], + "debug": { + "service_urls": [ + { + "method": "string", + "url": "string", + "params": {}, + "data": {}, + "status_code": 0, + "duration": 0 + } + ], + "cached_at": "2019-08-24T14:15:22Z" + }, + "currencies": [], + "immature_cohorts": {}, + "totals_per_dimension": {} +} +``` + +#### Example + +```console +curl --location "https://automate.adjust.com/reports-service/pivot_report?ad_spend_mode=network&app_token__in={app_token1},{app_token2}&date_period=2021-05-01:2021-05-02&dimensions=app,partner_name,campaign,campaign_id_network,campaign_network&metrics=installs,network_installs,network_cost,network_ecpi&index=app" \ +--header 'Authorization: Bearer {YOUR_API_TOKEN}' +``` + +```json +{ + "rows": [ + { + "Test App": { + "rows": [ + { + "attr_dependency": { + "app_network": ["google_play:com.test.app"] + }, + "campaign_id_network": "123", + "campaign_network": "Campaign Name", + "campaign": "Campaign Name (123)", + "partner_name": "MyPartner", + "installs": 10, + "network_installs": 0, + "network_cost": 0, + "network_ecpi": 0 + } + ] + } + } + ], + "totals": { + "installs": 10, + "network_installs": 0, + "network_cost": 0, + "network_ecpi": 0 + }, + "totals_per_dimension": { + "campaign_id_network": { + "Organic": { + "installs": 10, + "network_installs": 0, + "network_cost": 0, + "network_ecpi": 0 + } + }, + "campaign_network": { + "Organic": { + "installs": 10, + "network_installs": 0, + "network_cost": 0, + "network_ecpi": 0 + } + }, + "app": { + "adjust Demo App": { + "installs": 10, + "network_installs": 0, + "network_cost": 0, + "network_ecpi": 0 + } + }, + "campaign": { + "Organic": { + "installs": 10, + "network_installs": 0, + "network_cost": 0, + "network_ecpi": 0 + } + }, + "partner_name": { + "Organic": { + "installs": 10, + "network_installs": 0, + "network_cost": 0, + "network_ecpi": 0 + } + } + } +} +``` + +### Fetch a CSV report {% #fetch-csv-report %} + +The `csv_report` endpoint returns data in a comma-separated values format, perfect for importing into spreadsheet software or other tools that require a flat file structure. This format is ideal for users who prefer to work with data in Excel or similar applications for further manipulation and reporting. + +```http +GET https://automate.adjust.com/reports-service/csv_report +``` + +#### Parameters + +In addition to the [parameters for each endpoint](#report-parameters), you MAY pass the following **query parameter** when calling the `csv_report` endpoint: + +{% deflist %} +`readable_names`: `Boolean` + +: Whether to return columns with their human-readable names. Defaults to `false`. +{% /deflist %} + +Human-readable names can change depending on upstream requirements. Use slugs for long running reports to ensure consistency. You can use the [events endpoint](#retrieve-event-slugs) to retrieve event slugs. + +#### Response format + +```text +app,partner_name,campaign,campaign_id_network,campaign_network,installs,network_cost +String,String,String,String,String,Number,Number +``` + +#### Example + +```console +curl --location "https://automate.adjust.com/reports-service/csv_report?ad_spend_mode=network&app_token__in={app_token1},{app_token2}&date_period=2021-05-01:2021-05-02&dimensions=app,partner_name,campaign,campaign_id_network,campaign_network&metrics=installs,network_cost" +--header "Authorization: Bearer {YOUR_API_TOKEN}" +``` + +```text +app,partner_name,campaign,campaign_id_network,campaign_network,installs,network_cost +App Name,AppLovin,Campaign Name (Campaign ID),Campaign ID,Campaign Network,64,1000 +``` diff --git a/src/content/docs/en/api/rs-api/authentication.mdx b/src/content/docs/en/api/rs-api/authentication.mdx deleted file mode 100644 index 9d591162f..000000000 --- a/src/content/docs/en/api/rs-api/authentication.mdx +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: "Report service API authentication" -description: "You need a bearer token to use the Report service API." -slug: en/api/rs-api/authentication -sidebar-position: 1 -sidebar-label: Authentication ---- - -You need a [bearer token](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) to use the Report service API. You can get this token in the Adjust dashboard by following the steps in this article. - -## Find your Adjust API token {#find-your-adjust-api-token} - -Before you can start making API calls, you first need to find your Adjust API token. You can find your Adjust API token in your Adjust dashboard. - - - -If you've configured SSO, your API tokens aren't available in the Adjust dashboard. Reach out to your Adjust representative or support@adjust.com for help with API tokens. - - - -Your Adjust API token is located in your **profile**. To find it, follow these steps: - -1. Select the settings icon in the bottom left corner. -2. Select **Account settings**. Your account settings page opens. -3. Select the **My profile** tab. -4. Your **API Token** is shown with your **User Details**. Select the copy button to copy the token to your system clipboard. - -## Reset your Adjust API token {#reset-your-adjust-api-token} - -You can reset your Adjust API token at any time. Resetting your token invalidates the old token. This means that any requests made using the old token won't work. If you reset your Adjust API token, you need to make sure to update it wherever it's in use. - -1. Select the settings icon in the bottom left corner. -2. Select **Account settings**. Your account settings page opens. -3. Select the **My Profile** tab. -4. Your **API Token** is shown with your **User details**. -5. Select **Reset API token**. A popup modal appears. -6. Enter your account password in the modal and select **Reset** to reset your API token. The modal closes and a confirmation appears in the top right of the screen. -7. Select the copy button next to the **API Token** to copy the token to your system clipboard. diff --git a/src/content/docs/en/api/rs-api/csv.mdx b/src/content/docs/en/api/rs-api/csv.mdx deleted file mode 100644 index ecc6d769d..000000000 --- a/src/content/docs/en/api/rs-api/csv.mdx +++ /dev/null @@ -1,199 +0,0 @@ ---- -title: "CSV endpoint" -description: "The reports endpoint enables you to combine data from many services in a single CSV report." -slug: en/api/rs-api/csv -sidebar-position: 5 ---- - -The CSV Report Service provides an API to get aggregated data from different sources in CSV format. - -- KPI Service metrics -- KPI Service cohorts -- SKAdNetwork -- Ad Spend - -## Fetch CSV report {#fetch-csv-report} - - - -```http -GET https://automate.adjust.com/reports-service/csv_report -``` - - - -The `GET` method returns filtered data from the report service in CSV format. The API returns columns of data for each parameter passed in the request. By default the parameter's slug is used as the column header. You can return human-readable names by passing `readable_names=true` in your request. - - - -Human-readable names can change depending on upstream requirements. Use slugs for long running reports to ensure consistency. You can use the [Events endpoint](/en/api/rs-api/events) to retrieve event slugs. - - - -### Filters {#filters} - -| Filter | Type | Description | Example | -| ------------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `dimensions`\* | `String` | Comma-separated values used to group parameters. See the dimensions table below for more information. | `dimensions=app,os_name,week,campaign_id_network` | -| `metrics`\* | `String` | Comma-separated KPIs. See the metrics table below for more information. | `metrics=cost,installs,ecpi_network` | -| `date_period`\* | `String` | Start and end dates for the report with 3 supported formats: | | -| `cohort_maturity` | `String` | | `cohort_maturity=immature` | -| `readable_names` | `Boolean` | Whether to return columns with their human-readable names. Defaults to `false` | `readable_names=true` | -| `utc_offset` | `String` | The timezone used in the report. | `utc_offset=+01:00` | -| `timezone_id` | `String` | The ID of the timezone used in the report. `timezone_id=1` | | -| `hour__between` | `String` | Filter results between given hours of the day. `hour__between=-10h:-0h` | | -| `attribution_type` | `String` | The type of engagement the attribution awards. | `attribution_type=click` | -| `attribution_source` | `String` | Whether in-app activity is assigned to the user’s install source (`first`) or divided among the install source and subsequent sources of reattribution (`dynamic`). Defaults to `dynamic`. | `attribution_source=first` | -| `reattributed` | `String` | Filter for reattributed users only. Reattribution is when a user who has already installed your app returns to it through a new Adjust-measureed source. | `reattributed=false` | -| `iap_revenue_mode` | `String` | The percentage of gross ad revenue returned by the endpoint. Available options are: | `iap_revenue_mode=GROSS_70` | -| `ad_revenue_sources` | `String` | Comma-separated list of ad revenue sources. | `ad_revenue_sources=unknown` | -| `os_names` | `String` | Comma-separated list of operating system names. | `os_names=ios,android` | -| `ad_spend_mode` | `String` | Determines the ad spend source applied in calculations. See How ad spend source affects your data for more information. | `ad_spend_mode=network` | -| `sandbox` | `Boolean` | Whether to use sandbox data or production data. Defaults to `false`. | `sandbox=true` | -| `sort` | `String` | Comma-separated list of metrics/dimensions to sort the report by. Use `-` to order descending. | `sort=-clicks,installs` | -| `index` | `String` | Comma-separated list of dimensions used to index the report. | `index=network,campaign,adgroup` | -| `format_dates` | `Boolean` | If set to `false`, all date dimensions are returned in ISO format. | `format_dates=false` | -| `period_over_period` | `String` | The period for comparing report data. | `period_over_period=previous_week` | -| `currency` | `String` | Currency used for conversion of money related metrics. | `currency=USD` | -| `[dimension]__in` | `String` | Comma-separated list of values to filter dimension's values (exact match) for any dimension. | `campaign__in=abc,def` | -| `[dimension]__not_in` | `String` | Comma-separated list of values to filter dimension's values (exclude exact match) for any dimension | `campaign__not_in=abc,def` | -| `[dimension]__contains` | `String` | Substring search in dimension's values (case insensitive) for any dimension. | `campaign__contains=ios` | -| `[dimension]__exclude` | `String` | Excluding substring search in dimension's values (case insensitive) for any dimension. | `campaign__exclude=ios` | -| `[dimension]__starts_with` | `String` | Substring search matching dimensions starting with specified prefix (case insensitive). | `campaign__starts_with=ios` | -| `[dimension]__not_starts_with` | `String` | Substring search matching dimensions not starting with specified prefix (case insensitive). | `campaign__not_starts_with=ios` | -| `[dimension]__ends_with` | `String` | Substring search matching dimensions ending with specified suffix (case insensitive). | `campaign__ends_with=ios` | -| `[dimension]__not_ends_with` | `String` | Substring search matching dimensions not ending with specified suffix (case insensitive). | `campaign__not_ends_with=ios` | -| `[metric]__lt` | `String` | "Less than" filter for metric's values any metric. | `skad_installs__lt=100` | -| `[metric]__lte` | `String` | "Less than or equal" filter for metric's values for any metric. | `skad_installs__lte=100` | -| `[metric]__gt` | `String` | "Greater than" filter for metric's values for any metric. | `skad_installs__gt=100` | -| `[metric]__gte` | `String` | "Greater than or equal" filter for metric's values for any metric. | `skad_installs__gte=100` | -| `[metric]__eq` | `String` | "Equal" filter for metric's values for any metric. | `skad_installs__eq=100` | -| `[metric]__ne` | `String` | "Not equal" filter for values relating to any metric. | `skad_installs__ne=100` | - -### Dimensions {#dimensions} - -Dimensions allow a user to break down metrics into groups using one or several parameters. For example, the number of installs by date, country and network. - -| Dimension | Data type | Description | Example | -| --------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | -| `hour` | `Date` | Use `format_dates=false` to return the value in ISO format.
`YYYY-MM-DDTHH:MM:SS` | `2021-05-11T17:00:45` | -| `day` | `Date` | Use `format_dates=false` to return the value in ISO format.
`YYYY-MM-DD` | `2021-05-11` | -| `week` | `Date` | Use `format_dates=false` to return the value in ISO format.
`YYYY-MM-DD - YYYY-MM-DD` | `2021-05-09 - 2021-05-15` | -| `month` | `Date` | Use `format_dates=false` to return the value in ISO format.
`YYYY-MM` | `2021-05` | -| `year` | `Date` | Use `format_dates=false` to return the value in ISO format.
`YYYY` | `2021` | -| `quarter` | `String` | Use `format_dates=false` to return the value in ISO format.
`Q YYYY` | `Q2 2021` | -| `os_name` | `String` | Possible values:
  • `android`
  • `bada`
  • `blackberry`
  • `ios`
  • `linux`
  • `macos`
  • `server`
  • `symbian`
  • `unknown`
  • `webos`
  • `windows`
  • `windows-phone`
| | -| `device_type` | `String` | Possible values:
  • `bot`
  • `console`
  • `ipod`
  • `mac`
  • `pc`
  • `phone`
  • `server`
  • `simulator`
  • `tablet`
  • `tv`
  • `unknown`
| | -| `app` | `String` | Name of the app. | | -| `app_token` | `String` | App ID in the Adjust system. | | -| `store_id` | `String` | Store App ID. | `com.random.app` | -| `store_type` | `String` | Store from where the app was installed. | `google_play` | -| `currency` | `String` | Currency name. | `Euro` | -| `currency_code` | `String` | 3-character value ISO 4217. | `EUR` | -| `network` | `String` | The name of the advertising network. | Organic, AppLovin, Facebook Installs, Instagram Installs. | -| `campaign` | `String` | Link sub-level 1.
String value usually contains campaign name and id. | | -| `campaign_network` | `String` | Campaign name from the network. | | -| `campaign_id_network` | `String` | Campaign ID from the network. | | -| `adgroup` | `String` | Link sub-level 2.
String value usually contains adgroup name and id. | | -| `adgroup_network` | `String` | Adgroup name from the network. | | -| `adgroup_id_network` | `String` | Adgroup ID from the network. | | -| `source_network` | `String` | Name of the source network. Optional value dependent on the network. | | -| `source_id_network` | `String` | ID of the source network. | | -| `creative` | `String` | Link sub-level 3.
String value usually contains creative name and id. | | -| `creative_network` | `String` | Creative name from the network. | | -| `creative_id_network` | `String` | Creative ID from the network. | | -| `country` | `String` | Country name. | `United States of America` | -| `country_code` | `String` | 2-character value ISO 3166. | `US` | -| `region` | `String` | Business region. | `APAC` | -| `partner_name` | `String` | Partner's name in the Adjust system. | `AppLovin` | -| `partner_id` | `String` | Partner’s id in the Adjust system. | `34` | -| `partner` | `String` | The unique slug of the partner. | `applovin` | -| `channel` | `String` | A combination of `partner_name` and `network`. | | -| `platform` | `String` | The device operating system/platform. See list of supported platforms below. | `android` | - - - -- `android` -- `android-tv` -- `bada` -- `blackberry` -- `facebook` -- `fire-tv` -- `ios` -- `linux` -- `macos` -- `server` -- `symbian` -- `webos` -- `windows` -- `windows-phone` - - - -### Metrics {#metrics} - -Metrics are used to assess and compare the performance of campaigns you run and measure with Adjust. - -At least 1 metric is required in each API request. The most common metrics are: - -- `installs` -- `clicks` -- `impressions` - -A full list of metrics is available in the [Datascape metrics glossary](https://help.adjust.com/en/article/datascape-metrics-glossary). You can also use the [Filters Data endpoint](/en/api/rs-api/filters-data) to search for metrics. - -### Response format {#response-format} - -| Parameter | Data Type | Description | -| --------------------- | --------- | ---------------------------------- | -| `app` | `String` | The name of the app | -| `partner_name` | `String` | The name of the partner | -| `campaign` | `String` | The name of the ID of the campaign | -| `campaign_id_network` | `String` | The ID of the campaign | -| `campaign_name` | `String` | The name of the campaign | -| `installs` | `Number` | The number of installs | -| `network_cost` | `Number` | The total network cost of the row | - - - -```text -app,partner_name,campaign,campaign_id_network,campaign_network,installs,network_cost -String,String,String,String,String,Number,Number -``` - - - -### Response codes {#response-codes} - -| Response | Description | Notes | -| -------- | ------------------- | --------------------------------------------------------------------------- | -| `200` | Success | Returns report information | -| `204` | No content | Returned if the response object is empty | -| `400` | Bad request | Returned if your request is malformed or contains unsupported parameters | -| `401` | Unauthorized | Returned if your credentials are incorrect or absent | -| `403` | Forbidden | Returned if you try to access information you don't have permission to view | -| `429` | Too many requests | Returned if you exceed 50 simultaneous requests | -| `503` | Service unavailable | Returned if the server can't be reached | -| `504` | Gateway timeout | Returned if the query takes too long to return a response | - -## Example {#example} - - - -```console -$ curl \ ---header 'Authorization: Bearer ' \ ---location --request GET 'https://automate.adjust.com/reports-service/csv_report?ad_spend_mode=network&app_token__in={app_token1},{app_token2}&date_period=2021-05-01:2021-05-02&dimensions=app,partner_name,campaign,campaign_id_network,campaign_network&metrics=installs,network_cost' -``` - - - - - -```text -app,partner_name,campaign,campaign_id_network,campaign_network,installs,network_cost -App Name,AppLovin,Campaign Name (Campaign ID),Campaign ID,Campaign Network,64,1000 - -``` - - diff --git a/src/content/docs/en/api/rs-api/events.mdx b/src/content/docs/en/api/rs-api/events.mdx deleted file mode 100644 index 1195ab1a4..000000000 --- a/src/content/docs/en/api/rs-api/events.mdx +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: "Events endpoint" -description: "Use the Events endpoint to retrieve event slugs to use in your report service queries." -slug: en/api/rs-api/events -sidebar-position: 3 ---- - -Use the Events endpoint to retrieve event slugs to use in your report service queries. The endpoint enables you to search for events using their readable names and returns useful information about each one. - -## Return events {#return-events} - - - -```http -GET https://automate.adjust.com/reports-service/events -``` - - - -Return a list of event objects. - -### Parameters {#parameters} - -| Parameter | Data type | Required | Description | -| ------------------ | --------- | -------- | ---------------------------------------------------------------------------------------- | -| `events__contains` | `String` | No | Filters events by an exact match in the event's `key` or a partial match in its `value`. | - -### Response parameters {#response-parameters} - -| Parameter | Data type | Description | -| ---------------------- | --------------- | --------------------------------------------------------------------------------------------------- | -| `id` | `String` | The event slug. | -| `name` | `String` | The name of the event. | -| `short_name` | `String` | The shortened name of the event. | -| `section` | `String` | The event section. See the [Sections table](#rs-events-sections) for a summary of available values. | -| `formatting` | `String` | The format in which the event's data is stored. | -| `increase_is_negative` | `Boolean` | Whether the most recent change was a value increase. | -| `app_token` | `Array` | The app token with which the event is associated. | -| `tokens` | `Array` | The event token or tokens. | - -#### Sections {#sections} - -| Section | Description | -| ------------------- | ----------------------------------------------------- | -| `conversion` | Metrics relating to click and impression conversions. | -| `fraud` | Metrics relating to fraud prevention. | -| `cost` | Metrics relating to cost. | -| `revenue` | Metrics relating to app revenue. | -| `retention` | Metrics relating to cohort-based user retention. | -| `events` | Metrics relating to events. | -| `conversion_events` | Metrics relating to SKAdNetwork conversion events. | -| `installs` | Metrics relating to app installs and reinstalls. | -| `conversion_values` | Metrics relating to SKAdNetwork conversion values. | - - - -```json -[ - { - "id": "string", - "name": "string", - "short_name": "", - "section": "", - "formatting": "money", - "increase_is_negative": false, - "description": "", - "app_token": ["string"], - "tokens": ["string"] - } -] -``` - - - -### Responses {#responses} - -This endpoint returns the following responses: - -| Response | Description | Notes | -| -------- | ------------------- | --------------------------------------------------------------------------- | -| `200` | Success | Returns report information | -| `204` | No content | Returned if the response object is empty | -| `400` | Bad request | Returned if your request is malformed or contains unsupported parameters | -| `401` | Unauthorized | Returned if your credentials are incorrect or absent | -| `403` | Forbidden | Returned if you try to access information you don't have permission to view | -| `429` | Too many requests | Returned if you exceed 50 simultaneous requests | -| `503` | Service unavailable | Returned if the server can't be reached | -| `504` | Gateway timeout | Returned if the query takes too long to return a response | - -## Example {#example} - - - -```console -$ curl \ -'https://automate.adjust.com/reports-service/events?events__contains=purchase' \ ---header 'Authorization: Bearer {API_TOKEN}' -``` - - - - - -```json -[ - { - "id": "purchase", - "name": "Purchase event", - "short_name": "PUR", - "section": "Revenue", - "formatting": "money", - "increase_is_negative": false, - "description": "", - "app_token": ["4zb92bmajmrd"], - "tokens": ["abc123"] - } -] -``` - - diff --git a/src/content/docs/en/api/rs-api/filters-data.mdx b/src/content/docs/en/api/rs-api/filters-data.mdx deleted file mode 100644 index 9d090144e..000000000 --- a/src/content/docs/en/api/rs-api/filters-data.mdx +++ /dev/null @@ -1,190 +0,0 @@ ---- -title: Filters data endpoint -description: Use the filters data endpoint to find metrics for your queries -slug: en/api/rs-api/filters-data -sidebar-position: 2 ---- - -The Filters Data endpoint enables you to retrieve a list of valid metrics. You can use these metrics to filter calls to other endpoints in the Report Service API suite. - -A full list of metrics is available in the [Datascape metrics glossary](https://help.adjust.com/en/article/datascape-metrics-glossary). - -## Before you begin {#before-you-begin} - -To use this endpoint, you need an Adjust API token. Follow the instructions in the [authentication guide](/en/api/rs-api/authentication) to get your token. - -## Endpoint {#endpoint-1} - -```http -GET https://automate.adjust.com/reports-service/filters_data -``` - -### GET request {#get-request} - -Return a list of filter items. Use the `id` field of the returned objects to filter other API calls. - -#### Parameters {#parameters} - -| Parameter | Data type | In | Description | -| ------------------------------ | -------------- | ----- | --------------------------------------------------------------------------------------------- | -| `required_filters`\* | `String` | Query | A comma separated list of filters. See the Required filters table below for a list of values. | -| `section` | `Enum` | Query | The section you want to filter items by. See the Section table below for a list of values. | -| `[required_filters]__contains` | `String` | Query | Enter a search term to look for a full or partial match in the object's id and name fields. | - -### Required filters {#required-filters} - -| Filter | Description | -| ---------------------- | ------------------------------------------------------------------------------------------------------- | -| `apps` | Returns a list of your apps. | -| `apps_network` | Returns a list of your apps and their associated store IDs. | -| `overview_metrics` | Returns a list of overview metrics. | -| `skad_metrics` | Returns a list of metrics relating to SKAdNetwork. | -| `cohort_maturity` | Returns a list of metrics relating to the maturity of a cohort. Example: mature, immature. | -| `cohort_metrics` | Returns a list of metrics relating to your cohorts. | -| `event_metrics` | Returns a list of metrics relating to your events. All metrics are duplicated per event. | -| `cost_metrics` | Returns a list of metrics relating to cost. | -| `etl_metrics` | Returns a list of metrics relating to ETL (extract, transform, load) between Adjust and another system. | -| `dimensions` | Returns a list of dimensions. | -| `countries` | Returns a list of countries. | -| `currencies` | Returns a list of currencies. | -| `os_names` | Returns a list of operating system names. | -| `networks` | Returns a list of networks. | -| `partners` | Returns a list of partners. | -| `ad_revenue_sources` | Returns a list of ad revenue sources. | -| `iap_revenue_mode` | Returns a list of ad revenue modes. | -| `attribution_type` | Returns a list of attribution types. Examples: all, click, impression. | -| `attribution_source` | Returns a list of attribution sources. | -| `attribution_status` | Returns a list of attribution statuses. | -| `ad_spend_mode` | Returns a list of cost modes. Examples: attribution, network, mixed. | -| `ad_spend_mode` | Returns a list of ad spend modes. Examples: attribution, network, mixed. | -| `utc_offset` | The offset (in hours) from UTC. Defaults to 0 (UTC). | -| `attributes` | Returns a list of attributes. | -| `index` | Returns a list of key metrics that relate to all apps. | -| `period_over_period` | Returns a list of time periods used for data comparison. | -| `cohort_metric_names` | Returns a list of readable names for cohort metrics. | -| `full_cohort_periods` | Returns a list of time periods related to cohorts. | -| `store_type` | Returns a list of app stores. | -| `skad_time_adjustment` | Returns a list of valid SKAdNetwork activity windows. | - -### Sections {#sections} - -| Section | Description | -| ------------------- | ----------------------------------------------------- | -| `conversion` | Metrics relating to click and impression conversions. | -| `fraud` | Metrics relating to fraud prevention. | -| `cost` | Metrics relating to cost. | -| `revenue` | Metrics relating to app revenue. | -| `retention` | Metrics relating to cohort-based user retention. | -| `events` | Metrics relating to events. | -| `conversion_events` | Metrics relating to SKAdNetwork conversion events. | -| `installs` | Metrics relating to app installs and reinstalls. | -| `conversion_values` | Metrics relating to SKAdNetwork conversion values. | - -### Responses {#responses} - -This endpoint returns the following responses: - -| Response | Message | Notes | -| -------- | --------------------- | --------------------------------------------------------------------------- | -| `200` | `Success` | Returns report information | -| `204` | `No content` | Returned if the response object is empty | -| `400` | `Bad request` | Returned if your request is malformed or contains unsupported parameters | -| `401` | `Unauthorized` | Returned if your credentials are incorrect or absent | -| `403` | `Forbidden` | Returned if you try to access information you don't have permission to view | -| `429` | `Too many requests` | Returned if you exceed 50 simultaneous requests | -| `503` | `Service unavailable` | Returned if the server can't be reached | -| `504` | `Gateway timeout` | Returned if the query takes too long to return a response | - -#### Success response {#success-response} - -```json -{ - "required_filters_1": [ - { - "id": "string", - "name": "string", - "short_name": "string", - "section": "string", - "formatting": "string" - } - ], - "required_filters_2": [ - { - "id": "string", - "name": "string", - "short_name": "string", - "section": "string", - "formatting": "string" - }, - { - "id": "string", - "name": "string", - "short_name": "string", - "section": "string", - "formatting": "string" - } - ] -} -``` - -### Parameters {#parameters} - -| Parameter | Data type | Description | -| ------------ | --------- | -------------------------------------------------------------------------- | -| `id` | `String` | The ID of the filter item. Use this to filter your API calls. | -| `name` | `String` | The readable name of the filter item. | -| `short_name` | `String` | The shortened name of the filter item. | -| `section` | `String` | The section the filter item is associated with. | -| `formatting` | `String` | The data format of the filter item. Example: `money`, `decimal`, `string`. | - -## Example {#example} - - - -```sh -curl --location --request GET 'https://automate.adjust.com/reports-service/filters_data?required_filters=overview_metrics,cost_metrics§ion=cost&overview_metrics__contains=ecpi&cost_metrics__contains=Ad spend' \ ---header 'Authorization: Bearer {API_TOKEN}' -``` - - - - - -```json -{ - "overview_metrics": [ - { - "id": "ecpi_all", - "name": "eCPI (All Installs)", - "short_name": "eCPI (All)", - "section": "Cost", - "formatting": "money" - }, - { - "id": "ecpi", - "name": "eCPI (Paid Installs)", - "short_name": "eCPI (Paid)", - "section": "Cost", - "formatting": "money" - } - ], - "cost_metrics": [ - { - "id": "network_cost", - "name": "Ad Spend (Network)", - "short_name": "", - "section": "Cost", - "formatting": "decimal" - }, - { - "id": "network_cost_diff", - "name": "Ad Spend Diff (Network)", - "short_name": "", - "section": "Cost", - "formatting": "decimal" - } - ] -} -``` - - diff --git a/src/content/docs/en/api/rs-api/index.mdx b/src/content/docs/en/api/rs-api/index.mdx deleted file mode 100644 index 2b3be4a47..000000000 --- a/src/content/docs/en/api/rs-api/index.mdx +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: "Report service API" -description: "Use the Report service API to fetch aggregated data for your apps." -category-title: Report service API -slug: en/api/rs-api -sidebar-position: 1 ---- - -The Report Service API enables you to query Adjust's reporting dataset to retrieve aggregated data. Use these endpoints to filter, sort, and retrieve your Adjust data with ease. - -## 1. Authenticate your calls {#authenticate-your-calls} - -To use the Report Service API endpoints, you first need to get your Adjust API token. Follow the instructions in the [Authentication article](/en/api/rs-api/authentication) to find out how to use this token with the API. - -## 2. Find your metrics {#find-your-metrics} - -Adjust supports a lot of metrics that you can use to filter your reports. Many of these metrics exist on a per-app or per-event basis. - -A full list of metrics is available in the [Datascape metrics glossary](https://help.adjust.com/en/article/datascape-metrics-glossary). You can also use the [Filters Data endpoint](/en/api/rs-api/filters-data) to search for metrics and the [Events endpoint](/en/api/rs-api/events) to return the machine-generated slugs of your events for use in CSV reports. - -## 3. Choose your response format {#choose-your-response-format} - -The Report Service API contains endpoints for three different report formats. Choose the endpoint that matches the format you want to receive: - -- Reports endpoint: returns data as JSON. -- CSV reports endpoint: returns data as CSV. -- Pivot reports endpoint: returns data as JSON with a field that breaks down totals by dimension. diff --git a/src/content/docs/en/api/rs-api/pivot.mdx b/src/content/docs/en/api/rs-api/pivot.mdx deleted file mode 100644 index 3ed1e5386..000000000 --- a/src/content/docs/en/api/rs-api/pivot.mdx +++ /dev/null @@ -1,267 +0,0 @@ ---- -title: "Pivot report endpoint" -description: "The reports endpoint enables you to combine data from many services in a single pivot report." -slug: en/api/rs-api/pivot -sidebar-position: 6 ---- - -Pivot Report Service provides an API to get aggregated data from different sources: KPI Service metrics, KPI Service cohorts, SKAdNetwork, and Ad Spend. - -The reports endpoint enables you to combine data from many services in a single report. Request installs, revenue, ad spend, and SKAdNetwork data divided by day, app, and ad network. - -## Fetch pivot report {#fetch-pivot-report} - - - -```http -GET https://automate.adjust.com/reports-service/pivot_report -``` - - - -The `GET` method returns filtered data from the report service in JSON format. - -### Filters {#filters} - -| Filter | Type | Description | Example | -| ------------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `dimensions`\* | `String` | Comma-separated values used to group parameters. See the dimensions table below for more information. | `dimensions=app,os_name,week,campaign_id_network` | -| `metrics`\* | `String` | Comma-separated KPIs. See the metrics table below for more information. | `metrics=cost,installs,ecpi_network` | -| `date_period`\* | `String` | Start and end dates for the report with 3 supported formats:
  • Logical dates
  • Absolute dates
  • Relative dates
|
  • **Logical dates:**
    • `this_month_until_yesterday`
    • `today`
    • `yesterday`
    • `this_week`
    • `last_week`
    • `this_month`
    • `last_month`
  • **Absolute dates:**
    • `2020-12-31:2021-01-01`
  • **Relative dates:**
    • `-10d:-3d (from 10 days ago to 3 days ago)`
| -| `cohort_maturity` | `String` |
  • `immature`: displays current values of cumulative metrics for all cohorts, including immature cohorts.
  • `mature`: displays the values of cumulative metrics only for mature cohorts and zeros for immature cohorts.
| `cohort_maturity=immature` | -| `utc_offset` | `String` | The timezone used in the report. | `utc_offset=+01:00` | -| `attribution_type` | `String` | The type of engagement the attribution awards.
  • `click` (default)
  • `impression`
  • `all`
| `attribution_type=click` | -| `attribution_source` | `String` | Whether in-app activity is assigned to the user’s install source (`first`) or divided among the install source and subsequent sources of reattribution (`dynamic`). Defaults to `dynamic`. | `attribution_source=first` | -| `reattributed` | `String` | Filter for reattributed users only. Reattribution is when a user who has already installed your app returns to it through a new Adjust-measured source.
  • `all` (default)
  • `false`
  • `true`
| `reattributed=false` | -| `iap_revenue_mode` | `String` | The percentage of gross ad revenue returned by the endpoint. Available options are:
  • `GROSS_100`
  • `GROSS_85`
  • `GROSS_70`
  • `GROSS_60`
| `iap_revenue_mode=GROSS_70` | -| `ad_revenue_sources` | `String` | Comma-separated list of ad revenue sources. | `ad_revenue_sources=unknown` | -| `os_names` | `String` | Comma-separated list of operating system names. | `os_names=ios,android` | -| `ad_spend_mode` | `String` | Determines the ad spend source applied in calculations. See How ad spend source affects your data for more information.
  • `adjust`
  • `network`
  • `mixed`
| `ad_spend_mode=network` | -| `sandbox` | `Boolean` | Whether to use sandbox data or production data. Defaults to `false`. | `sandbox=true` | -| `sort` | `String` | Comma-separated list of metrics/dimensions to sort the report by. Use `-` to order descending. | `sort=-clicks,installs` | -| `drilldown` | `String` | List of parameters to drill down into. Formatted as pipe-separated tuples. | `drilldown=campaign:123\|adgroup:234` | -| `focus` | `String` | List of parameters to focus on. Formatted as pipe-separated tuples. Differs from drilldown as it doesn't add extra dimensions to the results. | `focus=campaign:123\|adgroup:234` | -| `index` | `String` | Comma-separated list of dimensions used to index the report. | `index=network,campaign,adgroup` | -| `format_dates` | `Boolean` | If set to `false`, all date dimensions are returned in ISO format. | `format_dates=false` | -| `period_over_period` | `String` | The period for comparing report data. | `period_over_period=previous_week` | -| `currency` | `String` | Currency used for conversion of money related metrics. | `currency=USD` | -| `[dimension]__in` | `String` | Comma-separated list of values to filter dimension's values (exact match) for any dimension. | `campaign__in=abc,def` | -| `[dimension]__not_in` | `String` | Comma-separated list of values to filter dimension's values (exclude exact match) for any dimension | `campaign__not_in=abc,def` | -| `[dimension]__contains` | `String` | Substring search in dimension's values (case insensitive) for any dimension. | `campaign__contains=ios` | -| `[dimension]__exclude` | `String` | Excluding substring search in dimension's values (case insensitive) for any dimension. | `campaign__exclude=ios` | -| `[dimension]__starts_with` | `String` | Substring search matching dimensions starting with specified prefix (case insensitive). | `campaign__starts_with=ios` | -| `[dimension]__not_starts_with` | `String` | Substring search matching dimensions not starting with specified prefix (case insensitive). | `campaign__not_starts_with=ios` | -| `[dimension]__ends_with` | `String` | Substring search matching dimensions ending with specified suffix (case insensitive). | `campaign__ends_with=ios` | -| `[dimension]__not_ends_with` | `String` | Substring search matching dimensions not ending with specified suffix (case insensitive). | `campaign__not_ends_with=ios` | -| `[metric]__lt` | `String` | "Less than" filter for metric's values any metric. | `skad_installs__lt=100` | -| `[metric]__lte` | `String` | "Less than or equal" filter for metric's values for any metric. | `skad_installs__lte=100` | -| `[metric]__gt` | `String` | "Greater than" filter for metric's values for any metric. | `skad_installs__gt=100` | -| `[metric]__gte` | `String` | "Greater than or equal" filter for metric's values for any metric. | `skad_installs__gte=100` | -| `[metric]__eq` | `String` | "Equal" filter for metric's values for any metric. | `skad_installs__eq=100` | -| `[metric]__ne` | `String` | "Not equal" filter for values relating to any metric. | `skad_installs__ne=100` | - -### Dimensions {#dimensions} - -Dimensions allow a user to break down metrics into groups using one or several parameters. For example, the number of installs by date, country and network. - -| Dimension | Data type | Description | Example | -| --------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | -| `hour` | `Date` | Use `format_dates=false` to return the value in ISO format.
`YYYY-MM-DDTHH:MM:SS` | `2021-05-11T17:00:45` | -| `day` | `Date` | Use `format_dates=false` to return the value in ISO format.
`YYYY-MM-DD` | `2021-05-11` | -| `week` | `Date` | Use `format_dates=false` to return the value in ISO format.
`YYYY-MM-DD - YYYY-MM-DD` | `2021-05-09 - 2021-05-15` | -| `month` | `Date` | Use `format_dates=false` to return the value in ISO format.
`YYYY-MM` | `2021-05` | -| `year` | `Date` | Use `format_dates=false` to return the value in ISO format.
`YYYY` | `2021` | -| `quarter` | `String` | Use `format_dates=false` to return the value in ISO format.
`Q YYYY` | `Q2 2021` | -| `os_name` | `String` | Possible values:
  • `android`
  • `bada`
  • `blackberry`
  • `ios`
  • `linux`
  • `macos`
  • `server`
  • `symbian`
  • `unknown`
  • `webos`
  • `windows`
  • `windows-phone`
| | -| `device_type` | `String` | Possible values:
  • `bot`
  • `console`
  • `ipod`
  • `mac`
  • `pc`
  • `phone`
  • `server`
  • `simulator`
  • `tablet`
  • `tv`
  • `unknown`
| | -| `app` | `String` | Name of the app. | | -| `app_token` | `String` | App ID in the Adjust system. | | -| `store_id` | `String` | Store App ID. | `com.random.app` | -| `store_type` | `String` | Store from where the app was installed. | `google_play` | -| `currency` | `String` | Currency name. | `Euro` | -| `currency_code` | `String` | 3-character value ISO 4217. | `EUR` | -| `network` | `String` | The name of the advertising network. | Organic, AppLovin, Facebook Installs, Instagram Installs. | -| `campaign` | `String` | Link sub-level 1.
String value usually contains campaign name and id. | | -| `campaign_network` | `String` | Campaign name from the network. | | -| `campaign_id_network` | `String` | Campaign ID from the network. | | -| `adgroup` | `String` | Link sub-level 2.
String value usually contains adgroup name and id. | | -| `adgroup_network` | `String` | Adgroup name from the network. | | -| `adgroup_id_network` | `String` | Adgroup ID from the network. | | -| `source_network` | `String` | Name of the source network. Optional value dependent on the network. | | -| `source_id_network` | `String` | ID of the source network. | | -| `creative` | `String` | Link sub-level 3.
String value usually contains creative name and id. | | -| `creative_network` | `String` | Creative name from the network. | | -| `creative_id_network` | `String` | Creative ID from the network. | | -| `country` | `String` | Country name. | `United States of America` | -| `country_code` | `String` | 2-character value ISO 3166. | `US` | -| `region` | `String` | Business region. | `APAC` | -| `partner_name` | `String` | Partner's name in the Adjust system. | `AppLovin` | -| `partner_id` | `String` | Partner’s id in the Adjust system. | `34` | -| `partner` | `String` | The unique slug of the partner. | `applovin` | -| `channel` | `String` | A combination of `partner_name` and `network`. | | -| `platform` | `String` | The device operating system/platform. See list of supported platforms below. | `android` | - - - -- `android` -- `android-tv` -- `bada` -- `blackberry` -- `facebook` -- `fire-tv` -- `ios` -- `linux` -- `macos` -- `server` -- `symbian` -- `webos` -- `windows` -- `windows-phone` - - - -### Metrics {#metrics} - -Metrics are used to assess and compare the performance of campaigns you run and measure with Adjust. - -At least 1 metric is required in each API request. The most common metrics are: - -- `installs` -- `clicks` -- `impressions` - -A full list of metrics is available in the [Datascape metrics glossary](https://help.adjust.com/en/article/datascape-metrics-glossary). You can also use the [Filters Data endpoint](/en/api/rs-api/filters-data) to search for metrics. - -### Response format {#response-format} - - - -```json -{ - "rows": [ - { - "attr_dependency": {}, - "app": "App Name", - "partner_name": "AppLovin", - "campaign": "Campaign Name (Campaign ID)", - "campaign_id_network": "Campaign ID", - "campaign_network": "Campaign Name", - "installs": "64", - "cost": "1000" - } - ], - "totals": { - "installs": 64, - "cost": 1000 - }, - "warnings": [], - "totals_per_dimension": {} -} -``` - - - -### Response codes {#response-codes} - -This endpoint returns the following responses: - -| Response | Description | Notes | -| -------- | ------------------- | --------------------------------------------------------------------------- | -| `200` | Success | Returns report information | -| `204` | No content | Returned if the response object is empty | -| `400` | Bad request | Returned if your request is malformed or contains unsupported parameters | -| `401` | Unauthorized | Returned if your credentials are incorrect or absent | -| `403` | Forbidden | Returned if you try to access information you don't have permission to view | -| `429` | Too many requests | Returned if you exceed 50 simultaneous requests | -| `503` | Service unavailable | Returned if the server can't be reached | -| `504` | Gateway timeout | Returned if the query takes too long to return a response | - -## Example {#example} - - - -```console -$ curl \ ---header 'Authorization: Bearer ' \ --L -X GET 'https://automate.adjust.com/reports-service/pivot_report?ad_spend_mode=network&app_token__in={app_token1},{app_token2}&date_period=2021-05-01:2021-05-02&dimensions=app,partner_name,campaign,campaign_id_network,campaign_network&metrics=installs,network_installs,network_cost,network_ecpi&index=app' \ -``` - - - - - -```json -{ - "rows": [ - { - "Test App": { - "rows": [ - { - "attr_dependency": { - "app_network": ["google_play:com.test.app"] - }, - "campaign_id_network": "123", - "campaign_network": "Campaign Name", - "campaign": "Campaign Name (123)", - "partner_name": "MyPartner", - "installs": 10, - "network_installs": 0, - "network_cost": 0, - "network_ecpi": 0 - } - ] - } - } - ], - "totals": { - "installs": 10, - "network_installs": 0, - "network_cost": 0, - "network_ecpi": 0 - }, - "totals_per_dimension": { - "campaign_id_network": { - "Organic": { - "installs": 10, - "network_installs": 0, - "network_cost": 0, - "network_ecpi": 0 - } - }, - "campaign_network": { - "Organic": { - "installs": 10, - "network_installs": 0, - "network_cost": 0, - "network_ecpi": 0 - } - }, - "app": { - "adjust Demo App": { - "installs": 10, - "network_installs": 0, - "network_cost": 0, - "network_ecpi": 0 - } - }, - "campaign": { - "Organic": { - "installs": 10, - "network_installs": 0, - "network_cost": 0, - "network_ecpi": 0 - } - }, - "partner_name": { - "Organic": { - "installs": 10, - "network_installs": 0, - "network_cost": 0, - "network_ecpi": 0 - } - } - } -} -``` - - diff --git a/src/content/docs/en/api/rs-api/reports.mdx b/src/content/docs/en/api/rs-api/reports.mdx deleted file mode 100644 index b5e91a448..000000000 --- a/src/content/docs/en/api/rs-api/reports.mdx +++ /dev/null @@ -1,219 +0,0 @@ ---- -title: "Reports endpoint" -description: "The reports endpoint enables you to combine data from many services in a single report." -slug: en/api/rs-api/reports -sidebar-position: 4 ---- - -The reports endpoint enables you to combine data from many services in a single report. Request installs, revenue, ad spend, and SKAdNetwork data divided by day, app, and ad network. - -## Fetch JSON report {#fetch-json-report} - - - -```http -GET https://automate.adjust.com/reports-service/report -``` - - - -Returns filtered data from the report service in JSON format. - -### Filters {#filters} - -| Filter | Type | Description | Example | -| ------------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `dimensions`\* | `String` | Comma-separated values used to group parameters. See the dimensions table below for more information. | `dimensions=app,os_name,week,campaign_id_network` | -| `metrics`\* | `String` | Comma-separated KPIs. See the metrics table below for more information. | `metrics=cost,installs,ecpi_network` | -| `date_period`\* | `String` | Start and end dates for the report with 3 supported formats:
  • Logical dates
  • Absolute dates
  • Relative dates
|
  • **Logical dates:**
    • `this_month_until_yesterday`
    • `today`
    • `yesterday`
    • `this_week`
    • `last_week`
    • `this_month`
    • `last_month`
  • **Absolute dates:**
    • `2020-12-31:2021-01-01`
  • **Relative dates:**
    • `-10d:-3d (from 10 days ago to 3 days ago)`
| -| `cohort_maturity` | `String` |
  • `immature`: displays current values of cumulative metrics for all cohorts, including immature cohorts.
  • `mature`: displays the values of cumulative metrics only for mature cohorts and zeros for immature cohorts.
| `cohort_maturity=immature` | -| `utc_offset` | `String` | The timezone used in the report. | `utc_offset=+01:00` | -| `attribution_type` | `String` | The type of engagement the attribution awards.
  • `click` (default)
  • `impression`
  • `all`
| `attribution_type=click` | -| `attribution_source` | `String` | Whether in-app activity is assigned to the user’s install source (`first`) or divided among the install source and subsequent sources of reattribution (`dynamic`). Defaults to `dynamic`. | `attribution_source=first` | -| `reattributed` | `String` | Filter for reattributed users only. Reattribution is when a user who has already installed your app returns to it through a new Adjust-measured source.
  • `all` (default)
  • `false`
  • `true`
| `reattributed=false` | -| `iap_revenue_mode` | `String` | The percentage of gross ad revenue returned by the endpoint. Available options are:
  • `GROSS_100`
  • `GROSS_85`
  • `GROSS_70`
  • `GROSS_60`
| `iap_revenue_mode=GROSS_70` | -| `ad_revenue_sources` | `String` | Comma-separated list of ad revenue sources. | `ad_revenue_sources=unknown` | -| `os_names` | `String` | Comma-separated list of operating system names. | `os_names=ios,android` | -| `ad_spend_mode` | `String` | Determines the ad spend source applied in calculations. See How ad spend source affects your data for more information.
  • `adjust`
  • `network`
  • `mixed`
| `ad_spend_mode=network` | -| `sandbox` | `Boolean` | Whether to use sandbox data or production data. Defaults to `false`. | `sandbox=true` | -| `sort` | `String` | Comma-separated list of metrics/dimensions to sort the report by. Use `-` to order descending. | `sort=-clicks,installs` | -| `index` | `String` | Comma-separated list of dimensions used to index the report. | `index=network,campaign,adgroup` | -| `format_dates` | `Boolean` | If set to `false`, all date dimensions are returned in ISO format. | `format_dates=false` | -| `period_over_period` | `String` | The period for comparing report data. | `period_over_period=previous_week` | -| `currency` | `String` | Currency used for conversion of money related metrics. | `currency=USD` | -| `[dimension]__in` | `String` | Comma-separated list of values to filter dimension's values (exact match) for any dimension. | `campaign__in=abc,def` | -| `[dimension]__not_in` | `String` | Comma-separated list of values to filter dimension's values (exclude exact match) for any dimension | `campaign__not_in=abc,def` | -| `[dimension]__contains` | `String` | Substring search in dimension's values (case insensitive) for any dimension. | `campaign__contains=ios` | -| `[dimension]__exclude` | `String` | Excluding substring search in dimension's values (case insensitive) for any dimension. | `campaign__exclude=ios` | -| `[dimension]__starts_with` | `String` | Substring search matching dimensions starting with specified prefix (case insensitive). | `campaign__starts_with=ios` | -| `[dimension]__not_starts_with` | `String` | Substring search matching dimensions not starting with specified prefix (case insensitive). | `campaign__not_starts_with=ios` | -| `[dimension]__ends_with` | `String` | Substring search matching dimensions ending with specified suffix (case insensitive). | `campaign__ends_with=ios` | -| `[dimension]__not_ends_with` | `String` | Substring search matching dimensions not ending with specified suffix (case insensitive). | `campaign__not_ends_with=ios` | -| `[metric]__lt` | `String` | "Less than" filter for metric's values any metric. | `skad_installs__lt=100` | -| `[metric]__lte` | `String` | "Less than or equal" filter for metric's values for any metric. | `skad_installs__lte=100` | -| `[metric]__gt` | `String` | "Greater than" filter for metric's values for any metric. | `skad_installs__gt=100` | -| `[metric]__gte` | `String` | "Greater than or equal" filter for metric's values for any metric. | `skad_installs__gte=100` | -| `[metric]__eq` | `String` | "Equal" filter for metric's values for any metric. | `skad_installs__eq=100` | -| `[metric]__ne` | `String` | "Not equal" filter for values relating to any metric. | `skad_installs__ne=100` | - -### Dimensions {#dimensions} - -Dimensions allow a user to break down metrics into groups using one or several parameters. For example, the number of installs by date, country and network. - -| Dimension | Data type | Description | Example | -| --------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | -| `hour` | `Date` | Use `format_dates=false` to return the value in ISO format.
`YYYY-MM-DDTHH:MM:SS` | `2021-05-11T17:00:45` | -| `day` | `Date` | Use `format_dates=false` to return the value in ISO format.
`YYYY-MM-DD` | `2021-05-11` | -| `week` | `Date` | Use `format_dates=false` to return the value in ISO format.
`YYYY-MM-DD - YYYY-MM-DD` | `2021-05-09 - 2021-05-15` | -| `month` | `Date` | Use `format_dates=false` to return the value in ISO format.
`YYYY-MM` | `2021-05` | -| `year` | `Date` | Use `format_dates=false` to return the value in ISO format.
`YYYY` | `2021` | -| `quarter` | `String` | Use `format_dates=false` to return the value in ISO format.
`Q YYYY` | `Q2 2021` | -| `os_name` | `String` | Possible values:
  • `android`
  • `bada`
  • `blackberry`
  • `ios`
  • `linux`
  • `macos`
  • `server`
  • `symbian`
  • `unknown`
  • `webos`
  • `windows`
  • `windows-phone`
| | -| `device_type` | `String` | Possible values:
  • `bot`
  • `console`
  • `ipod`
  • `mac`
  • `pc`
  • `phone`
  • `server`
  • `simulator`
  • `tablet`
  • `tv`
  • `unknown`
| | -| `app` | `String` | Name of the app. | | -| `app_token` | `String` | App ID in the Adjust system. | | -| `store_id` | `String` | Store App ID. | `com.random.app` | -| `store_type` | `String` | Store from where the app was installed. | `google_play` | -| `currency` | `String` | Currency name. | `Euro` | -| `currency_code` | `String` | 3-character value ISO 4217. | `EUR` | -| `network` | `String` | The name of the advertising network. | Organic, AppLovin, Facebook Installs, Instagram Installs. | -| `campaign` | `String` | Link sub-level 1.
String value usually contains campaign name and id. | | -| `campaign_network` | `String` | Campaign name from the network. | | -| `campaign_id_network` | `String` | Campaign ID from the network. | | -| `adgroup` | `String` | Link sub-level 2.
String value usually contains adgroup name and id. | | -| `adgroup_network` | `String` | Adgroup name from the network. | | -| `adgroup_id_network` | `String` | Adgroup ID from the network. | | -| `source_network` | `String` | Name of the source network. Optional value dependent on the network. | | -| `source_id_network` | `String` | ID of the source network. | | -| `creative` | `String` | Link sub-level 3.
String value usually contains creative name and id. | | -| `creative_network` | `String` | Creative name from the network. | | -| `creative_id_network` | `String` | Creative ID from the network. | | -| `country` | `String` | Country name. | `United States of America` | -| `country_code` | `String` | 2-character value ISO 3166. | `US` | -| `region` | `String` | Business region. | `APAC` | -| `partner_name` | `String` | Partner's name in the Adjust system. | `AppLovin` | -| `partner_id` | `String` | Partner’s id in the Adjust system. | `34` | -| `partner` | `String` | The unique slug of the partner. | `applovin` | -| `channel` | `String` | A combination of `partner_name` and `network`. | | -| `platform` | `String` | The device operating system/platform. See list of supported platforms below. | `android` | - - - -- `android` -- `android-tv` -- `bada` -- `blackberry` -- `facebook` -- `fire-tv` -- `ios` -- `linux` -- `macos` -- `server` -- `symbian` -- `webos` -- `windows` -- `windows-phone` - - - -### Metrics {#metrics} - -Metrics are used to assess and compare the performance of campaigns you run and measure with Adjust. - -At least 1 metric is required in each request. The most common metrics are: - -- `installs` -- `clicks` -- `impressions` - -A full list of metrics is available in the [Datascape metrics glossary](https://help.adjust.com/en/article/datascape-metrics-glossary). You can also use the [Filters Data endpoint](/en/api/rs-api/filters-data) to search for metrics. - -### Response format {#response-format} - - - -```json -{ - "rows": [ - { - "attr_dependency": {}, - "app": "App Name", - "partner_name": "AppLovin", - "campaign": "Campaign Name (Campaign ID)", - "campaign_id_network": "Campaign ID", - "campaign_network": "Campaign Name", - "installs": "64", - "cost": "1000" - } - ], - "totals": { - "installs": 64, - "cost": 1000 - }, - "warnings": [] -} -``` - - - -### Response codes {#response-codes} - -This endpoint returns the following responses: - -| Response | Description | Notes | -| -------- | ------------------- | --------------------------------------------------------------------------- | -| `200` | Success | Returns report information | -| `204` | No content | Returned if the response object is empty | -| `400` | Bad request | Returned if your request is malformed or contains unsupported parameters | -| `401` | Unauthorized | Returned if your credentials are incorrect or absent | -| `403` | Forbidden | Returned if you try to access information you don't have permission to view | -| `429` | Too many requests | Returned if you exceed 50 simultaneous requests | -| `503` | Service unavailable | Returned if the server can't be reached | -| `504` | Gateway timeout | Returned if the query takes too long to return a response | - -## Example {#example} - - - -```console -$ curl \ ---header 'Authorization: Bearer ' \ ---location --request GET 'https://automate.adjust.com/reports-service/report?ad_spend_mode=network&app_token__in={app_token1},{app_token2}&date_period=2021-05-01:2021-05-02&dimensions=app,partner_name,campaign,campaign_id_network,campaign_network&metrics=installs,network_installs,network_cost,network_ecpi' -``` - - - - - -```json -{ - "rows": [ - { - "attr_dependency": { - "campaign_id_network": "unknown", - "partner_id": "-300", - "partner": "Organic" - }, - "app": "Test app", - "partner_name": "Organic", - "campaign": "unknown", - "campaign_id_network": "unknown", - "campaign_network": "unknown", - "installs": "10", - "network_installs": "0", - "network_cost": "0.0", - "network_ecpi": "0.0" - } - ], - "totals": { - "installs": 10.0, - "network_installs": 0.0, - "network_cost": 0.0, - "network_ecpi": 0.0 - }, - "warnings": [], - "pagination": null -} -``` - - diff --git a/src/redirects.json b/src/redirects.json index 843d9820d..4cf3ddd31 100644 --- a/src/redirects.json +++ b/src/redirects.json @@ -31,5 +31,12 @@ "/sdk/cordova/migration": "/sdk/migration/cordova", "/sdk/cordova/migration/v4-to-v5": "/sdk/migration/cordova/v4-to-v5", "/sdk/react-native/migration": "/sdk/migration/react-native", - "/sdk/react-native/migration/v4-to-v5": "/sdk/migration/react-native/v4-to-v5" + "/sdk/react-native/migration/v4-to-v5": "/sdk/migration/react-native/v4-to-v5", + "/en/api/rs-api": "/en/api/reports-service", + "/en/api/rs-api/authentication": "/en/api/reports-service#authentication", + "/en/api/rs-api/filters-data": "/en/api/reports-service#retrieve-filters", + "/en/api/rs-api/events": "/en/api/reports-service#retrieve-event-slugs", + "/en/api/rs-api/reports": "/en/api/reports-service#fetch-json-report", + "/en/api/rs-api/pivot": "/en/api/reports-service#fetch-pivot-report", + "/en/api/rs-api/csv": "/en/api/reports-service#fetch-csv-report" } From 2a782396d813d8015b1f6de815e099960d0c3f83 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Fri, 25 Oct 2024 09:47:16 +0200 Subject: [PATCH 03/10] Fix typos --- src/content/docs/en/api/reports-service.mdoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/api/reports-service.mdoc b/src/content/docs/en/api/reports-service.mdoc index 3b370d5c8..e2b5a8ce0 100644 --- a/src/content/docs/en/api/reports-service.mdoc +++ b/src/content/docs/en/api/reports-service.mdoc @@ -48,7 +48,7 @@ The Reports Service API When querying the Reports Service API, you need to filter your reporting data. The Reports Service API supports different filters such as metrics and dimensions. A full list of metrics is available in the [Datascape metrics glossary](https://help.adjust.com/en/article/datascape-metrics-glossary) and a full list of dimensions is available in the [Datascape dimensions glossary](https://help.adjust.com/en/article/datascape-dimensions-glossary). -You can fetch filters programatically using the `filters_data` endpoint. This endpoint returns a full representation of all matching filters. +You can fetch filters programmatically using the `filters_data` endpoint. This endpoint returns a full representation of all matching filters. ```http GET https://automate.adjust.com/reports-service/filters_data @@ -420,7 +420,7 @@ You MAY pass the following as **query parameters**: `[dimension]__exclude`: `String` -: A substring to filter a given dimension's value by. Exludes partial or exact matches. +: A substring to filter a given dimension's value by. Excludes partial or exact matches. `[dimension]__starts_with`: `String` From 22bfcaeaf6d36c0992fb206cdb0cee0677514f6c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Fri, 25 Oct 2024 09:56:44 +0200 Subject: [PATCH 04/10] Improve syntax highlighting --- src/content/docs/en/api/reports-service.mdoc | 35 +++++++++++--------- 1 file changed, 20 insertions(+), 15 deletions(-) diff --git a/src/content/docs/en/api/reports-service.mdoc b/src/content/docs/en/api/reports-service.mdoc index e2b5a8ce0..65c2fcf10 100644 --- a/src/content/docs/en/api/reports-service.mdoc +++ b/src/content/docs/en/api/reports-service.mdoc @@ -19,10 +19,10 @@ By default, the Reports Service API queries only data relating to the first acco To specify which account you want to query data for, pass your account ID as an `X-Account-ID` header in each request. -```console +```sh curl --location "https://automate.adjust.com/reports-service/filters_data?required_filters=overview_metrics%2Ccost_metrics§ion=cost&overview_metrics__contains=ecpi&cost_metrics__contains=Ad%20spend" \ ---header "Authorization: Bearer {YOUR_API_TOKEN}" ---header "X-Account-ID: {YOUR_ACCOUNT_ID}" + --header "Authorization: Bearer {YOUR_API_TOKEN}" \ + --header "X-Account-ID: {YOUR_ACCOUNT_ID}" ``` ## Response codes {% #response-codes %} @@ -145,9 +145,10 @@ The following sections are available: #### Example -```console +```sh curl --location "https://automate.adjust.com/reports-service/filters_data?required_filters=overview_metrics%2Ccost_metrics§ion=cost&overview_metrics__contains=ecpi&cost_metrics__contains=Ad%20spend" \ ---header "Authorization: Bearer {YOUR_API_TOKEN}" + --header "Authorization: Bearer {YOUR_API_TOKEN}" \ + --header "X-Account-ID: {YOUR_ACCOUNT_ID}" ``` ```json @@ -271,9 +272,10 @@ You MAY pass the following as a **query parameter**: #### Example -```console +```sh curl --location "https://automate.adjust.com/reports-service/events?events__contains=purchase&tokens_mapping=true" \ ---header "Authorization: Bearer {YOUR_API_TOKEN}" + --header "Authorization: Bearer {YOUR_API_TOKEN}" \ + --header "X-Account-ID: {YOUR_ACCOUNT_ID}" ``` ```json @@ -498,9 +500,10 @@ GET https://automate.adjust.com/reports-service/report #### Example -```console +```sh $ curl --location "https://automate.adjust.com/reports-service/report?ad_spend_mode=network&app_token__in={app_token1},{app_token2}&date_period=2024-05-01:2024-05-02&dimensions=app,partner_name,campaign,campaign_id_network,campaign_network&metrics=installs,network_installs,network_cost,network_ecpi" \ ---header "Authorization: Bearer {YOUR_API_TOKEN}" + --header "Authorization: Bearer {YOUR_API_TOKEN}" \ + --header "X-Account-ID: {YOUR_ACCOUNT_ID}" ``` ```json @@ -580,9 +583,10 @@ In addition to the [mandatory parameters for each endpoint](#report-parameters), #### Example -```console +```sh curl --location "https://automate.adjust.com/reports-service/pivot_report?ad_spend_mode=network&app_token__in={app_token1},{app_token2}&date_period=2021-05-01:2021-05-02&dimensions=app,partner_name,campaign,campaign_id_network,campaign_network&metrics=installs,network_installs,network_cost,network_ecpi&index=app" \ ---header 'Authorization: Bearer {YOUR_API_TOKEN}' + --header "Authorization: Bearer {YOUR_API_TOKEN}" \ + --header "X-Account-ID: {YOUR_ACCOUNT_ID}" ``` ```json @@ -688,12 +692,13 @@ String,String,String,String,String,Number,Number #### Example -```console -curl --location "https://automate.adjust.com/reports-service/csv_report?ad_spend_mode=network&app_token__in={app_token1},{app_token2}&date_period=2021-05-01:2021-05-02&dimensions=app,partner_name,campaign,campaign_id_network,campaign_network&metrics=installs,network_cost" ---header "Authorization: Bearer {YOUR_API_TOKEN}" +```sh +curl --location "https://automate.adjust.com/reports-service/csv_report?ad_spend_mode=network&app_token__in={app_token1},{app_token2}&date_period=2021-05-01:2021-05-02&dimensions=app,partner_name,campaign,campaign_id_network,campaign_network&metrics=installs,network_cost" \ + --header "Authorization: Bearer {YOUR_API_TOKEN}" \ + --header "X-Account-ID: {YOUR_ACCOUNT_ID}" ``` -```text +```csv app,partner_name,campaign,campaign_id_network,campaign_network,installs,network_cost App Name,AppLovin,Campaign Name (Campaign ID),Campaign ID,Campaign Network,64,1000 ``` From 98a8f22ec03872f7e7d878697d5c45db653c51bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Fri, 25 Oct 2024 10:15:51 +0200 Subject: [PATCH 05/10] Remove leading token --- src/content/docs/en/api/reports-service.mdoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/api/reports-service.mdoc b/src/content/docs/en/api/reports-service.mdoc index 65c2fcf10..8c2d48512 100644 --- a/src/content/docs/en/api/reports-service.mdoc +++ b/src/content/docs/en/api/reports-service.mdoc @@ -501,7 +501,7 @@ GET https://automate.adjust.com/reports-service/report #### Example ```sh -$ curl --location "https://automate.adjust.com/reports-service/report?ad_spend_mode=network&app_token__in={app_token1},{app_token2}&date_period=2024-05-01:2024-05-02&dimensions=app,partner_name,campaign,campaign_id_network,campaign_network&metrics=installs,network_installs,network_cost,network_ecpi" \ +curl --location "https://automate.adjust.com/reports-service/report?ad_spend_mode=network&app_token__in={app_token1},{app_token2}&date_period=2024-05-01:2024-05-02&dimensions=app,partner_name,campaign,campaign_id_network,campaign_network&metrics=installs,network_installs,network_cost,network_ecpi" \ --header "Authorization: Bearer {YOUR_API_TOKEN}" \ --header "X-Account-ID: {YOUR_ACCOUNT_ID}" ``` From 405266088af52667d3b0b6b4c29329efb17df44d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Fri, 25 Oct 2024 14:06:50 +0200 Subject: [PATCH 06/10] Clarify wording --- src/content/docs/en/api/reports-service.mdoc | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/src/content/docs/en/api/reports-service.mdoc b/src/content/docs/en/api/reports-service.mdoc index 8c2d48512..59fc7a4a7 100644 --- a/src/content/docs/en/api/reports-service.mdoc +++ b/src/content/docs/en/api/reports-service.mdoc @@ -9,15 +9,16 @@ Use the Reports Service API to query Adjust's reporting dataset for aggregated d {% partial file="./_authentication.mdoc" /%} -### Use multiple accounts {% #use-multiple-accounts %} +### Select reporting account {% #select-reporting-account %} -By default, the Reports Service API queries only data relating to the first account your user is associated with. To query data from another account, follow these steps: +When you create a user in Adjust, it's associated with the account you're logged into at the time. By default, the Reports Service API returns data related to the first account associated with your user. + +If your user is associated with multiple accounts, you can choose which account you want to query by passing the account ID in an `X-Account-ID` header. To do this: 1. Select the account icon ({% icon type="Person" /%}) 1. Select **Change account**. 1. Search for the account you want to query in the pop-up that appears. The account ID is written in parentheses after the account name. - -To specify which account you want to query data for, pass your account ID as an `X-Account-ID` header in each request. +1. Pass the account ID as an `X-Account-ID` header in each request. ```sh curl --location "https://automate.adjust.com/reports-service/filters_data?required_filters=overview_metrics%2Ccost_metrics§ion=cost&overview_metrics__contains=ecpi&cost_metrics__contains=Ad%20spend" \ @@ -40,9 +41,9 @@ The Reports Service API returns the following response codes for each endpoint: | `503` | `Service unavailable` | Returned if the server can't be reached | | `504` | `Gateway timeout` | Returned if the query takes too long to return a response | -## Fetch required information {% #fetch-required-information %} +## Fetch required data {% #fetch-required-data %} -The Reports Service API +You must provide filters when querying the Reports Service API. Follow these instructions to fetch filters to use when building your report query. ### Retrieve filters {% #retrieve-filters %} From f30b74c74ca14d992c5f9ea295126b8a00b5016f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Thu, 21 Nov 2024 10:32:33 +0100 Subject: [PATCH 07/10] Move UI icons --- src/components/Layout/Icons/UiIcons.astro | 133 ++++++++++++++++++++++ src/components/Layout/Icons/index.astro | 2 + 2 files changed, 135 insertions(+) create mode 100644 src/components/Layout/Icons/UiIcons.astro diff --git a/src/components/Layout/Icons/UiIcons.astro b/src/components/Layout/Icons/UiIcons.astro new file mode 100644 index 000000000..871dd965c --- /dev/null +++ b/src/components/Layout/Icons/UiIcons.astro @@ -0,0 +1,133 @@ + + + + + + + diff --git a/src/components/Layout/Icons/index.astro b/src/components/Layout/Icons/index.astro index 8434a9234..3601fbe99 100644 --- a/src/components/Layout/Icons/index.astro +++ b/src/components/Layout/Icons/index.astro @@ -2,6 +2,7 @@ import BadgeIcons from "./BadgeIcons.astro"; import CalloutIcons from "./CalloutIcons.astro"; import TabIcons from "./TabIcons.astro"; +import UiIcons from "./UiIcons.astro"; --- + From 9ba17c69f756e2e0bf6fdbb5da1627a31cd58e10 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Thu, 21 Nov 2024 10:39:13 +0100 Subject: [PATCH 08/10] Apply suggestions from code review Co-authored-by: Slava Skvortsov <29122694+SlavaSkvortsov@users.noreply.github.com> --- src/content/docs/en/api/reports-service.mdoc | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/content/docs/en/api/reports-service.mdoc b/src/content/docs/en/api/reports-service.mdoc index 59fc7a4a7..2706c642a 100644 --- a/src/content/docs/en/api/reports-service.mdoc +++ b/src/content/docs/en/api/reports-service.mdoc @@ -365,8 +365,11 @@ You MAY pass the following as **query parameters**: : The percentage of gross ad revenue. - `GROSS_100` +- `GROSS_95` - `GROSS_85` +- `GROSS_80` - `GROSS_70` +- `GROSS_65` - `GROSS_60` `ad_revenue_sources`: `String` From 9b37361c1d71476104b3328dd5fedf8e954c3ebe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Thu, 21 Nov 2024 11:09:21 +0100 Subject: [PATCH 09/10] docs: Address PR feedback --- src/content/docs/en/api/reports-service.mdoc | 415 +++---------------- 1 file changed, 62 insertions(+), 353 deletions(-) diff --git a/src/content/docs/en/api/reports-service.mdoc b/src/content/docs/en/api/reports-service.mdoc index 2706c642a..d1bcb9cec 100644 --- a/src/content/docs/en/api/reports-service.mdoc +++ b/src/content/docs/en/api/reports-service.mdoc @@ -21,7 +21,7 @@ If your user is associated with multiple accounts, you can choose which account 1. Pass the account ID as an `X-Account-ID` header in each request. ```sh -curl --location "https://automate.adjust.com/reports-service/filters_data?required_filters=overview_metrics%2Ccost_metrics§ion=cost&overview_metrics__contains=ecpi&cost_metrics__contains=Ad%20spend" \ +curl --location "https://automate.adjust.com/reports-service/events?events__contains=purchase&tokens_mapping=true" \ --header "Authorization: Bearer {YOUR_API_TOKEN}" \ --header "X-Account-ID: {YOUR_ACCOUNT_ID}" ``` @@ -30,16 +30,16 @@ curl --location "https://automate.adjust.com/reports-service/filters_data?requir The Reports Service API returns the following response codes for each endpoint: -| Response | Message | Notes | -| --------------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -| `200` | `Success` | Returns report information | -| `204` | `No content` | Returned if the response object is empty | -| `400` | `Bad request` | Returned if your request is malformed or contains unsupported parameters | -| `401` | `Unauthorized` | Returned if your credentials are incorrect or absent | -| `403` | `Forbidden` | Returned if you try to access information you don't have permission to view | -| `429` | `Too many requests` | Returned if you exceed 50 simultaneous requests | -| `503` | `Service unavailable` | Returned if the server can't be reached | -| `504` | `Gateway timeout` | Returned if the query takes too long to return a response | +| Response | Message | Notes | +| -------- | --------------------- | --------------------------------------------------------------------------- | +| `200` | `Success` | Returns report information | +| `204` | `No content` | Returned if the response object is empty | +| `400` | `Bad request` | Returned if your request is malformed or contains unsupported parameters | +| `401` | `Unauthorized` | Returned if your credentials are incorrect or absent | +| `403` | `Forbidden` | Returned if you try to access information you don't have permission to view | +| `429` | `Too many requests` | Returned if you exceed 50 simultaneous requests | +| `503` | `Service unavailable` | Returned if the server can't be reached | +| `504` | `Gateway timeout` | Returned if the query takes too long to return a response | ## Fetch required data {% #fetch-required-data %} @@ -49,172 +49,6 @@ You must provide filters when querying the Reports Service API. Follow these ins When querying the Reports Service API, you need to filter your reporting data. The Reports Service API supports different filters such as metrics and dimensions. A full list of metrics is available in the [Datascape metrics glossary](https://help.adjust.com/en/article/datascape-metrics-glossary) and a full list of dimensions is available in the [Datascape dimensions glossary](https://help.adjust.com/en/article/datascape-dimensions-glossary). -You can fetch filters programmatically using the `filters_data` endpoint. This endpoint returns a full representation of all matching filters. - -```http -GET https://automate.adjust.com/reports-service/filters_data -``` - -#### Parameters - -You MUST pass the following as a **query parameter**: - -{% deflist %} -`required_filters`: `String` - -: A comma-separated list of filters. -{% /deflist %} - -The following filters are available: - -| Filter | Description | -| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -| `apps` | Returns a list of your apps. | -| `apps_network` | Returns a list of your apps and their associated store IDs. | -| `overview_metrics` | Returns a list of overview metrics. | -| `skad_metrics` | Returns a list of metrics relating to SKAdNetwork. | -| `cohort_maturity` | Returns a list of metrics relating to the maturity of a cohort. Example: mature, immature. | -| `cohort_metrics` | Returns a list of metrics relating to your cohorts. | -| `event_metrics` | Returns a list of metrics relating to your events. All metrics are duplicated per event. | -| `cost_metrics` | Returns a list of metrics relating to cost. | -| `etl_metrics` | Returns a list of metrics relating to ETL (extract, transform, load) between Adjust and another system. | -| `dimensions` | Returns a list of dimensions. | -| `countries` | Returns a list of countries. | -| `currencies` | Returns a list of currencies. | -| `os_names` | Returns a list of operating system names. | -| `networks` | Returns a list of networks. | -| `partners` | Returns a list of partners. | -| `ad_revenue_sources` | Returns a list of ad revenue sources. | -| `iap_revenue_mode` | Returns a list of ad revenue modes. | -| `attribution_type` | Returns a list of attribution types. Examples: all, click, impression. | -| `attribution_source` | Returns a list of attribution sources. | -| `attribution_status` | Returns a list of attribution statuses. | -| `ad_spend_mode` | Returns a list of cost modes. Examples: attribution, network, mixed. | -| `ad_spend_mode` | Returns a list of ad spend modes. Examples: attribution, network, mixed. | -| `utc_offset` | The offset (in hours) from UTC. Defaults to 0 (UTC). | -| `attributes` | Returns a list of attributes. | -| `index` | Returns a list of key metrics that relate to all apps. | -| `period_over_period` | Returns a list of time periods used for data comparison. | -| `cohort_metric_names` | Returns a list of readable names for cohort metrics. | -| `full_cohort_periods` | Returns a list of time periods related to cohorts. | -| `store_type` | Returns a list of app stores. | -| `skad_time_adjustment` | Returns a list of valid SKAdNetwork activity windows. | - -You MAY pass the following as **query parameters**: - -{% deflist %} -`section`: `String` - -: The section you want to filter items by. - -`[required_filters]__contains`: `String` - -: A search term to filter your selected required filters by. -{% /deflist %} - -The following sections are available: - -| Section | Description | -| ----------------------------------------------------- | ----------------------------------------------------- | -| `conversion` | Metrics relating to click and impression conversions. | -| `fraud` | Metrics relating to fraud prevention. | -| `cost` | Metrics relating to cost. | -| `revenue` | Metrics relating to app revenue. | -| `retention` | Metrics relating to cohort-based user retention. | -| `events` | Metrics relating to events. | -| `conversion_events` | Metrics relating to SKAdNetwork conversion events. | -| `installs` | Metrics relating to app installs and reinstalls. | -| `conversion_values` | Metrics relating to SKAdNetwork conversion values. | - -#### Response format - -```json -{ - "required_filters_1": [ - { - "id": "string", - "name": "string", - "short_name": "string", - "section": "string", - "formatting": "string", - "description": "string", - "increase_is_negative": false - } - ] -} -``` - -#### Example - -```sh -curl --location "https://automate.adjust.com/reports-service/filters_data?required_filters=overview_metrics%2Ccost_metrics§ion=cost&overview_metrics__contains=ecpi&cost_metrics__contains=Ad%20spend" \ - --header "Authorization: Bearer {YOUR_API_TOKEN}" \ - --header "X-Account-ID: {YOUR_ACCOUNT_ID}" -``` - -```json -{ - "cost_metrics": [ - { - "id": "network_ad_spend_skan", - "name": "Ad spend (SKAN)", - "short_name": "", - "section": "Cost", - "formatting": "money", - "description": "The amount spent on ads for SKAN campaigns as reported by the network API", - "increase_is_negative": false - }, - { - "id": "network_cost", - "name": "Ad spend (network)", - "short_name": "", - "section": "Cost", - "formatting": "money", - "description": "Ad spend data retrieved via the network API", - "increase_is_negative": true - }, - { - "id": "network_cost_diff", - "name": "Ad spend diff (network)", - "short_name": "", - "section": "Cost", - "formatting": "money", - "description": "Difference between the attribution and network data sources", - "increase_is_negative": true - } - ], - "overview_metrics": [ - { - "id": "skad_ecpi", - "name": "eCPI (SKAN)", - "short_name": "", - "section": "Cost", - "formatting": "decimal", - "description": "Effective cost per install, calculated by dividing the amount spent on ads for SKAN campaigns by installs", - "increase_is_negative": false - }, - { - "id": "ecpi_all", - "name": "eCPI (all installs)", - "short_name": "eCPI (all)", - "section": "Cost", - "formatting": "money", - "description": "Effective cost per install", - "increase_is_negative": true - }, - { - "id": "ecpi", - "name": "eCPI (paid installs)", - "short_name": "eCPI (paid)", - "section": "Cost", - "formatting": "money", - "description": "Effective cost per paid install", - "increase_is_negative": true - } - ] -} -``` - ### Retrieve event slugs {% #retrieve-event-slugs %} If you want to query your reporting data using your Adjust events, you need to retrieve the slugs for your events by calling the `events` endpoint. This endpoint enables you to search for events using their readable names and returns useful information about each one. @@ -314,11 +148,11 @@ For each reporting endpoint, you MUST pass the following **query parameters**: {% deflist %} `dimensions`: `String` -: A comma-separated list of dimensions to group results by. You can fetch dimensions from the [`filters_data` endpoint](#retrieve-filters) or find a full list in the [Datascape dimensions glossary](https://help.adjust.com/en/article/datascape-dimensions-glossary). +: A comma-separated list of dimensions to group results by. You can find a full list in the [Datascape dimensions glossary](https://help.adjust.com/en/article/datascape-dimensions-glossary). `metrics`: `String` -: A comma-separated list of metrics to report on. You can fetch metrics from the [`filters_data` endpoint](#retrieve-filters) or find a full list in the [Datascape metrics glossary](https://help.adjust.com/en/article/datascape-metrics-glossary). +: A comma-separated list of metrics to report on. You can find a full list in the [Datascape metrics glossary](https://help.adjust.com/en/article/datascape-metrics-glossary). `date_period`: `String` @@ -334,7 +168,7 @@ You MAY pass the following as **query parameters**: {% deflist %} `cohort_maturity`: `String` -: Whether to include all cohort metric values (`immature`) or only mature cohorts `mature`. If you pass `mature`, any values for immature cohorts are displayed as zeros. +: Whether to include all cohort metric values (`immature`) or only mature cohorts `mature`. If you pass `mature`, any values for immature cohorts are displayed as zeros. See [How cohorts work on the Adjust Help Center](https://help.adjust.com/en/article/how-cohorts-work#cohort-maturity). `utc_offset`: `String` @@ -342,7 +176,7 @@ You MAY pass the following as **query parameters**: `attribution_type`: `String` -: The type of engagement the attribution awards. +: The type of engagement the attribution awards. See the [attribution type documentation on the Adjust Help Center](https://help.adjust.com/en/article/set-up-your-view-in-datascape#attribution-type). - `click` (default) - `impression` @@ -371,6 +205,7 @@ You MAY pass the following as **query parameters**: - `GROSS_70` - `GROSS_65` - `GROSS_60` +- `GROSS_50` `ad_revenue_sources`: `String` @@ -444,31 +279,71 @@ You MAY pass the following as **query parameters**: : A substring to filter a given dimension by suffix. Case insensitive. -`[metric]__lt`: `String` +`[metric]__lt`: `Number` : "Less than" filter. Returns only values lower than the specified value for the specified metric. -`[metric]__lte`: `String` +`[metric]__lte`: `Number` : "Less than or equal to" filter. Returns only values lower than or equal to the specified value for the specified metric. -`[metric]__gt`: `String` +`[metric]__gt`: `Number` : "Greater than" filter. Returns only values higher than the specified value for the specified metric. -`[metric]__gte`: `String` +`[metric]__gte`: `Number` : "Greater than or equal to" filter. Returns only values greater than or equal to the specified value for the specified metric. -`[metric]__eq`: `String` +`[metric]__eq`: `Number` : "Equal to" filter. Returns only values equal to the specified value for the specified metric. -`[metric]__ne`: `String` +`[metric]__ne`: `Number` : "Not equal to" filter. Returns only values not equal to the specified value for the specified metric. {% /deflist %} +### Fetch a CSV report {% #fetch-csv-report %} + +The `csv_report` endpoint returns data in a comma-separated values format, perfect for importing into spreadsheet software or other tools that require a flat file structure. This format is ideal for users who prefer to work with data in Excel or similar applications for further manipulation and reporting. + +```http +GET https://automate.adjust.com/reports-service/csv_report +``` + +#### Parameters + +In addition to the [parameters for each endpoint](#report-parameters), you MAY pass the following **query parameter** when calling the `csv_report` endpoint: + +{% deflist %} +`readable_names`: `Boolean` + +: Whether to return columns with their human-readable names. Defaults to `false`. +{% /deflist %} + +Human-readable names can change depending on upstream requirements. Use slugs for long running reports to ensure consistency. You can use the [events endpoint](#retrieve-event-slugs) to retrieve event slugs. + +#### Response format + +```text +app,partner_name,campaign,campaign_id_network,campaign_network,installs,network_cost +String,String,String,String,String,Number,Number +``` + +#### Example + +```sh +curl --location "https://automate.adjust.com/reports-service/csv_report?ad_spend_mode=network&app_token__in={app_token1},{app_token2}&date_period=2021-05-01:2021-05-02&dimensions=app,partner_name,campaign,campaign_id_network,campaign_network&metrics=installs,network_cost" \ + --header "Authorization: Bearer {YOUR_API_TOKEN}" \ + --header "X-Account-ID: {YOUR_ACCOUNT_ID}" +``` + +```csv +app,partner_name,campaign,campaign_id_network,campaign_network,installs,network_cost +App Name,AppLovin,Campaign Name (Campaign ID),Campaign ID,Campaign Network,64,1000 +``` + ### Fetch a JSON report {% #fetch-json-report %} The `report` endpoint enables you to combine data from many services in a single report. Request installs, revenue, ad spend, and SKAdNetwork data divided by day, app, and ad network. @@ -540,169 +415,3 @@ curl --location "https://automate.adjust.com/reports-service/report?ad_spend_mod "pagination": null } ``` - -### Fetch a pivot report {% #fetch-pivot-report %} - -The `pivot_report` endpoint delivers data in a structured, pivot-table format. It allows you to group and aggregate data across multiple dimensions, making it easier to summarize and compare key metrics. This is useful when you want to analyze patterns or trends without having to manually manipulate the raw data. - -```http -GET https://automate.adjust.com/reports-service/pivot_report -``` - -#### Parameters - -In addition to the [mandatory parameters for each endpoint](#report-parameters), you MUST pass the following **query parameter** when calling the `pivot_report` endpoint: - -{% deflist %} -`index`: `String` - -: A comma-separated list of dimensions used to index the report. -{% /deflist %} - -#### Response format - -```json -{ - "rows": [], - "totals": {}, - "data_warnings": [], - "debug": { - "service_urls": [ - { - "method": "string", - "url": "string", - "params": {}, - "data": {}, - "status_code": 0, - "duration": 0 - } - ], - "cached_at": "2019-08-24T14:15:22Z" - }, - "currencies": [], - "immature_cohorts": {}, - "totals_per_dimension": {} -} -``` - -#### Example - -```sh -curl --location "https://automate.adjust.com/reports-service/pivot_report?ad_spend_mode=network&app_token__in={app_token1},{app_token2}&date_period=2021-05-01:2021-05-02&dimensions=app,partner_name,campaign,campaign_id_network,campaign_network&metrics=installs,network_installs,network_cost,network_ecpi&index=app" \ - --header "Authorization: Bearer {YOUR_API_TOKEN}" \ - --header "X-Account-ID: {YOUR_ACCOUNT_ID}" -``` - -```json -{ - "rows": [ - { - "Test App": { - "rows": [ - { - "attr_dependency": { - "app_network": ["google_play:com.test.app"] - }, - "campaign_id_network": "123", - "campaign_network": "Campaign Name", - "campaign": "Campaign Name (123)", - "partner_name": "MyPartner", - "installs": 10, - "network_installs": 0, - "network_cost": 0, - "network_ecpi": 0 - } - ] - } - } - ], - "totals": { - "installs": 10, - "network_installs": 0, - "network_cost": 0, - "network_ecpi": 0 - }, - "totals_per_dimension": { - "campaign_id_network": { - "Organic": { - "installs": 10, - "network_installs": 0, - "network_cost": 0, - "network_ecpi": 0 - } - }, - "campaign_network": { - "Organic": { - "installs": 10, - "network_installs": 0, - "network_cost": 0, - "network_ecpi": 0 - } - }, - "app": { - "adjust Demo App": { - "installs": 10, - "network_installs": 0, - "network_cost": 0, - "network_ecpi": 0 - } - }, - "campaign": { - "Organic": { - "installs": 10, - "network_installs": 0, - "network_cost": 0, - "network_ecpi": 0 - } - }, - "partner_name": { - "Organic": { - "installs": 10, - "network_installs": 0, - "network_cost": 0, - "network_ecpi": 0 - } - } - } -} -``` - -### Fetch a CSV report {% #fetch-csv-report %} - -The `csv_report` endpoint returns data in a comma-separated values format, perfect for importing into spreadsheet software or other tools that require a flat file structure. This format is ideal for users who prefer to work with data in Excel or similar applications for further manipulation and reporting. - -```http -GET https://automate.adjust.com/reports-service/csv_report -``` - -#### Parameters - -In addition to the [parameters for each endpoint](#report-parameters), you MAY pass the following **query parameter** when calling the `csv_report` endpoint: - -{% deflist %} -`readable_names`: `Boolean` - -: Whether to return columns with their human-readable names. Defaults to `false`. -{% /deflist %} - -Human-readable names can change depending on upstream requirements. Use slugs for long running reports to ensure consistency. You can use the [events endpoint](#retrieve-event-slugs) to retrieve event slugs. - -#### Response format - -```text -app,partner_name,campaign,campaign_id_network,campaign_network,installs,network_cost -String,String,String,String,String,Number,Number -``` - -#### Example - -```sh -curl --location "https://automate.adjust.com/reports-service/csv_report?ad_spend_mode=network&app_token__in={app_token1},{app_token2}&date_period=2021-05-01:2021-05-02&dimensions=app,partner_name,campaign,campaign_id_network,campaign_network&metrics=installs,network_cost" \ - --header "Authorization: Bearer {YOUR_API_TOKEN}" \ - --header "X-Account-ID: {YOUR_ACCOUNT_ID}" -``` - -```csv -app,partner_name,campaign,campaign_id_network,campaign_network,installs,network_cost -App Name,AppLovin,Campaign Name (Campaign ID),Campaign ID,Campaign Network,64,1000 -``` From b3897598c2c0838caf92e66f93b9b394e212ba3d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= Date: Thu, 21 Nov 2024 11:18:08 +0100 Subject: [PATCH 10/10] fix: update lycheeignore list --- .lycheeignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.lycheeignore b/.lycheeignore index a1143598f..f7db6e1d1 100644 --- a/.lycheeignore +++ b/.lycheeignore @@ -1,4 +1,5 @@ ^https?:\/\/(www.)?api\.adjust\.com(?:\/.*)?$ +^https?:\/\/(www.)?automate\.adjust\.com(?:\/.*)?$ ^https?:\/\/(www.)?example\.go\.link(?:\/.*)?$ ^https?:\/\/(www.)?dash\.adjust\.com\/control-center(?:\/.*)?$ ^https?:\/\/(www.)?segment\.com(?:\/.*)?$