> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Apple App Store as a data source
> Bring data from the Apple App Store to Nekt.
The Apple App Store is Apple's distribution platform for iOS, iPadOS, macOS, tvOS, watchOS, and visionOS apps. Through the App Store Connect API, it exposes how people discover, download, use, and pay for your apps, along with the sales and financial reports behind your payouts.
## Configuring Apple App Store as a Source
In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the Apple App Store option from the list of connectors.
Click **Next** and you'll be prompted to add your access.
### 1. Add account access
Apple authenticates every request with a key you generate in App Store Connect. Create it before starting the setup:
In [App Store Connect](https://appstoreconnect.apple.com), go to **Users and Access**, select the **Integrations** tab, and choose **App Store Connect API** in the left column. Make sure the **Team Keys** tab is selected — individual keys cannot read sales and financial reports.
Click **Generate API Key**, give it a name, and select the **Admin** role under Access. Apple only lets a key with the Admin role turn on analytics reports, which is what makes the report tables fill in automatically.
Click **Download API Key** to save the `.p8` file. Apple allows this download only once — if the file is lost, you have to generate a new key.
The following configurations are available:
* **Key ID**: The identifier shown in the Active column next to your key on the Integrations page.
* **Issuer ID**: Shown near the top of the same Integrations page. It is the same for every team key of your account.
* **Private key (.p8)**: The full contents of the `.p8` file you downloaded, including the BEGIN and END lines. Open the file in a text editor and paste everything.
* **Vendor Number**: Found in App Store Connect under **Payments and Financial Reports**. It is only needed for the Sales Reports and Finance Reports streams; every App Store analytics stream works without it.
* **Start Date**: The earliest date from which records will be synced.
* **Load historical analytics data**: (Default: enabled) Asks Apple once for a snapshot of all available analytics history. Leave it on for a new source — without it, analytics reports only cover the period after the source was created.
Once you're done, click **Next**.
Apple takes 24 to 48 hours to produce the first set of analytics reports after a source is created. Your first run will succeed with empty report tables, and the data appears on a later run. Sales Reports and Finance Reports are not affected and load immediately.
### 2. Select streams
Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. You can select entire groups of streams or pick specific ones.
Most analytics reports come in two versions, **Standard** and **Detailed**. They describe the same events: Detailed adds attribution columns (source info, campaign, page title) and, in exchange, applies stricter privacy thresholds that can omit low-volume rows. Pick one per report — selecting both puts two overlapping aggregations of the same events in your catalog, and any straightforward SUM across them counts the same activity twice.
> Tip: The stream can be found more easily by typing its name.
Select the streams and click **Next**.
### 3. Configure data streams
Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.
* **Layer**: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
* **Folder**: a folder can be created inside the selected layer to group all tables being created from this new data source.
* **Table name**: we suggest a name, but feel free to customize it. You have the option to add a **prefix** to all tables at once and make this process faster!
* **Sync Type**: you can choose between INCREMENTAL and FULL\_TABLE.
* Incremental: every time the extraction happens, we'll get only the new data - which is good if, for example, you want to keep every record ever fetched.
* Full table: every time the extraction happens, we'll get the current state of the data - which is good if, for example, you don't want to have deleted data in your catalog.
Once you are done configuring, click **Next**.
### 4. Configure data source
Describe your data source for easy identification within your organization, not exceeding 140 characters.
To define your [Trigger](https://docs.nekt.com/runs/scheduling-and-triggers), consider how often you want data to be extracted from this source. Apple publishes analytics data once a day, so a daily trigger matches how often new data actually exists.
Optionally, you can define some additional settings:
* Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource [here](https://docs.nekt.com/get-started/core-concepts/resource-control).
* Determine when to execute an **Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync)**. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.
Once you are ready, click **Next** to finalize the setup.
### 5. Check your new source
You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.
For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.
## How Apple limits the data
These are Apple's own rules, not Nekt's, and they shape what you can expect to see:
* **Analytics history starts on January 1, 2024.** Subscription State and Subscription Event reports start on January 1, 2025.
* **Report data expires after 35 days.** Apple deletes a report instance 35 days after producing it. Keeping your source on a daily trigger means the data is always collected well inside that window.
* **Daily sales reports are kept for one year.** The source does not look further back than that.
* **A day is complete two to five days later**, depending on the report. Apple restates a day when late events arrive, and the source re-reads the most recent day on every run so those corrections update the existing rows instead of duplicating them.
* **Privacy thresholds apply.** Usage reports only count users who opted in to share data with Apple and developers, rows representing fewer than five users or devices are omitted, and a small amount of statistical noise is added. Low-volume apps and brand-new features may show no data at all.
* **Rate limit**: Apple allows roughly 3,500 requests per hour per API key. The connector tracks the remaining budget and slows down on its own when it runs low.
# Streams and Fields
## Available streams
The table below lists every stream, its **slug** (the exact identifier to pass when creating the source via API) and a short description.
| Stream | Slug | Description |
| ------------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Apps | `apps` | Every app in your App Store Connect account, with bundle ID, SKU and primary locale. |
| Customer Reviews | `customer_reviews` | Ratings and written reviews left on the App Store, per app and territory. |
| Analytics Report Requests | `analytics_report_requests` | The report requests active for each app. Shows whether Apple stopped generating reports. |
| Analytics Reports | `analytics_reports` | The reports Apple generates for each request, with name and category. |
| Analytics Report Instances | `analytics_report_instances` | The daily instances of each report, showing how far back data currently reaches. |
| App Store Downloads | `app_store_downloads_standard` / `app_store_downloads_detailed` | Downloads from the App Store, split by download type, source, device and territory. |
| App Store Purchases | `app_store_purchases_standard` / `app_store_purchases_detailed` | Paid app and in-app purchase revenue, attributed to download sources and product pages. |
| App Store Discovery and Engagement | `app_store_discovery_and_engagement_standard` / `app_store_discovery_and_engagement_detailed` | Impressions, page views and taps across product pages, store sheets and in-app event pages. |
| App Store Installations and Deletions | `app_store_installs_and_deletions_standard` / `app_store_installs_and_deletions_detailed` | How often people install and delete the app. |
| App Sessions | `app_sessions_standard` / `app_sessions_detailed` | How often people open the app and how long they spend in it. |
| App Crashes | `app_crashes` | Crash counts by app version and device type. |
| Subscription State | `app_store_subscription_state_standard` / `app_store_subscription_state_detailed` | Daily snapshot of active and churned subscriptions, free trials and billing issues. |
| Subscription Events | `app_store_subscription_events_standard` / `app_store_subscription_events_detailed` | Subscription lifecycle changes: conversions to paid, renewals, and churn. |
| App Store Pre-Orders | `app_store_pre_orders_standard` / `app_store_pre_orders_detailed` | Pre-orders placed and canceled for the app. |
| Sales Reports | `sales_reports` | Daily Summary Sales report: units and estimated proceeds per SKU, country and device. Requires the Vendor Number. |
| Finance Reports | `finance_reports` | Consolidated financial report per fiscal month, in the currency you are actually paid in. Requires the Vendor Number. |
Analytics reports measure estimated proceeds in USD. Finance Reports are the only stream carrying settled amounts in your payout currency, which is why the two do not match exactly.
## Fields by stream
Below you'll find the main data streams from the Apple App Store and their corresponding fields:
Every app registered in your App Store Connect account.
**Key Fields:**
* `id` - App Store Connect resource ID of the app, used to link every other stream
* `name` - Name of the app as it appears on the App Store
* `bundle_id` - Bundle ID of the app, matching the one used in Xcode
* `sku` - Unique ID for the app that is not visible on the App Store
* `primary_locale` - Primary locale, used when localized information is unavailable in a territory
* `content_rights_declaration` - Whether the app contains third-party content
* `is_or_ever_was_made_for_kids` - Whether the app is, or has ever been, in the Made for Kids category
Ratings and written reviews customers left on the App Store.
**Key Fields:**
* `id` - Unique identifier of the review
* `app_id` - Resource ID of the reviewed app
* `app_name` - Name of the reviewed app
* `rating` - Star rating the customer gave, 1 to 5
* `title` - Title the customer wrote for the review
* `body` - Review text the customer wrote
* `reviewer_nickname` - Nickname the customer used
* `territory` - App Store territory the review was written in
* `created_date` - When the review was created, used as the incremental replication key
How often your app is downloaded from the App Store.
**Key Fields:**
* `date` - Date the downloads occurred
* `app_name`, `app_apple_identifier` - The app the row refers to
* `download_type` - First-time download, redownload, manual update, auto-update or restore
* `app_version` - App version being downloaded
* `device`, `platform_version` - Device and OS version
* `source_type` - Where the user discovered the app (App Store search, browse, app referrer, web referrer)
* `page_type` - Product page, in-app event page, store sheet or no page
* `territory` - App Store country or region
* `counts` - Total number of downloads
* `source_info`, `campaign`, `page_title` - Attribution detail, Detailed stream only
Paid app and in-app purchase revenue on the App Store.
**Key Fields:**
* `date` - Date the purchase occurred
* `purchase_type` - Type of purchase made
* `content_name`, `content_apple_identifier` - What was purchased
* `payment_method` - Payment type used to charge the customer
* `purchases` - Count of purchases; negative values are refunds
* `proceeds_in_usd` - Estimated proceeds: customer price minus taxes and Apple's commission
* `sales_in_usd` - Estimated sales
* `paying_users` - Unique paying users; not summable across rows
* `app_download_date` - When the app was downloaded, if within the previous 30 days
* `territory`, `device`, `platform_version` - Where and on what the purchase happened
How users interact with your app on the App Store itself.
**Key Fields:**
* `date` - Date the event occurred
* `event` - Type of event that occurred
* `engagement_type` - User action, if any, on the impression or page
* `page_type` - Page type associated with the event
* `source_type` - Where the user discovered the app
* `counts` - Total number of events
* `unique_counts` - Total number of unique users who performed the event
Installs and deletions, among users who opted in to share usage data.
**Key Fields:**
* `date` - Date the event occurred
* `event` - Type of usage event (installation or deletion)
* `download_type` - Type of download that preceded the event
* `app_version`, `device`, `platform_version` - What the event happened on
* `counts` - Total count of events
* `unique_devices` - Number of unique devices that generated the events
How often people open your app and how long they spend in it.
**Key Fields:**
* `date` - Date the sessions occurred
* `app_version`, `device`, `platform_version` - What the sessions ran on
* `sessions` - Number of sessions
* `total_session_duration` - Total duration of all sessions, in seconds
* `unique_devices` - Unique devices contributing to the sessions
* `territory` - App Store country or region
Crash counts by app version and device type.
**Key Fields:**
* `date` - Date the crashes occurred
* `app_version` - App version associated with the crash
* `device`, `platform_version` - Device and OS version
* `crashes` - Total number of crashes
* `unique_devices` - Number of unique devices on which the app crashed
Daily snapshot of your subscriptions.
**Key Fields:**
* `date` - Date the snapshot was generated for
* `state_metric`, `state_metric_grouping` - The subscription state being counted
* `subscription_name`, `subscription_identifier` - The subscription
* `subscription_duration`, `billing_frequency`, `billing_period` - Terms of the subscription
* `subscription_group`, `subscription_group_identifier` - Group the subscription belongs to
* `offer_type`, `offer_name`, `offer_pricing`, `offer_duration` - Redeemed offer
* `family_sharing` - Whether the subscription is shared with an iCloud family
* `cancellation_reason` - Why the subscription was canceled
* `counts` - Number of subscriptions
Changes across the subscription lifecycle.
**Key Fields:**
* `event_date` - Date the event occurred
* `event_sub_type`, `event_grouping` - The lifecycle event being counted
* `subscription_name`, `subscription_identifier` - The subscription
* `plan_change_type` - Upgrade, crossgrade or downgrade when users switch plans
* `previous_subscription_name`, `previous_subscription_identifier` - The plan switched away from
* `paid_service_days_recovered` - Paid days recovered through the billing grace period
* `cancellation_reason` - Why the subscription was canceled
* `counts` - Number of events
Pre-orders placed and canceled for your app.
**Key Fields:**
* `date` - Date the pre-order activity occurred
* `pre_order_start_date` - Date the app became available for pre-order
* `pre_order_end_date` - Last date the app is available for pre-order
* `pre_orders_placed` - Total number of pre-orders placed
* `pre_orders_canceled` - Total number of pre-orders canceled
* `territory`, `device`, `source_type` - Where the pre-order came from
The daily Summary Sales report from Sales and Trends. Requires the Vendor Number.
**Key Fields:**
* `report_date` - Day the report covers, used as the incremental replication key
* `sku`, `title`, `version` - The product sold
* `product_type_identifier` - Type of transaction, such as an initial download or an update
* `units` - Aggregated units; negative values are refunds
* `developer_proceeds_per_unit` - Amount received per unit
* `customer_price` - Price per unit billed to the customer
* `customer_currency`, `currency_of_proceeds` - Currencies involved
* `country_code` - App Store country or region of the sale
* `device`, `supported_platforms` - Where the purchase happened
* `subscription`, `period`, `preserved_pricing`, `proceeds_reason` - Subscription detail
The consolidated financial report per fiscal month, covering every region. Requires the Vendor Number.
**Key Fields:**
* `report_date` - Fiscal month the report covers, as YYYY-MM
* `start_date`, `end_date` - Period boundaries on Apple's fiscal calendar
* `vendor_identifier` - SKU of the app, or product ID of the in-app purchase
* `quantity` - Aggregated units sold
* `partner_share` - Proceeds received per unit
* `extended_partner_share` - Quantity multiplied by the partner share: the amount earned
* `partner_share_currency` - Currency of the amounts earned
* `sale_or_return` - S for a sale, R for a return
* `country_of_sale` - Country of the sale
* `customer_price`, `customer_currency` - What the customer paid
Every stream also carries an `additional_fields` column. It is normally empty and holds any column Apple adds to a report before the connector models it, so new data is never silently dropped.