# App Review Intelligence (`codepal/app-review-intelligence`) Actor

Turn App Store and Google Play reviews into product insight: complaint topics, feature requests, release regressions, rating trends, developer reply stats and gaps vs competitors. Alerts on rating drops and crash spikes, optional AI summaries.

- **URL**: https://apify.com/codepal/app-review-intelligence.md
- **Developed by:** [Jared Keanche](https://apify.com/codepal) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.50 / 1,000 review analyzeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## App Review Intelligence

**Turn App Store and Google Play reviews into answers: what's breaking, what users want next, which release hurt your rating, and where competitors beat you. Alerts reach Slack before your rating drops.**

Most review scrapers give you a spreadsheet of text. This Actor reads the reviews for you:

- **Complaint topics**: crashes & bugs, performance, login & OTP, payments (incl. M-Pesa), pricing & subscriptions, ads, UI/UX, customer support, update regressions, notifications, privacy & fraud, delivery, content quality. It covers English and common Swahili/Sheng.
- **Feature requests**, grouped ("dark mode", "offline mode", "export statements") with mention counts and the best example.
- **Release impact**: average rating and negative share per app version, the change vs the previous version, and **regressions** flagged automatically.
- **Trends**: weekly average rating, last N days vs before, and topic spikes ("crashes jumped from 3% to 41% of reviews").
- **Unhappy-user phrases** that appear far more often in 1–2★ reviews ("otp not received", "crashes on startup").
- **Developer replies** (Google Play): reply rate, reply rate on negative reviews, median reply time.
- **Competitor comparison**: health score, ratings, crash share, top complaint, top request, plus **topic gaps** where you get more complaints than competitors.
- **Alerts**: recent rating drop, store-rating drop, complaint spikes and release regressions, sent to Slack, Discord, Teams or any webhook.
- **Optional AI insights** with your own key (OpenAI, OpenRouter, Groq…): an executive summary, issues with evidence, likely causes and fixes, feature priorities and a reply template. Reviewer names are never sent.

### Input

```json
{
  "apps": ["https://play.google.com/store/apps/details?id=com.example.wallet&gl=KE", "https://apps.apple.com/ke/app/example-wallet/id1234567890"],
  "competitorApps": ["com.rival.wallet", "id987654321"],
  "appStoreCountries": ["ke", "us"],
  "daysBack": 90,
  "monitorName": "wallet-daily",
  "webhookUrl": "https://hooks.slack.com/services/…"
}
```

Accepted formats: store URLs, App Store ids (`id389801252` or `389801252`) and Play package names (`com.whatsapp`). Add a label with `My App (iOS) = id123…`.

### Output

- **Dataset, view *App summaries***: one row per app with store rating, period and recent averages, negative %, health score (0–100), top complaints with examples and trends, feature requests, versions and regressions, weekly trend, reply stats, alerts and AI insights.
- **Dataset, view *Classified reviews***: each review with rating, date, version, country, topics, sentiment, feature request, helpful votes, developer reply and `is_new`.
- **REPORT**: shareable HTML with alerts, a comparison table, per-app details and release impact.
- **COMPARISON**, **FEATURE_REQUESTS**, **OUTPUT**: JSON for dashboards and automations.

### Scheduling a monitor

1. Run once to build the baseline. The first run sends no alerts.
2. Schedule daily or weekly with the same `monitorName`. Turn on *Only new reviews in dataset* if you push rows into a sheet.
3. Alerts fire on: the recent average dropping by ≥ 0.3★, the store rating falling, a complaint topic rising ≥ 10 points, or a new version rating much worse than the previous one.

You pay for each review only once per monitor. Re-analysis in later runs is free.

### Good to know

- **App Store**: Apple's public feed exposes the ~500 most recent reviews per country. Add the countries where your users are.
- **Google Play**: reviews are filtered by language (`playLanguage`) and country. Large or frequent runs may need Apify Proxy.
- Sentiment follows the star rating. Text sentiment is used to flag mismatches (e.g. 5★ with an angry text).
- Topic detection is keyword-based: fast, free and explainable, but not perfect. Turn on AI insights for nuanced root causes.
- Reviewer names are excluded unless you turn them on.

### Pricing

$0.50 per 1,000 new reviews analyzed + $0.02 per app report, + $0.01 per AI insight (optional). See PRICING.md.

# Actor input Schema

## `apps` (type: `array`):

App Store or Google Play URLs, App Store ids (id389801252) or Play package names (com.whatsapp). Add both store versions of the same app as separate lines. Optional label: 'My App (Android) = com.example.app'.

## `competitorApps` (type: `array`):

Same formats. Used for the side-by-side comparison and topic gaps.

## `appStoreCountries` (type: `array`):

Two-letter country codes (us, gb, ke, ng, za…). App Store reviews are per country; the latest ~500 per country are available.

## `playCountry` (type: `string`):

Two-letter country code (used when the URL has no gl= parameter).

## `playLanguage` (type: `string`):

Two-letter language code (en, fr, sw, pt…). Google Play returns reviews written in this language.

## `maxReviewsPerApp` (type: `integer`):

Newest reviews first.

## `daysBack` (type: `integer`):

Only reviews from the last N days. 0 = no limit.

## `recentDays` (type: `integer`):

Recent reviews are compared with older ones to spot rating drops and complaint spikes.

## `outputReviews` (type: `boolean`):

Add every classified review to the dataset (in addition to app summaries).

## `onlyNewReviews` (type: `boolean`):

For scheduled runs: save only reviews not seen by this monitor before. Analysis still uses the whole window.

## `includeReviewerNames` (type: `boolean`):

Off by default (personal data). Turn on only if you need it, e.g. to match support tickets.

## `monitorName` (type: `string`):

Runs with the same name remember seen reviews and previous ratings (alerts, new-review counts, and you are only charged once per review).

## `alertRatingDrop` (type: `number`):

Alert when the recent average falls this much below the earlier average.

## `alertTopicSpikePts` (type: `integer`):

Alert when a complaint topic's share of recent reviews rises this many percentage points.

## `webhookUrl` (type: `string`):

HTTPS URL that receives alerts (Slack and Discord formatted automatically; JSON for Zapier, Make, n8n).

## `webhookSecret` (type: `string`):

Optional. Adds an x-signature-256 HMAC header.

## `enableAi` (type: `boolean`):

Per-app summary, issues with likely causes and fixes, feature priorities and a reply template, plus a competitor positioning summary. Uses your own API key; reviewer names are never sent.

## `aiBaseUrl` (type: `string`):

Any OpenAI-compatible API: OpenAI, OpenRouter (https://openrouter.ai/api/v1), Groq, Together, DeepSeek, a local Ollama…

## `aiModel` (type: `string`):

Model name at your provider.

## `aiApiKey` (type: `string`):

Stored encrypted. You pay your provider directly for tokens.

## `productContext` (type: `string`):

Optional: what the app does, recent releases, known issues. Helps the AI give better causes and fixes.

## `proxyConfiguration` (type: `object`):

Turn on Apify Proxy if Google Play starts refusing requests (large or frequent runs).

## Actor input object example

```json
{
  "apps": [
    "https://play.google.com/store/apps/details?id=com.whatsapp"
  ],
  "appStoreCountries": [
    "us"
  ],
  "playCountry": "us",
  "playLanguage": "en",
  "maxReviewsPerApp": 500,
  "daysBack": 90,
  "recentDays": 14,
  "outputReviews": true,
  "onlyNewReviews": false,
  "includeReviewerNames": false,
  "monitorName": "default",
  "alertRatingDrop": 0.3,
  "alertTopicSpikePts": 10,
  "enableAi": false,
  "aiBaseUrl": "https://api.openai.com/v1",
  "aiModel": "gpt-4o-mini",
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `apps` (type: `string`):

One row per app: ratings, complaints, feature requests, release impact, alerts.

## `reviews` (type: `string`):

Each review with topics, sentiment and feature request.

## `report` (type: `string`):

Shareable report with alerts, comparison and per-app details.

## `comparison` (type: `string`):

Side-by-side table, topic gaps and advantages.

## `featureRequests` (type: `string`):

Grouped feature requests per app with mentions and examples.

## `summary` (type: `string`):

Apps, alerts, gaps and warnings.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "apps": [
        "https://play.google.com/store/apps/details?id=com.whatsapp"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("codepal/app-review-intelligence").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "apps": ["https://play.google.com/store/apps/details?id=com.whatsapp"] }

# Run the Actor and wait for it to finish
run = client.actor("codepal/app-review-intelligence").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "apps": [
    "https://play.google.com/store/apps/details?id=com.whatsapp"
  ]
}' |
apify call codepal/app-review-intelligence --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,codepal/app-review-intelligence"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/0BcWuddpGtrpMXCZr/builds/NmLu5SUO9OaZuGmwU/openapi.json