:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(data-warehouse): add app store connect performance overviews table (#119193)
Tom Owersb4e3d0682ce7
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md b/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.mdindex dd430ffa0302..43cef17c43c0 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md@@ -706,7 +706,7 @@ Note: Full v2 endpoint list read from the docs nav (slugs encode the HTTP path).## Apple (App Store Connect) — gaps-Today (22): `analytics_app_clip_usage`, `analytics_app_crashes`, `analytics_app_sessions`, `analytics_app_sessions_detailed`, `analytics_app_store_downloads`, `analytics_app_store_downloads_detailed`, `analytics_app_store_preorders`, `analytics_discovery_engagement`, `analytics_discovery_engagement_detailed`, `analytics_installations_deletions`, `analytics_installations_deletions_detailed`, `app_store_versions`, `apps`, `beta_groups`, `builds`, `customer_reviews`, `in_app_purchases`, `review_responses`, `sales_reports`, `subscription_event_reports`, `subscription_groups`, `subscription_reports`+Today (23): `analytics_app_clip_usage`, `analytics_app_crashes`, `analytics_app_sessions`, `analytics_app_sessions_detailed`, `analytics_app_store_downloads`, `analytics_app_store_downloads_detailed`, `analytics_app_store_preorders`, `analytics_discovery_engagement`, `analytics_discovery_engagement_detailed`, `analytics_installations_deletions`, `analytics_installations_deletions_detailed`, `app_store_versions`, `apps`, `beta_groups`, `builds`, `customer_reviews`, `in_app_purchases`, `performance_overviews`, `review_responses`, `sales_reports`, `subscription_event_reports`, `subscription_groups`, `subscription_reports`Diffed against: <https://developer.apple.com/sample-code/app-store-connect/app-store-connect-openapi-specification.zip>@@ -719,6 +719,7 @@ Diffed against: <https://developer.apple.com/sample-code/app-store-connect/app-s- [ ] `Beta feedback (GET /v1/apps/{id}/betaFeedbackCrashSubmissions; GET /v1/apps/{id}/betaFeedbackScreenshotSubmissions)` — connects tester feedback and crash submissions to app quality reports (medium)- [ ] `Xcode Cloud build runs (GET /v1/ciProducts/{id}/buildRuns)` — measures build success, failures, and delivery time alongside synced app builds (medium)- [ ] `Subscription prices (GET /v1/subscriptions/{id}/prices)` — tracks subscription pricing by territory and effective period (medium)+- [x] `Performance overviews (GET /v1/apps/{id}/performanceOverviews)` — Xcode's aggregated performance metrics per app version, added in API 4.5 (medium)Note: Downloaded Apple's official OpenAPI ZIP and parsed GET paths, including relationship collections and metrics. Existing sales and analytics reports were counted as covered; report discovery alone does not sync every report category. Nested collections need requests for each group, subscription, app, or CI product; finance reports need fiscal periods and vendor numbers. Signing credentials, provisioning, upload assets, and API administration were excluded.diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/app_store_connect/app_store_connect.py b/products/warehouse_sources/backend/temporal/data_imports/sources/app_store_connect/app_store_connect.pyindex c8f339e57272..8b2a4367fbc0 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/app_store_connect/app_store_connect.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/app_store_connect/app_store_connect.py@@ -4,6 +4,7 @@ import csvimport gzipimport mathimport time+import bisectimport hashlibimport tempfileimport dataclasses@@ -51,6 +52,9 @@ CREDENTIALS_TIMEOUT_SECONDS = 15# `/v1/salesReports` returns a gzipped TSV, not JSON, and only for this Accept type.REPORT_ACCEPT = "application/a-gzip"+# `/v1/apps/{id}/performanceOverviews` serves Xcode's overview document, not JSON:API, under this Accept type.+PERFORMANCE_OVERVIEW_ACCEPT = "application/vnd.apple.xcode-overview+json"+# Hard cap on pages walked for one collection (or one app's collection) so a pagination bug can't scan# forever. At 200 rows a page that is 400k rows.MAX_PAGES_PER_RESOURCE = 2000@@ -793,6 +797,95 @@ def _get_app_fanout(manager.save_state(AppStoreConnectResumeConfig(app_id=app_ids[position + 1]))+def _as_dict(value: Any) -> dict[str, Any]:+ return value if isinstance(value, dict) else {}+++def _as_dicts(value: Any) -> list[dict[str, Any]]:+ return [item for item in value if isinstance(item, dict)] if isinstance(value, list) else []+++def _performance_overview_rows(app_id: str, body: Any) -> list[dict[str, Any]]:+ """Flatten an Xcode performance overview into one row per metric point.++ The document nests category, then metric section, then dataset (a percentile and device+ population), then one point per app version. The insights and signatures blocks summarize+ these same points, so they are not kept.+ """+ overview = _as_dict(body)+ metadata = _as_dict(overview.get("appMetadata"))+ rows: list[dict[str, Any]] = []+ for category in _as_dicts(overview.get("categories")):+ for section in _as_dicts(category.get("sections")):+ unit = _as_dict(section.get("unit"))+ for dataset in _as_dicts(section.get("datasets")):+ criteria = _as_dict(dataset.get("filterCriteria"))+ goal = _as_dict(dataset.get("recommendedMetricGoal"))+ for point in _as_dicts(dataset.get("points")):+ breakdown = _as_dict(point.get("percentageBreakdown"))+ rows.append(+ {+ "app_id": app_id,+ "bundle_id": metadata.get("bundleId"),+ "platform": metadata.get("platform"),+ "latest_version": metadata.get("latestVersion"),+ "category": category.get("identifier"),+ "category_name": category.get("displayName"),+ "metric": section.get("identifier"),+ "metric_name": section.get("displayName"),+ "unit": unit.get("identifier"),+ "unit_name": unit.get("displayName"),+ "percentile": criteria.get("percentile"),+ "device": criteria.get("device"),+ "device_marketing_name": criteria.get("deviceMarketingName"),+ "version": point.get("version"),+ "value": point.get("value"),+ "error_margin": point.get("errorMargin"),+ "breakdown_value": breakdown.get("value"),+ "breakdown_subsystem": breakdown.get("subSystemLabel"),+ "recommended_goal_value": goal.get("value"),+ "recommended_goal_detail": goal.get("detail"),+ }+ )+ return rows+++def _get_app_overview(+ session: requests.Session,+ config: AppStoreConnectEndpointConfig,+ token_provider: AppStoreConnectTokenProvider,+ logger: FilteringBoundLogger,+ manager: ResumableSourceManager[AppStoreConnectResumeConfig],+ selected_app_ids: frozenset[str],+) -> Iterator[list[dict[str, Any]]]:+ # Sorted, so a bookmarked app that disappears between attempts still marks a position: a resumed+ # full refresh appends, and restarting from the first app would duplicate committed rows.+ app_ids = sorted(_list_app_ids(session, token_provider, logger, selected_app_ids))+ resume = _load_resume(manager)+ start = bisect.bisect_left(app_ids, resume.app_id) if resume is not None and resume.app_id else 0++ for position in range(start, len(app_ids)):+ app_id = app_ids[position]+ # The app was just listed, so a 404 means Apple has no overview for it yet (an unreleased+ # app, or too few users to report metrics). That must not fail the other apps.+ response = _get(+ session,+ f"{BASE_URL}{config.path.format(app_id=app_id)}",+ token_provider=token_provider,+ logger=logger,+ accept=PERFORMANCE_OVERVIEW_ACCEPT,+ tolerate=(404,),+ )+ rows = [] if response.status_code == 404 else _performance_overview_rows(app_id, response.json())++ if position + 1 < len(app_ids):+ manager.save_state(AppStoreConnectResumeConfig(app_id=app_ids[position + 1]))+ if rows:+ yield rows+ else:+ manager.safe_point()++def _to_date(value: Any) -> date | None:if value is None:return None@@ -1879,6 +1972,10 @@ def get_rows(yield from _get_app_fanout(session, config, token_provider, logger, resumable_source_manager, failures, selected_app_ids)+ elif config.kind == "app_overview":+ yield from _get_app_overview(+ session, config, token_provider, logger, resumable_source_manager, selected_app_ids+ )elif config.kind == "analytics_report":yield from _get_analytics_report(session,diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/app_store_connect/canonical_descriptions.py b/products/warehouse_sources/backend/temporal/data_imports/sources/app_store_connect/canonical_descriptions.pyindex 61486b3dff93..9ea300ff7000 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/app_store_connect/canonical_descriptions.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/app_store_connect/canonical_descriptions.py@@ -154,6 +154,32 @@ CANONICAL_DESCRIPTIONS: CanonicalDescriptions = {"referenceName": "Name of the group, visible only in App Store Connect.",},},+ "performance_overviews": {+ "description": "Xcode's aggregated performance metrics for an app, such as launch time, hangs, memory, battery and disk writes, with one row per metric, population and app version.",+ "docs_url": "https://developer.apple.com/documentation/appstoreconnectapi/get-v1-apps-_id_-performanceoverviews",+ "columns": {+ "app_id": "Identifier of the app the metrics belong to.",+ "bundle_id": "Bundle ID of the app.",+ "platform": "Platform the metrics were collected on.",+ "latest_version": "Latest version of the app that the overview covers.",+ "category": "Identifier of the metric category, such as launch, hang, memory, battery or disk.",+ "category_name": "Display name of the metric category.",+ "metric": "Identifier of the metric within its category.",+ "metric_name": "Display name of the metric.",+ "unit": "Identifier of the unit the metric value is measured in.",+ "unit_name": "Display name of the unit the metric value is measured in.",+ "percentile": "Population percentile the value describes, such as typical or high-end usage.",+ "device": "Device class the value was measured on.",+ "device_marketing_name": "Marketing name of the device the value was measured on.",+ "version": "App version the value was measured for.",+ "value": "Measured value of the metric for this version and population, in `unit`.",+ "error_margin": "Margin of error of the measured value.",+ "breakdown_value": "Share of the value attributed to the subsystem in `breakdown_subsystem`.",+ "breakdown_subsystem": "Subsystem that `breakdown_value` is attributed to.",+ "recommended_goal_value": "Value Apple recommends the metric stays within for this population.",+ "recommended_goal_detail": "Explanation of the recommended goal.",+ },+ },"sales_reports": {"description": "One row of Apple's daily Sales and Trends summary report: units and developer proceeds per SKU, territory and product type.","docs_url": "https://developer.apple.com/documentation/appstoreconnectapi/download_sales_and_trends_reports",diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/app_store_connect/settings.py b/products/warehouse_sources/backend/temporal/data_imports/sources/app_store_connect/settings.pyindex e18a77b600a4..cc2abf9dddb6 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/app_store_connect/settings.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/app_store_connect/settings.py@@ -6,7 +6,7 @@ from posthog.dataclasses import frozenfrom products.warehouse_sources.backend.temporal.data_imports.sources.common.schema import incremental_fieldfrom products.warehouse_sources.backend.types import IncrementalField, IncrementalFieldType-# App Store Connect splits into very different transports, so the catalog carries four kinds:+# App Store Connect splits into very different transports, so the catalog carries five kinds:## - "collection": a top-level JSON:API list (`/v1/apps`, `/v1/builds`, ...) walked via `links.next`.# - "app_fanout": a per-app JSON:API list (`/v1/apps/{app_id}/customerReviews`, ...). Apps are@@ -21,7 +21,9 @@ from products.warehouse_sources.backend.types import IncrementalField, Increment# is also ensured and, once Apple generates it, backfills history older than# the ongoing stream. Report request creation is the only account mutation this# source makes.-EndpointKind = Literal["collection", "app_fanout", "sales_report", "analytics_report"]+# - "app_overview": a per-app document that is not JSON:API (`/v1/apps/{app_id}/performanceOverviews`).+# One request per app returns the whole document, which is flattened into rows.+EndpointKind = Literal["collection", "app_fanout", "sales_report", "analytics_report", "app_overview"]# Apple caps most collection pages at 200 resources.MAX_PAGE_SIZE = 200@@ -195,6 +197,16 @@ APP_STORE_CONNECT_ENDPOINTS: dict[str, AppStoreConnectEndpointConfig] = {primary_keys=["app_id", "id"],path="/v1/apps/{app_id}/subscriptionGroups",),+ # Xcode's aggregated performance metrics (launch time, hangs, memory, battery, disk writes) by+ # app version. Rows are the overview's metric points, one per (metric, percentile, device,+ # version). The document is a current snapshot with no date to filter or partition on, so+ # this is a full refresh.+ "performance_overviews": AppStoreConnectEndpointConfig(+ name="performance_overviews",+ kind="app_overview",+ primary_keys=["app_id", "category", "metric", "percentile", "device", "version"],+ path="/v1/apps/{app_id}/performanceOverviews",+ ),# Daily units and proceeds. Off by default because it needs a vendor number and a Finance or Sales# role on the key. Keyed on (report date, line number): a published day's file is immutable, so the# pair is stable and unique, and re-reading a day merges cleanly.diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/app_store_connect/source.py b/products/warehouse_sources/backend/temporal/data_imports/sources/app_store_connect/source.pyindex a9faceb7bc30..3f9150cd7811 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/app_store_connect/source.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/app_store_connect/source.py@@ -80,7 +80,7 @@ Sales and subscription reports also need your vendor number (App Store ConnectThe analytics tables need a key with the Admin role. Apple lets only an Admin key start an analytics report.-Leave **app IDs** blank to sync every app the key can read. To sync only some of your apps, list their Apple IDs, separated by commas. You can find an app's Apple ID in App Store Connect under **App Information → General Information**. The filter covers the apps, versions, reviews, review responses, in-app purchases, subscription groups and analytics tables. Builds, TestFlight groups and the sales reports cover your whole account, so they are not filtered."""+Leave **app IDs** blank to sync every app the key can read. To sync only some of your apps, list their Apple IDs, separated by commas. You can find an app's Apple ID in App Store Connect under **App Information → General Information**. The filter covers the apps, versions, reviews, review responses, in-app purchases, subscription groups, performance overviews and analytics tables. Builds, TestFlight groups and the sales reports cover your whole account, so they are not filtered."""restatement_note = restatement_caption()if restatement_note:caption = f"{caption}\n\n{restatement_note}"diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/app_store_connect/tests/test_app_store_connect.py b/products/warehouse_sources/backend/temporal/data_imports/sources/app_store_connect/tests/test_app_store_connect.pyindex c37b3e7ff60b..0b9c7c09d906 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/app_store_connect/tests/test_app_store_connect.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/app_store_connect/tests/test_app_store_connect.py@@ -535,6 +535,119 @@ class TestAppFanoutEndpoints:assert [row["id"] for row in rows] == ["R1", "R2", "R3"]+def _overview(*versions: tuple[str, float]) -> dict[str, Any]:+ return {+ "version": "1.0",+ "appMetadata": {"bundleId": "com.example.app", "appId": "A1", "latestVersion": "2.0", "platform": "IOS"},+ "insights": {"regressions": [{"metric": "launchTime"}]},+ "categories": [+ {+ "identifier": "launch",+ "displayName": "Launch Time",+ "sections": [+ {+ "identifier": "launchTime",+ "displayName": "Time to first draw",+ "unit": {"identifier": "ms", "displayName": "Milliseconds"},+ "datasets": [+ {+ "filterCriteria": {"percentile": "p50", "device": "all_iPhones"},+ "points": [{"version": version, "value": value} for version, value in versions],+ "recommendedMetricGoal": {"value": 400, "detail": "Under 400 ms"},+ }+ ],+ }+ ],+ }+ ],+ }+++class _FakeOverviewApi(_FakeApi):+ """Serves overview documents per app; an app with no document 404s."""++ def __init__(self, bodies: dict[str, dict[str, Any]]) -> None:+ super().__init__(bodies)+ self.accepts: list[str] = []++ def get(self, url: str, **kwargs: Any) -> MagicMock:+ if url.endswith("/performanceOverviews"):+ self.calls.append((url, kwargs.get("params")))+ self.accepts.append(kwargs["headers"]["Accept"])+ if url not in self.bodies:+ return _json_response({"errors": [{"status": "404"}]}, status_code=404)+ return _json_response(self.bodies[url])+ return super().get(url, **kwargs)+++class TestPerformanceOverviews:+ def _api(self) -> _FakeOverviewApi:+ return _FakeOverviewApi(+ {+ f"{BASE_URL}/v1/apps": _page(+ [_resource("apps", "A1"), _resource("apps", "A2"), _resource("apps", "A3")]+ ),+ f"{BASE_URL}/v1/apps/A1/performanceOverviews": _overview(("1.0", 512.5), ("2.0", 380.0)),+ f"{BASE_URL}/v1/apps/A3/performanceOverviews": _overview(("3.1", 290.0)),+ }+ )++ def test_flattens_metric_points_and_skips_an_app_without_an_overview(self) -> None:+ api = self._api()++ rows = _collect("performance_overviews", api, _FakeManager())++ assert [(row["app_id"], row["version"], row["value"]) for row in rows] == [+ ("A1", "1.0", 512.5),+ ("A1", "2.0", 380.0),+ ("A3", "3.1", 290.0),+ ]+ assert rows[0] == {+ "app_id": "A1",+ "bundle_id": "com.example.app",+ "platform": "IOS",+ "latest_version": "2.0",+ "category": "launch",+ "category_name": "Launch Time",+ "metric": "launchTime",+ "metric_name": "Time to first draw",+ "unit": "ms",+ "unit_name": "Milliseconds",+ "percentile": "p50",+ "device": "all_iPhones",+ "device_marketing_name": None,+ "version": "1.0",+ "value": 512.5,+ "error_margin": None,+ "breakdown_value": None,+ "breakdown_subsystem": None,+ "recommended_goal_value": 400,+ "recommended_goal_detail": "Under 400 ms",+ }+ assert set(api.accepts) == {"application/vnd.apple.xcode-overview+json"}++ @parameterized.expand(+ [+ ("bookmarked_app_still_listed", "A3"),+ ("bookmarked_app_no_longer_listed", "A25"),+ ]+ )+ def test_bookmarks_the_next_app_and_resumes_without_refetching_earlier_apps(+ self, _name: str, bookmark: str+ ) -> None:+ manager = _FakeManager()+ _collect("performance_overviews", self._api(), manager)+ assert [state.app_id for state in manager.saved] == ["A2", "A3"]++ api = self._api()+ rows = _collect("performance_overviews", api, _FakeManager(AppStoreConnectResumeConfig(app_id=bookmark)))++ assert [row["app_id"] for row in rows] == ["A3"]+ assert [url for url, _ in api.calls if url.endswith("/performanceOverviews")] == [+ f"{BASE_URL}/v1/apps/A3/performanceOverviews"+ ]++class TestCheckAppIds:def _message(self, app_ids: str | None, apps: list[dict[str, Any]]) -> tuple[str | None, _FakeApi]:api = _FakeApi({f"{BASE_URL}/v1/apps": _page(apps)})