onatcipli/app-store-reviews

App Store Reviews

Analyze App Store reviews, generate intelligent replies, and extract competitive insights using Apple's public and private APIs.

Workflow 0 — App Setup & Onboarding

Before generating replies, run the onboarding process to create an app-specific configuration file. This ensures replies match your brand voice consistently.

Quick Start

1. Ask the user: "Would you like to set up reply preferences for your app?"
2. If yes, proceed with onboarding
3. If a config file already exists, ask if they want to update it

Onboarding Steps

1. Fetch existing responses (if available):

   GET /v1/apps/{appId}/customerReviews?include=response&limit=100
   

2. Auto-detect patterns from existing replies:

   • Greeting style ("Hi {name}," vs "Hello!")
   • Sign-off ("— The Team" vs none)
   • Tone (formal vs casual)
   • Emoji usage
   • Support email/URLs
   • Common phrases

3. Present findings to user:

   "I analyzed {n} existing replies and detected these patterns:
    - Tone: {detected_tone}
    - Sign-off: {detected_signoff}
    - Emoji usage: {detected_emoji}
    Would you like to use these as defaults?"
   

4. Conduct interview with smart defaults:

   • App identity (name, description, support email)
   • Brand voice (tone, emoji, sign-off)
   • Reply policies (escalation, restricted topics)
   • Language support

   See onboarding-interview.md for full question list.

5. Generate config file:

   • Create {app-name}-review-config.md
   • Save to user's preferred location
   • Confirm file location

Output

The onboarding process generates a markdown configuration file following the template in app-config-template.md.

Re-running Setup

Users can update their configuration at any time:

• Update specific settings
• Start fresh with new configuration
• Keep existing and continue

---

API Access Tiers

ReviewCat works with two tiers of Apple endpoints:

| Tier | Auth | Scope | Reference | |------|------|-------|-----------| | Public | None | Any app (read-only reviews, search, lookup) | See apple-endpoints.md §1 | | Private | JWT (App Store Connect) | Your own apps (full CRUD on reviews + responses) | See apple-endpoints.md §2 |

Choose the tier based on the task:

• Own app → prefer Private API (more data, filtering, responses, summarizations)
• Competitor app → must use Public API (RSS feed, iTunes Search)
• Quick lookup / no auth available → Public API

Workflow 1 — Fetch & Analyze Own App Reviews

1. Generate a JWT token (see apple-endpoints.md §2.1)
2. Fetch reviews: GET /v1/apps/{appId}/customerReviews
   • Use sort=-createdDate for newest first
   • Use filter[rating]=1,2 to focus on negative reviews
   • Use filter[territory]=USA for a specific country
   • Set limit=200 and paginate via links.next
3. For version-specific reviews, first list versions with GET /v1/apps/{appId}/appStoreVersions, then query GET /v1/appStoreVersions/{versionId}/customerReviews
4. Run analysis on collected reviews (see Workflow 5)

Workflow 2 — Fetch Competitor Reviews

1. Search for competitor: GET https://itunes.apple.com/search?term={name}&media=software
2. Extract trackId from results
3. Fetch reviews via RSS:

   GET https://itunes.apple.com/{country}/rss/customerreviews/page={1-10}/id={trackId}/sortby=mostrecent/json
   

4. Loop pages 1–10 (max 500 reviews per country)
5. For multi-country analysis, iterate over country codes: us, gb, de, fr, jp, au, ca, br, kr, cn
6. Parse entries from feed.entry[] — fields: im:rating.label, title.label, content.label, author.name.label, im:version.label

Workflow 3 — Generate Replies to Reviews

Generate context-aware, professional developer responses to customer reviews.

Pre-requisite: App Configuration

Before generating replies, check if an app configuration file exists:

1. If config exists: Load settings from {app-name}-review-config.md
2. If no config: Prompt user to run Workflow 0 first, or proceed with default settings

When a config file is available, apply these settings:

• Brand voice: Tone, emoji usage, sign-off style
• Preferred phrases: Use configured phrases where appropriate
• Avoided phrases: Never use words/phrases marked as restricted
• Policies: Follow escalation rules and restricted topics
• Language: Match supported language preferences

Reply Strategy

| Rating | Tone | Strategy | |--------|------|----------| | 1–2 stars | Empathetic, solution-focused | Acknowledge frustration, offer fix/workaround, invite follow-up | | 3 stars | Grateful, improvement-oriented | Thank for feedback, highlight upcoming improvements | | 4–5 stars | Warm, brief | Thank the user, reinforce positive experience |

Instructions

1. Load app config (if available) from {app-name}-review-config.md
2. Read the review's rating, title, body, and territory
3. Identify the core issue or sentiment
4. Check if topic is restricted (redirect to support if so)
5. Select reply strategy based on rating + config policies
6. Draft response following:
   • App config settings (tone, phrases, emoji, sign-off)
   • Patterns in reply-templates.md
7. Validate reply against config constraints:
   • No restricted topics mentioned
   • No avoided phrases used
   • Correct sign-off applied
   • Length within config preference
8. Post via POST /v1/customerReviewResponses (private API only)

Constraints

• Max response length: 5,970 characters (Apple's limit)
• Do NOT include personal information, legal promises, or pricing details
• Always be professional — never argue or be defensive
• Reference specific issues the user raised to show the reply is not generic
• For non-English reviews, respond in the same language as the review
• Follow all policies defined in app config file

Workflow 4 — Competitor Comparison

Build a competitive analysis comparing your app with competitors.

1. Fetch your app's reviews (Workflow 1) and competitor reviews (Workflow 2)
2. For each app, compute:
   • Average rating (overall + per version)
   • Rating distribution (count per star)
   • Sentiment score — ratio of positive (4–5) to negative (1–2) reviews
   • Review velocity — reviews per week/month
3. Run theme extraction on each app's reviews (see Workflow 5)
4. Identify:
   • Your strengths — themes praised in your reviews but criticized in competitors
   • Your gaps — themes praised in competitors but criticized in your reviews
   • Common pain points — negative themes shared across all apps
   • Feature requests — features users ask for across all apps
5. Output a structured comparison report (see analysis-prompts.md §competitor-report)

Workflow 5 — Analyze Reviews

Perform deep analysis on a set of collected reviews. See analysis-prompts.md for detailed prompt patterns.

Theme Extraction

Categorize every review into one or more themes:

• Bug report — crashes, errors, broken features
• Feature request — missing functionality users want
• UX complaint — confusing UI, poor navigation, design issues
• Performance — slow, battery drain, storage usage
• Pricing — subscription cost, value perception, payment issues
• Praise — positive feedback on specific features
• Support — customer service experience

For each theme, track: count, average rating, representative quotes, trend direction.

Sentiment Analysis

Classify each review as: positive, neutral, negative, mixed.

Use the following signals:

• Rating (primary signal): 1–2 = negative, 3 = neutral/mixed, 4–5 = positive
• Body text sentiment (secondary signal): override rating when text clearly contradicts it (e.g., 5-star review that says "app is terrible but I accidentally tapped 5 stars")

Actionable Insights

From the analyzed reviews, extract:

1. Top 5 issues — most mentioned negative themes, sorted by frequency
2. Top 5 praised features — most mentioned positive themes
3. Trending issues — themes increasing in frequency over recent reviews
4. Quick wins — issues that appear fixable and are frequently mentioned
5. Feature demand — requested features ranked by mention count

Workflow 6 — Executive Summary Report

Generate a concise report for stakeholders.

Report Structure

## Review Summary — {App Name} — {Date Range}

### Key Metrics
- Total reviews: {n}
- Average rating: {x.x}/5
- Rating distribution: ★5: {n} | ★4: {n} | ★3: {n} | ★2: {n} | ★1: {n}
- Sentiment: {x}% positive, {x}% neutral, {x}% negative

### Top Issues
1. {Issue} — {count} mentions — "{representative quote}"
2. ...

### Top Praise
1. {Feature} — {count} mentions — "{representative quote}"
2. ...

### Trending
- ↑ Increasing: {themes getting worse}
- ↓ Decreasing: {themes improving}

### Recommendations
1. {Actionable recommendation based on data}
2. ...

Workflow 7 — Rating Trend Monitoring

Track how ratings change over time.

1. Fetch reviews with sort=createdDate to get chronological order
2. Group reviews by time period (day/week/month)
3. Compute per-period: average rating, review count, sentiment ratio
4. Identify inflection points — sudden drops/spikes in rating
5. Correlate with app version releases (use im:version from RSS or version endpoint from private API)
6. Flag anomalies: rating drop > 0.5 stars, negative review spike > 2x average

Pagination Reference

Private API (App Store Connect)

Cursor-based. Follow links.next URL until absent:

url = f"https://api.appstoreconnect.apple.com/v1/apps/{app_id}/customerReviews?limit=200&sort=-createdDate"
all_reviews = []
while url:
    resp = requests.get(url, headers={"Authorization": f"Bearer {token}"})
    data = resp.json()
    all_reviews.extend(data["data"])
    url = data.get("links", {}).get("next")

Public API (RSS Feed)

Page-based. Iterate pages 1–10:

for page in range(1, 11):
    url = f"https://itunes.apple.com/{country}/rss/customerreviews/page={page}/id={app_id}/sortby=mostrecent/json"
    resp = requests.get(url)
    entries = resp.json().get("feed", {}).get("entry", [])
    if not entries:
        break
    all_reviews.extend(entries)

Rate Limits

| Endpoint | Limit | Backoff Strategy | |----------|-------|-----------------| | App Store Connect API | Undocumented — use moderate pace | Exponential backoff on 429/503 | | iTunes Search / Lookup | ~20 req/min | Wait 3s between calls | | RSS Feed | Undocumented — can get 403 | Wait 5s between country iterations |

Quick Reference — Endpoint Cheat Sheet

| Task | Method | Endpoint | Auth | |------|--------|----------|------| | Search apps | GET | itunes.apple.com/search?term=...&media=software | Public | | Lookup app | GET | itunes.apple.com/lookup?id=... | Public | | Public reviews | GET | itunes.apple.com/{cc}/rss/customerreviews/page={p}/id={id}/sortby=mostrecent/json | Public | | List reviews | GET | /v1/apps/{id}/customerReviews | JWT | | Version reviews | GET | /v1/appStoreVersions/{id}/customerReviews | JWT | | Single review | GET | /v1/customerReviews/{id} | JWT | | Get response | GET | /v1/customerReviews/{id}/response | JWT | | Post response | POST | /v1/customerReviewResponses | JWT | | Delete response | DELETE | /v1/customerReviewResponses/{id} | JWT | | Summarizations | GET | /v1/apps/{id}/customerReviewSummarizations | JWT | | List versions | GET | /v1/apps/{id}/appStoreVersions | JWT |

For full endpoint details, parameters, and authentication setup, see apple-endpoints.md.

Reference Files

| File | Purpose | |------|---------| | apple-endpoints.md | API endpoint details, authentication, parameters | | analysis-prompts.md | Prompt patterns for review analysis | | reply-templates.md | Reply templates by rating and issue type | | onboarding-interview.md | Interview questions and auto-detection logic | | app-config-template.md | Template for app-specific config files |