app-store-reviews

name

app-store-reviews

description

App Store review analysis, competitor intelligence, and automated response generation for iOS/macOS apps. Use this skill when working with Apple App Store reviews for any of these tasks: (1) Fetching and analyzing customer reviews for your own apps via the App Store Connect API, (2) Fetching competitor app reviews via the public RSS feed or iTunes Search API, (3) Performing sentiment analysis, theme extraction, or bug/feature-request categorization on reviews, (4) Generating context-aware developer replies to customer reviews, (5) Comparing ratings, review sentiment, or feature gaps across competing apps, (6) Tracking rating trends and review volume over time, (7) Producing executive summaries or actionable insight reports from review data, (8) Searching the App Store for apps by name or category, (9) Setting up app-specific reply configurations through an interactive onboarding interview that auto-detects patterns from existing responses.

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