App Store Stats Viewer

A premium Node.js application for aggregating and visualizing install, active device, and uninstall metrics across the Google Play Store and Apple App Store.

Includes a web-based dashboard, a CLI for programmatic access, and a mock-data demo mode for local evaluation.

---

Live Demo

Explore the Dashboard Demo
(Note: The demo is locked in Simulated Mode with rich sample data)

---

Quick Start (Docker)

Option A: Pre-built Image (Recommended)

Pull the latest image directly from the GitHub Container Registry.

1. Pull the image:

   docker pull ghcr.io/zmsp/appstore-analytics:sha-65d8ec55f30974f879afd526106cdf21aea8a15b

2. Prepare configuration: Create a config directory in your host path. Place your config.json and any required .json or .p8 API keys inside it.

3. Run the container:

   docker run -d \
     -p 3000:3000 \
     -v $(pwd)/config:/config \
     -v $(pwd)/data:/app/downloaded_stats \
     -e CONFIG_PATH=/config/config.json \
     --name appstore-analytics \
     ghcr.io/zmsp/appstore-analytics:sha-65d8ec55f30974f879afd526106cdf21aea8a15b

Option B: Build from Source

1. Clone the repository:

   git clone https://github.com/your-username/store_stat_viewer.git
   cd store_stat_viewer

2. Run via Docker Compose:

   docker-compose up -d

3. Access the Web UI: Navigate to http://localhost:3000.

   • Initial Setup: You will be prompted to configure an admin password on the first run.
   • Demo Mode: Toggle the switch in the sidebar to bypass authentication and preview the UI with simulated data.

---

Key Features

• Web Dashboard: Glassmorphic dark-themed UI with Chart.js visualizations for daily event trends, segmentable by country, OS version, app version, and device type.
• Multi-Platform Aggregation: Unified data layer fetching from Google Play Console (via GCS exports) and Apple App Store Connect.
• Headless CLI: Terminal utility for scripting, cron jobs, or rapid querying without the web interface.
• Self-Hosted & Secure: Local data persistence and JWT-based authentication for the web interface. Service account keys remain on your host.

---

Architecture & Data Flow

System Architecture

The backend is an Express-based Node.js server that handles API communication with Google Cloud Storage and App Store Connect, serving data to a single-page frontend.

graph TD
    subgraph Frontend
        WebUI[Web Dashboard]
        StaticConfig[static_config.json]
    end

    subgraph Backend
        Server[Express Server]
        CLI[CLI Utility]
    end

    subgraph Core Libraries
        GCSLib[Google Play Lib]
        AppleLib[App Store Lib]
    end

    subgraph External Data Sources
        GCS[(Google Cloud Storage)]
        AppStoreAPI[(App Store Connect API)]
    end

    User([User / Browser]) <--> WebUI
    WebUI <--> Server
    WebUI -- Read if Static --> StaticConfig
    Server --> GCSLib
    Server --> AppleLib
    CLI --> GCSLib
    
    GCSLib <--> GCS
    AppleLib <--> AppStoreAPI
    
    Server <--> LocalCache[(Local Cache)]

Loading

CI/CD Pipeline

Pushes to the main branch trigger a GitHub Actions workflow that builds a new production Docker image (GHCR) and updates the static demo deployed to GitHub Pages.

graph LR
    Push[git push main] --> GHA[GitHub Actions]
    subgraph GitHub Actions
        BuildDemo[Build Demo]
        BuildDocker[Build Docker]
    end
    BuildDemo --> GHPages[GitHub Pages]
    BuildDocker --> GHCR[GitHub Container Registry]
    
    GHPages --> DemoUser([Public User])
    GHCR --> SelfHost([Self-Hosted Docker])

Loading

---

Prerequisites & Authentication Setup

1. Google Play Console (GCS Exports)

Google Play exports bulk reports directly into a Google Cloud Storage (GCS) bucket.

A. Retrieve the GCP Service Account Key

1. Go to the Google Cloud IAM Service Accounts Console.
2. Create a service account (e.g. playstore-stats-reader).
3. In the Keys tab, click Add Key -> Create New Key (JSON).
4. Save the file to config/keys/google_key.json.

B. Connect to your Play Console

1. Go to the Google Play Console -> Users and Permissions.
2. Invite the service account email.
3. Grant "View app information and download bulk reports (read-only)" permission.
4. Note: It can take up to 24 hours for bucket permissions to synchronize.

C. Find your Bucket Name

1. In Play Console, go to Download reports -> Statistics.
2. Click Copy Cloud Storage URI (e.g. gs://pubsite_prod_12345678/stats/installs/).
3. The bucket name is the part between gs:// and the first slash: pubsite_prod_12345678.

2. Apple App Store Connect

1. Go to App Store Connect -> Users and Access -> Keys.
2. Generate an API Key with Sales and Reports access.
3. Download the .p8 file and save it to config/keys/apple_key.p8.
4. Note your Issuer ID and Key ID.

---

Configuration

The dashboard and CLI look for a config/config.json file. Use the following template as a guide.

[
  {
    "name": "Production Account",
    "projectID": "your-gcp-project-id",
    "bucketName": "pubsite_prod_12345678",
    "keyFilePath": "keys/google_key.json",
    "appleIssuerId": "xxxx-xxxx-xxxx",
    "appleKeyId": "XXXXXXXXXX",
    "keyFilePath_apple": "keys/apple_key.p8",
    "ignoredPackages": ["com.example.testapp"]
  }
]

Field	Platform	Description
name	Both	Display name for this configuration set.
projectID	Google	Your Google Cloud Project ID.
bucketName	Google	The GCS bucket name where Play Console exports reports.
keyFilePath	Google	Path to the service account JSON key (relative to config.json).
appleIssuerId	Apple	Issuer ID from App Store Connect API.
appleKeyId	Apple	Key ID from App Store Connect API.
keyFilePath_apple	Apple	Path to the .p8 private key (relative to config.json).
ignoredPackages	Google	Optional array of package names to hide from the dashboard.

---

Usage

CLI Utility

You can query your stats directly in the command line.

Option A: Using a Saved Project (Recommended)

# Query the first project in config (index 0)
node app/cli.js -s 0

# Query by project name
node app/cli.js -s "Production Account"

Option B: Manual Parameters

node app/cli.js \
  --key="config/keys/google_key.json" \
  --projectID="your-id" \
  --bucketName="your-bucket" \
  --packageName="com.example.app"

CLI Options

Argument	Alias	Description
--key	-k	Path to the service account JSON key file
--project	-s	Name or index of the saved project from config
--config	-c	Path to config.json (defaults to ../config/config.json)
--projectID	-g	Google Cloud Project ID
--bucketName	-b	Google Play Console GCS Bucket name
--packageName	-p	App package identifier (e.g. com.example.app)

---

Project Structure

.
├── app/
│   ├── lib/              # Core logic for GCS and App Store integration
│   ├── public/           # Dashboard frontend (HTML/JS/CSS)
│   ├── server.js         # Express API backend server
│   └── cli.js            # Command-line utility
├── config/               # User configuration and keys (GIT IGNORED)
├── Dockerfile            # Multi-stage production Docker image
└── docker-compose.yml    # Docker orchestration

---

License

This project is licensed under the MIT License - see the LICENSE file for details.