--- name: store-analytics description: Take store analytics snapshots for a mobile app or game (App Store impressions, product page views, downloads and conversion through the Analytics Reports API; Google Play store listing visitors, acquisitions and installs from the Play reports bucket) and compare them with listing, screenshot and experiment changes from git; download App Store sales / finance reports and Play earnings / sales reports with a summary per product and currency. Use when the user asks whether a listing change, new screenshots or a store experiment worked, wants install / conversion numbers, sets up store reporting, or wants sales, proceeds or earnings numbers. --- # Store analytics CLI: `storebound analytics setup | snapshot | compare`. MCP: `analytics_snapshot`, `analytics_compare` (offline), `analytics_setup`. Read-only on both stores except `setup` (creates the App Store report request). Snapshots go to `.storebound/analytics/.json` (gitignored; they are your business numbers). ## What is possible (and what is not) - **App Store**: the Analytics Reports API. An Admin key creates one ONGOING report request (`storebound analytics setup`); the first reports come 1-2 days later, then daily, and Apple keeps instances for 35 days, so take a snapshot at least monthly (weekly is better). A request left unread for a long time stops (`stoppedDueToInactivity`); `setup` makes a new one. storebound reads "App Store Discovery and Engagement" (Event Impression / Page view, Counts and Unique Counts) and "App Store Downloads" (First-time Download, Redownload; updates are left out), checks each segment's md5 checksum and keeps, per day, the newest processing of that day. Conversion = (first-time downloads + redownloads) / unique impressions. Source: https://developer.apple.com/documentation/appstoreconnectapi/downloading-analytics-reports - **Google Play**: there is **no API** for store listing statistics (the Play Developer Reporting API only has vitals). Play Console writes monthly CSV exports into your own Cloud Storage bucket; storebound reads them with the service account. Setup: Play Console > Download reports > Statistics > **Copy Cloud Storage URI** and put the bucket into `play.reportsBucket` (`pubsite_prod_rev_`); the service account needs "View app information and download bulk reports" (Play Console Help answer 6135870). Files appear with a few days' delay; the current month's file grows daily. Conversion = store listing acquisitions / store listing visitors. - **Not possible through any API**: Play store listing experiment results and App Store Product Page Optimization results (read them in the consoles; `storebound apple ppo status` shows the App Store test state), Play "Explore" search terms beyond the traffic source file. ## Flow 1. Once: `storebound analytics setup` (App Store) and `play.reportsBucket` (Play). 2. Weekly: `storebound analytics snapshot` (default the last 28 days; `--dry` prints totals only). 3. Change the listing as usual and commit it (`store/appstore.md`, `store/listing.md`, `store/shots/...`, the config). One change at a time, with a clear commit subject ("new first screenshot: boss fight"), makes the comparison readable. 4. `storebound analytics compare` (or `--md` for a report): for every commit that touched the store files, daily impressions (App Store) or visitors (Play) and conversion in the 7 days before vs the 7 days from the change (`--days 14` for small apps). ## Sales and finance reports `storebound reports ` downloads one report into `.storebound/reports/` (gitignored: these files hold per-order rows and buyer locations) and prints a summary per product and currency plus `.summary.csv` (or `--csv `); totals are never added across currencies. `--dry` shows the request only. MCP: `reports`. - **App Store**: `apple-sales [--type SALES] [--frequency DAILY|WEEKLY|MONTHLY|YEARLY] [--date ...]` (Sales and Trends; other types: PRE_ORDER, SUBSCRIPTION, SUBSCRIPTION_EVENT, SUBSCRIBER, SUBSCRIPTION_OFFER_CODE_REDEMPTION, WIN_BACK_ELIGIBILITY, each with Apple's fixed frequency and version) and `apple-finance --month YYYY-MM` (Apple fiscal month; consolidated region ZZ, `--detail` for the Financial Detail report, region Z1). Needs a **team** API key (not an individual key) with access to reports, and the vendor number (App Store Connect > Payments and Financial Reports) as `ASC_VENDOR_NUMBER` in the environment, a credential profile (`--account`) or `.storebound/credentials.json`, never in the config. A 404 means "no report for that date" (no sales, or not out yet: daily reports come the next day). - **Google Play**: `play-earnings --month YYYY-MM` / `play-sales --month YYYY-MM` read `earnings/earnings_YYYYMM*.zip` and `sales/salesreport_YYYYMM*.zip` from `play.reportsBucket` and unzip them. The service account needs "View financial data" in Play Console (Users and permissions). Earnings arrive early in the next month; estimated sales update daily. - Money numbers are the owner's: never paste them into issues, commits or public text. ## Read it honestly - Small numbers swing: under a few hundred page views a week, a 20 % change is noise. Say so. - Seasonality, featuring, ads campaigns, a rating drop and price changes move the same numbers. Look at the same weekday span and mention other things that changed in that window. - A before / after comparison is not an experiment. For a real answer use the store tests: Play store listing experiments (Console) and App Store Product Page Optimization (`storebound apple ppo`, store-screenshots skill). - Never present estimates as facts to the owner, and never put these numbers into public text (listings, replies).