https://github.com/zmsp/appstore-analytics
Automated analytics ingestion pipeline for Google Play Console & Apple App Store Connect. Sync active devices, installs, uninstalls, and crashes without sales tables via Node.js & Docker.
https://github.com/zmsp/appstore-analytics
andorid app-analytics app-store-connect-api apple appstore devops-analytics dockerized-dashboard google-play-console play-store-stats playstore
Last synced: 4 days ago
JSON representation
Automated analytics ingestion pipeline for Google Play Console & Apple App Store Connect. Sync active devices, installs, uninstalls, and crashes without sales tables via Node.js & Docker.
- Host: GitHub
- URL: https://github.com/zmsp/appstore-analytics
- Owner: zmsp
- License: mit
- Created: 2026-07-18T07:33:58.000Z (6 days ago)
- Default Branch: main
- Last Pushed: 2026-07-18T09:05:23.000Z (6 days ago)
- Last Synced: 2026-07-18T09:13:43.712Z (6 days ago)
- Topics: andorid, app-analytics, app-store-connect-api, apple, appstore, devops-analytics, dockerized-dashboard, google-play-console, play-store-stats, playstore
- Language: JavaScript
- Homepage: https://www.zobairshahadat.com/appstore-analytics/
- Size: 1.37 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://www.zobairshahadat.com/appstore-analytics/)
*(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:**
```bash
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:**
```bash
docker run -d \
-p 3000:3000 \
-v $(pwd)/data:/app/data \
--name appstore-analytics \
ghcr.io/zmsp/appstore-analytics:sha-65d8ec55f30974f879afd526106cdf21aea8a15b
```
*Note: Place your `config.json` and keys directly inside the `data` directory on your host for persistent storage.*
### Option B: Build from Source
1. **Clone the repository:**
```bash
git clone https://github.com/your-username/store_stat_viewer.git
cd store_stat_viewer
```
2. **Run via Docker Compose:**
```bash
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.
```mermaid
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)]
```
### 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.
```mermaid
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])
```
---
## 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](https://console.cloud.google.com/iam-admin/serviceaccounts).
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](https://play.google.com/apps/publish) -> **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](https://appstoreconnect.apple.com/) -> **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.
```json
[
{
"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)**
```bash
# 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**
```bash
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
```text
.
├── 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](LICENSE) file for details.