App Store Connect

App Store Connect is a web-based platform provided by Apple for app developers and publishers. It allows them to manage their apps on the Apple App Store, including tasks like submitting new apps, updating existing apps, managing app metadata, tracking app performance, and reviewing user feedback and ratings.

Refer to our website for the list of metrics and attributes available in Dataddo.

Authorize Connection to App Store Connect

In App Store Connect

To authorize your App Store Connect account, you will need:

• Private Key
• Key ID and Issuer ID

Obtain Private Key

1. In your Apple Developer account, navigate to the Users and Access section.
2. Go to the API Keys section and generate a new team API key (= API token). Do not use an individual API key: individual keys inherit the permissions of the user who created them and cannot be assigned a role of their own.
3. Fill in the key name and select the access level (role). See API Key Access Level below.
4. After generating the key, download it in the .p8 file format.

For more information, refer to Apple's official documentation.

API Key Access Level

The connector uses Apple's Analytics Reports API, which is only available to API keys with the Admin, Sales (with the Access to Reports permission), or Finance role. Apple additionally requires the Admin role to request an analytics report type for the first time; once the report request exists, keys with the Sales and Reports or Finance role can download the generated reports (see Apple's Analytics Reports API documentation).

This matters because Dataddo sends that first-time request automatically: when you create a source for an app and report request type (Ongoing or One-time snapshot) that has never been requested before, Dataddo calls Apple's POST /v1/analyticsReportRequests endpoint on your behalf. This initial request cannot be triggered from the App Store Connect web interface, only via the API.

Choose one of the following setups:

• Simple: use a key with the Admin role.
• Least privilege: authorize Dataddo with an Admin key, create your sources (this establishes the report requests), then replace the key in the authorizer with a Sales (with Access to Reports) or Finance key and revoke the Admin key in App Store Connect. Downloads only need the lower role. Note that connecting a new app or a new report request type later requires the Admin key again.

Obtain Key ID and Issuer ID

1. In your App Store Connect, navigate to the Users and Access page and then select the API Keys tab.
2. Under the Active section, hover your cursor next to your Key ID to copy it.
3. Copy the Issuer ID which appears near the top of the page.

In Dataddo

First upload the Private Key to Dataddo.

1. Navigate to the Security page.
2. Go to the Certificates & Tokens tab and click on Add Certificate.
3. Choose RSA Private Key certificate type and upload the private key you generated in App Store Connect.

Then create an App Store Connect authorizer.

1. On the Authorizers page, click on Authorize New Service and select App Store Connect.
2. Fill in the following fields:
   1. Key ID: App Store Connect's key ID.
   2. Issuer ID: App Store Connect's issuer ID.
3. For the private key, select the newly uploaded certificate.
4. Rename your authorizer for easier identification and click on Save.

Data Coverage

The connector is built on Apple's Analytics Reports API. When you create a source, you pick:

• your app,
• the type of report request: Ongoing (Apple keeps generating new reports on a recurring basis) or One-time snapshot (all available historical data in a single report),
• the granularity: Daily or Monthly,
• the report from the table below, and the fields to extract.

Standard vs. Detailed: both variants contain the same metrics. The Detailed variant adds finer acquisition breakdowns: Source Info, Campaign, and Page Title.

How Data Extraction Works

There is no date range to set in Dataddo. The data window is preconfigured by the report you choose: the report request type and the granularity define what each run delivers.

Ongoing reports

• Apple generates a new report on a recurring basis. The first report is ready roughly 24 to 48 hours after you create the source; Dataddo retries automatically until it appears.
• Each run loads the newest report Apple has generated: one day of data per run with Daily granularity, one month with Monthly.
• Apple considers a day's data complete two days after the reporting date, so the newest daily report is usually about two days behind.
• To build a continuous history, schedule the source daily (or monthly) and append the data, or upsert on dataddo_hash. Keep the schedule running: days in between are skipped if the source does not run, because each run only loads the newest report.

One-time snapshot reports

A snapshot contains all available historical data for the report in one delivery. Use it to load history once, for example when you first set up the pipeline. It is not refreshed afterwards.

Recommended setup for a complete, always-fresh table: create two sources for the same report, a One-time snapshot source to backfill the history and an Ongoing daily source for new data. They share the same schema, so you can send both to the same table and upsert on dataddo_hash.

Metadata Columns

When you create a source, you can add these Dataddo metadata columns to the extracted data:

• dataddo_hash - a fingerprint built from each record's key fields. It works as a natural key, so it is ideal for upserts (updating existing rows in your destination instead of creating duplicates).
• dataddo_extraction_timestamp - the date and time the row was extracted. Use it to track how records change over time, for example to build slowly changing dimensions.

How to Create an App Store Connect Data Source

Creating a data source takes you through five steps, shown in the progress bar at the top of the wizard. Each step is explained below.

1. Pick the connector

On the Sources page, click Create Source, then select the connector from the catalog. Use the search bar or the category tabs if you do not see it right away. You can rename the source at any time using the pencil icon next to its name.

2. Choose the account

This step selects what Dataddo reads from.

• Authorizer: Select an account you have already authorized from the drop-down. If you have none yet, choose Add new account and follow the prompts. If no authorizer is selected, Dataddo asks you to authorize before you continue.
• What to extract from: Select the exact entity you want to pull data from. Depending on the service this may be labelled an account, property, profile, workspace, or similar, sometimes with a sub-level to choose as well.
• Multiple accounts: To pull the same data from every entity you can access, turn on Automatically collect data from all .... This is multi-account extraction. Leave it off to choose them by hand.

3. Build the data model

Choose exactly what to extract. What you can pick depends on the connector, and the wizard may group the fields differently for each one.

• Values: the measures you want, often called metrics, such as sessions, clicks, or revenue.
• Breakdowns: the fields you group or split those values by, often called dimensions or attributes, such as date, country, or campaign.
• Context metadata (when available): identifier fields that Dataddo derives from your selection, such as the account or property ID. They let you tell rows apart when you combine several sources.

Some connectors limit which fields can be queried together; the wizard flags this where it applies. Click Test on Sample Data at any point to preview the result before you continue.

4. Add metadata columns (optional)

Two optional columns help your destination handle the data.

• Dataddo Hash (Include Row Hash): a fingerprint built from the columns you pick. It works as a natural key, so your destination can deduplicate rows and run upserts instead of creating duplicates. Turn it on, then select the columns that uniquely identify a row.
• Dataddo Extraction Timestamp: the time each row was extracted. Use it to watermark the data, for example to build slowly changing dimensions or to track when a value last changed.

5. Set the schedule

Decide how often Dataddo runs the extraction.

• Frequency: how often the pipeline runs, for example daily. Click Show advanced settings to also set the exact hour and minute (UTC).
• Date range: the relative window each run extracts, for example "Yesterday". The window moves forward on every run.
• Historical data: a new source starts from the current window. To load older data, run a full data re-sync after the source is created.
• Allow Empty Data Extractions: when on, a run that returns no data records zero rows instead of failing. Turn it on if the source can legitimately have periods with no data.

Click Save. Your data source is ready.

Troubleshooting

Data Preview Unavailable

No data preview when you click on Test Data might be caused by an issue with your source configuration. The most common causes are:

• Date range: Try a smaller date range. You can load the rest of your data afterward via manual data load.
• Insufficient permissions: Please make sure your authorized account has at least admin-level permissions.

The Report Is Not Available Yet

A new source has no data until Apple generates the first report, which takes roughly 24 to 48 hours. Dataddo retries automatically during that time, so no action is needed. If the source still has no data after two days, check that the selected app and report are correct.

The API Key in Use Does Not Allow This Request

Apple returns this error with HTTP status 403 when the API key authenticated successfully but its role does not permit the requested operation.

"errors" : [ {
  "status" : "403",
  "code" : "FORBIDDEN_ERROR",
  "title" : "This request is forbidden for security reasons",
  "detail" : "The API key in use does not allow this request"
} ]

For this connector, the usual causes are:

1. The key's role cannot access the Analytics Reports API at all. Roles like Developer, App Manager, or Marketing are not sufficient. The key must have the Admin, Sales (with Access to Reports), or Finance role.
2. A first-time report request needs the Admin role. If the source you are creating is the first one for a given app and report request type, Dataddo must register the report request with Apple, and Apple only allows this with an Admin key. See API Key Access Level.
3. The key is an individual API key. Individual keys inherit the creating user's permissions and may lack report access. Use a team API key instead.

A key's role cannot be changed after creation. Generate a new team API key with a sufficient role in Users and Access > Integrations, upload the new .p8 private key on the Security page, and update the authorizer with the new Key ID and certificate.

Missing or Expired Agreement Error

Apple blocks the App Store Connect API while a required agreement is unsigned or expired. In that case the extraction fails with the following error.

"response_body": "{\n \"errors\" : [ {\n   \"status\" : \"403\",\n   \"code\" : \"FORBIDDEN.REQUIRED_AGREEMENTS_MISSING_OR_EXPIRED\",\n   \"title\" : \"A required agreement is missing or has expired.\",\n   \"detail\" : \"This request requires an in-effect agreement that has not been signed or has expired.\"\n } ]\n}"

To fix it:

1. Log in to App Store Connect as a user who is allowed to accept agreements. Only the Account Holder can accept most agreements; an Admin can accept the Paid Applications Agreement. If that is not you, ask your Account Holder.
2. Go to Agreements, Tax, and Banking and accept every agreement marked as pending or expired. Check that the agreement shows as Active afterwards.
3. If nothing is listed there, open the App Store Connect homepage and the Apple Developer website and look for a banner asking you to accept the latest Program License Agreement.
4. Once the agreements are active, the next scheduled run extracts data normally. You do not need to change anything in Dataddo.

Related Articles

Now that you have successfully created a data source, see how you can connect your data to a dashboarding app or a data storage.

Sending Data to Dashboarding Apps

• Simple Data Integration to Dashboards
• Data Backfilling to Dashboarding Apps

Sending Data to Data Storages

• Batch Ingestion to Data Warehouses
• Data Backfilling to Storages

Other Resources

• Troubleshooting
• Extraction Logs
• Data Duplication