app-store-optimization

App Store Optimization (ASO)

ASO is search-engine + conversion-rate optimization for app stores. Two levers move installs:

1. Discoverability — getting your listing to appear for the searches real users type. Driven by indexed metadata fields and keyword choice.
2. Conversion — turning an impression into an install. Driven by icon, title, subtitle, the first three screenshots, rating, and social proof.

Optimizing the wrong field wastes effort. The single most important fact in all of ASO: on iOS the description is NOT indexed. Never put keyword work there — it does nothing for ranking. (On Google Play the full description is indexed; see below.) This asymmetry drives almost every platform-specific rule.

This skill works in two modes:

• Local / pre-submission: run inside an app project, auto-detect Fastlane metadata, Xcode, or Gradle, and audit/optimize the metadata you are about to ship.
• Remote / live: pass an app ID or store URL to fetch and audit a live listing — your own app, or a competitor's.

---

The golden rules (violate any one and you waste real money)

These are absolute. Never recommend a change that breaks one.

1. iOS Name + Subtitle + Keywords are one shared index pool. Apple indexes all three independently, then de-duplicates. Never repeat a word (or its stem) across these three fields — a repeat wastes premium character budget for zero extra ranking. (couple in the subtitle AND in the keywords field = one word's worth of budget thrown away.)
2. Character budget = money. Use it all. Fill Name to ≥15 chars (CJK exempt — each character carries more meaning), Subtitle to ≥20, and the iOS keyword field to 95–100 of its 100. Empty space is lost ranking surface.
3. iOS description is not indexed — optimize it only for conversion. Lead with the value proposition; the first ~3 lines show before the "more" tap. Stuffing keywords here is pure waste.
4. Same language, different storefronts each get their own 100 chars. en-US / en-GB / en-AU / en-CA are four independent keyword fields. Use four different keyword sets — never copy the same string into all four. The same applies to fr-FR/fr-CA, es-ES/es-MX, zh-Hans/zh-Hant, pt-BR/pt-PT.
5. "Category match ≠ function match." This is the most-missed trap. A keyword whose top-ranked apps are in your category but serve a different function is poison: users search it, land on you, see the wrong thing, and bounce. Low conversion on a term tells Apple's algorithm the term is a bad fit and demotes your whole listing, not just that term. Prefer an empty keyword slot over a function-mismatch word. (Detection method in references/keyword-research.md.)
6. Avoid category-giant monopoly words. Single high-volume words (face, dating, generator, avatar, ring) are owned by giants with millions of ratings. A vertical app gets zero impressions for them and burns the characters. Go long-tail and specific.
7. Transliteration traps drain non-English budget. English loanwords transliterated into another language (vintage, retro, romantic) have near-zero local search volume. Use native search terms instead (table in references/localization-aso.md).
8. Screenshot caption text is a conversion asset first. Some markets may extract caption text as a secondary discovery signal, but treat captions as primarily for conversion — clear, benefit-led, localized — unless you have current store evidence that captions move discovery in your market. (A June-2025 caption OCR-indexing change is widely reported; if confirmed in your market, captions become a second keyword surface and Apple reportedly OCRs the top/bottom of the shot — but keep this hedge intact.)
9. Verify after every write. App Store Connect can accept a malformed update (HTTP 200) yet store nothing, or you can re-introduce a cross-field conflict by keeping an old field while writing a new one. Always re-run the audit immediately after pushing metadata.

---

Recent platform shifts (dated)

• New-app boost eliminated — Apple removed the artificial first-1–2-week visibility lift for new apps. External traffic (paid/social/PR) from day 1 is now required to seed relevance; you can't coast on a launch bump.
• Custom Product Pages: up to 35 per app, organic-keyword-assignable since 2024 (previously paid Apple Search Ads only) — each CPP can target a different long-tail cluster. Details in references/category-playbooks.md.
• Caption OCR-indexing (June 2025, reported) — see golden rule #8; treat as a dated data point, not a license to keyword-stuff captions.

Running ASO with an LLM — avoid self-contamination

When one model both researches and decides ASO, its own prior conclusions / session memory / "regional flavor" intuitions are the dominant pollution source — it fabricates plausible-but-wrong keywords. Countermeasures:

• Isolate research from decision. Run keyword/feature analysis as an independent pass that is forbidden from reading any prior ASO report (move old ASO_*.md / *Market_Research*.md / .aso/ files out of reach first); let the orchestrating model only do mechanical execution + data passing.
• Never trust model intuition for locale words. Any candidate not validated via iTunes Search (or marked untested after a throttle) must be validated before shipping — never extrapolated. Real failure: a model invented boho/winter/cottage/maple for en-AU/en-CA; iTunes testing showed all were function-mismatches.

---

Platform metadata quick reference

iOS App Store

Field	Limit	Indexed?	Update needs review?	Use for
App Name	30	YES — highest weight	Yes	Brand + #1 keyword
Subtitle	30	YES — high weight	Yes	#2–#3 keywords / benefit
Keywords field	100	YES — medium weight	Yes	All remaining unique terms, comma-separated, no spaces
Description	4,000	NO	Yes	Conversion copy only
Promotional Text	170	NO	No — instant	Seasonal / limited-time messaging
What's New	4,000	NO	Per-version	Update notes
IAP display names	—	YES — low weight	Per-IAP	Bonus keyword coverage

Limits count Unicode codepoints, not bytes — one CJK character = 1, one emoji can be 1–2. Keyword field format: kw1,kw2,kw3 — no space after commas (each space wastes a character).

Google Play

Field	Limit	Indexed?	Use for
Title	30	YES — highest weight	Brand + primary keyword (natural language)
Short Description	80	YES — medium-high	Secondary keyword + benefit
Full Description	4,000	YES — high weight	Primary keyword in 1st sentence, 2–3% density
Developer Name	—	YES — low	Branding
What's New	500	NO	Update notes (shorter than iOS)

Google uses NLP/semantic matching and penalizes unnatural keyword stuffing. Additional Play ranking signals grep can't see in the listing: user-review text (indexed), backlinks to the Play page, and Android Vitals (ANR <0.47%, crash rate <1.09%) — poor vitals directly reduce visibility.

Full field specs, indexing nuances, and per-device visual sizes live in references/metadata-specs.md.

---

Auto-detection (local mode)

When no app ID is given, detect the project first. Look for, in priority order:

Source	Detects	Files
Fastlane iOS	per-locale name, subtitle, keywords, description	fastlane/metadata/<locale>/{name,subtitle,keywords,description,promotional_text}.txt
Fastlane Android	per-locale title, short/full description	fastlane/metadata/android/<locale>/{title,short_description,full_description}.txt
Xcode	bundle ID, app name	*.xcodeproj/project.pbxproj, Info.plist
Gradle	application ID, app name	app/build.gradle, AndroidManifest.xml, res/values/strings.xml

Fastlane metadata is richest (all fields available). Xcode/Gradle give only identifiers — extract the app ID and optionally fetch the live listing.

For iOS shops using App Store Connect directly (no Fastlane), pull current metadata with the asc CLI — see references/app-store-connect-cli.md.

---

Audit orchestration flow

When asked to audit a listing (/aso audit <app-id> or a local project), run this pipeline:

1. Fetch / detect the listing data → structured per-locale metadata.

2. Classify category (gaming, SaaS/productivity, health/fitness, e-commerce, social, fintech, …) to load the right benchmarks and templates from references/category-playbooks.md.

3. Run mechanical checks (these are free and deterministic — see the audit logic in references/keyword-research.md):

   • character budget per field (codepoint count vs limit)
   • cross-field stem overlap (Name+Subtitle vs Keywords)
   • cross-locale duplication (same-language storefront pools)
   • transliteration-trap words per locale
   • keyword field format (no spaces after commas, no app-name repeats)

4. Run analytical passes — keyword coverage, metadata quality, visual assets, reviews/ratings, competitor gap, conversion signals, technical health, localization. For a big listing these are independent and can be dispatched as parallel sub-agents (one per dimension), each returning a scored sub-report.

5. Score a weighted ASO Health Score (0–100):

   Dimension	Weight
   Keyword optimization	20%
   Metadata quality	20%
   Visual assets	15%
   Reviews & ratings	15%
   Competitive position	10%
   Technical health	10%
   Conversion signals	10%

6. Generate two outputs:

   • Audit report — score, platform, category, top issues, per-dimension findings.
   • Action plan — prioritized Critical → High → Medium → Low (severity mapping in references/quality-gates.md).

---

Keyword research — the validation loop

You do NOT need a paid tool (AppTweak / Sensor Tower) to do real keyword research. The free, current stack:

1. iTunes Search API (public, no key) — returns the real top-ranked apps for any term in any storefront. This is how you detect the "category-match ≠ function-match" trap (golden rule #5): look at what the top 5 apps for a candidate keyword actually do, and compare to your app's function.

   curl -s "https://itunes.apple.com/search?term=<KEYWORD>&country=us&entity=software&limit=5" \
     | python3 -c "import json,sys;[print(a['trackName'],'—',a.get('primaryGenreName')) for a in json.load(sys.stdin)['results']]"
   

2. Apple Search Suggestions — Apple's own autocomplete (the strongest App-Store demand signal): search.itunes.apple.com/.../hints?clientApplication=Software&term=<partial> (see references/competitor-intelligence.md).

3. Google Suggest — keyless cross-platform corroboration: https://suggestqueries.google.com/complete/search?client=firefox&q=<term>&hl=<lang>&gl=<country> — data[1] is the completions list; completion-count is the reliable proxy (Google Trends/pytrends is reliably 429-throttled — best-effort only).

4. App Store Connect Analytics — your own actual traffic-driving search terms (the ground truth for what's already working).

Throttle caveat: the iTunes Search API trips 403/429 under parallel load (N sub-agents from one IP). When throttled, mark a candidate untested and validate later — never extrapolate or invent regional words.

Apple Search Ads (ASA) API does NOT expose a public keyword-popularity / search-volume endpoint (verified 2026; the searchPopularity field only exists inside ASA Custom Reports, whose GET has returned 403 since 2026-03-16 as Apple migrates to the Insights API). Do not promise users a volume number from the ASA API — use the free signals above instead, and if they run ASA campaigns, the in-console Search Match / keyword recommendations are the practical popularity proxy.

Full keyword methodology — the three-layer candidate gate, the function-mismatch procedure, the Opportunity Score ranking, the runnable mechanical audit (scripts/aso_audit.py), script-aware tokenization, and the monopoly/giant word lists — is in references/keyword-research.md. Deeper competitor/review research (reviews RSS, ratings histogram, Apple Suggest) is in references/competitor-intelligence.md.

---

Conversion rate optimization

Conversion benchmarks (2025–2026): iOS ~25%, Google Play ~27% average, but category variance is huge (10–115%+). Audit the first impression — everything a user sees before scrolling or tapping "more":

• iOS search result: icon, name, subtitle, rating, first 3 screenshots, Get button.
• Play search result: icon, title, developer, rating, Install button.

Score conversion 0–100 weighting: first-3-screenshots 25%, title clarity 20%, rating strength 20%, social proof 15%, subtitle/short-desc 10%, icon appeal 10%. Psychology levers to evaluate: social proof, authority (awards, Editor's Choice), specificity (concrete numbers beat vague claims), benefit framing (outcomes, not features). Detailed scoring rubric, screenshot narrative arc, and icon rules: references/conversion-and-visuals.md.

---

A/B testing

iOS Product Page Optimization tests visuals only (icon, screenshots, preview video — NOT title/subtitle/keywords/description), max 3 treatments + original, 7–90 days. Google Play Store Listing Experiments also test text (short/full description), up to 5 localized + 1 main, 7-day minimum. Change ONE element per test, make it meaningful, aim for ~1,000+ views/variant and ≥90% confidence; primary metric is install conversion rate; test screenshots first, then icon. Full table, hypothesis template, and roadmap: references/conversion-and-visuals.md.

---

Localization

Don't localize every storefront — prioritize by iOS penetration and spend. Per-locale keyword research, not translation — translating your en-US keywords gives words nobody searches. Exploit the cross-indexed locale matrix (e.g. a US storefront also indexes several other locales' keyword fields) to pack overflow terms for free. Watch for transliteration traps and cultural fit. Market tiers, the cross-index matrix, transliteration tables across 8+ languages, and ASC-unsupported locales: references/localization-aso.md.

---

Compliance — will this get rejected?

Run a policy pass on any metadata you recommend, both your current values and proposed changes. The high-frequency rejection causes:

• Google Play title banned words: #1, best, top, free, new, sale, download now, install now, etc. No emojis, no ALL CAPS.
• Both stores: no competitor brand names in any field (Apple strengthened this in Nov 2025 — no competitor icons/brands/names); no other-platform names ("Android" on iOS); no pricing terms.
• Screenshots: must show actual app UI; no promo text overlays ("#1", "Best", "Sale") on Play.
• Category gates: health apps need disclaimers + no unvalidated sensor measurements; finance apps must complete Google's financial- features declaration (mandatory since Oct 2025); AI apps must disclose third-party AI data sharing (Apple, Nov 2025) and offer in-app reporting of generated content (Google, Jul 2025).

Full policy matrix with guideline references and the complete banned-words list: references/store-policies.md.

Scope note: this skill covers discoverability and conversion metadata, including screenshot framing/rendering (references/screenshot-rendering.md — chrome decision, bezel install, aspect-ratio crop, captions, the scaffold→AI-enhance pipeline). For the binary submission, build upload, and the full pre-submission review checklist, see the companion app-review-preflight skill — don't duplicate that work here.

---

App Store Connect write workflow (asc CLI)

To push optimized metadata to a live iOS listing, use the asc CLI. The two gotchas that silently fail:

• Multi-line fields (description, What's New) must use asc raw PATCH with a JSON body file — passing \n through shell args returns HTTP 200 but stores empty content.
• A FAILED screenshot upload blocks submission ("screenshots still uploading") until you raw DELETE it.

Pull → edit → push → re-audit recipes, plus the exact localizations update, metadata pull/push, screenshot upload, and resource-ID lookup commands: references/app-store-connect-cli.md.

---

Output conventions

• Audit report and Action Plan as separate markdown files; action items grouped Critical/High/Medium/Low with the offending field and the exact recommended value.
• Keyword maps show the proposed per-field strings with live codepoint counts (e.g. Name: "Snap — AI Couple Photos" (24/30)).
• Always state which fields require app review (1–3 days on iOS) vs which are instant (iOS promotional text, all Play text).

Reference files (load on demand)

File	Contents
references/metadata-specs.md	Full iOS + Android field specs, indexing rules, visual-asset sizes per device
references/keyword-research.md	Seed expansion, intent, the function-mismatch detection method, mechanical audit checks, giant/monopoly word lists
references/quality-gates.md	Hard thresholds, Critical→Low severity mapping, density bands, scoring labels
references/localization-aso.md	Market tiers, cross-indexed locale matrix, transliteration + face-swap tables, full 39-locale set, ASC-unsupported locales
references/store-policies.md	Apple + Google policy matrix with guideline refs, banned-words list, category-specific gates
references/category-playbooks.md	Per-category keyword themes, benchmarks, 4-phase roadmap, launch checklist, seasonal calendar, In-App Events + Custom Product Pages, review/rating-prompt tactics
references/conversion-and-visuals.md	Conversion scoring, screenshot narrative, icon rules, A/B test design, launch-velocity tactics
references/screenshot-rendering.md	How to render/frame screenshots: chrome decision, bezel install, aspect-ratio crop, file prep, panoramic, captions/fonts, scaffold→AI-enhance, source-capture QA
references/competitor-intelligence.md	Off-device iTunes/App Store API toolkit: reviews RSS, ratings histogram, Apple Suggest, chart feeds, bundle/developer lookup, storefront/genre IDs
references/app-store-connect-cli.md	asc CLI pull/push recipes + env-var auth / auth doctor / capabilities, raw PATCH for multi-line fields, screenshot upload, pre/post-write verify
scripts/aso_audit.py	Runnable mechanical audit (budget, cross-field stem, CJK substring, cross-locale dup, traps, format); offline JSON or live asc; exits non-zero on ERROR
scripts/itunes_search_check.py	iTunes Search competition check — result-count bands + top-5 + aggregate ratings
scripts/google_signals.py	Google Suggest (+ best-effort Trends) demand corroboration