---
name: app-store-optimization
description: "App Store Optimization (ASO) for ranking and conversion: keyword research; app name, subtitle and 100-byte keyword field; description and promotional text that convert; screenshot captions and slot order; Custom Product Pages and their assigned search keywords; In-App Events; Product Page Optimization A/B tests; localized metadata; ratings, review replies, and when to call RequestReviewAction or AppStore.requestReview. Use when improving App Store ranking or conversion, or deciding what belongs to ASO versus App Store review, privacy and ATT, or StoreKit implementation."
metadata:
  source: multi-agent-pipeline
---

# App Store Optimization

This skill decides what to say on the product page and where: which keywords,
how the copy converts, which custom pages and events to run. Compliance
questions such as field limits enforced at submission, screenshot device sizes
and rejection risks belong to `app-store-review`.

## Contents

- [Overview](#overview)
- [Name and subtitle](#name-and-subtitle)
- [Keyword field](#keyword-field)
- [Description](#description)
- [Promotional text](#promotional-text)
- [Screenshots and previews](#screenshots-and-previews)
- [Asking for reviews in the app](#asking-for-reviews-in-the-app)
- [Custom pages](#custom-product-pages)
- [Events](#in-app-events)
- [Page tests](#product-page-optimization)
- [Ratings and reviews](#ratings-and-reviews)
- [Localizing the listing](#localized-metadata-optimization)
- [Mistakes to catch](#mistakes-to-catch)
- [Review checklist](#review-checklist)
- [References](#references)

## Overview

ASO has two goals that use different parts of the page:

- **Visibility**: appearing for relevant searches. Surfaces: app name,
  subtitle, keyword field, primary category, localizations, ratings and
  reviews, In-App Events when they fit, and custom pages that carry their own
  search keywords.
- **Conversion**: turning a page view into a download. Surfaces: screenshots,
  app previews, description, promotional text, the message on each Custom
  Product Page, Product Page Optimization tests, and making sure public claims
  and screenshots match the real app.

Use this skill for questions about discoverability, keywords, download rate or
any page element that moves either goal. It assumes the listing already obeys
`app-store-review` rules. Every plan or division of work names the two goals
separately.

**Who owns what**

| Area | Owner |
|---|---|
| What the listing says and to whom, which keywords match which message, screenshots, promotional text, custom pages, page tests, per-market listings, how events are pitched, rating strategy, the moment to request a review | This skill |
| Review compliance, PrivacyInfo.xcprivacy, ATT prompt wording, submission guardrails | `app-store-review` |
| Purchase code, subscription paywalls, entitlement checks, monetization mechanics | `storekit` |

**A complete plan covers**

- Visibility: the name and subtitle, the keyword field, the primary category, localizations,
  ratings and reviews, In-App Events if there is real timed content, Custom
  Product Pages and their assigned search keywords.
- Conversion: the description's opening lines, the first screenshots or the
  preview, promotional text, message fit on each custom page, a test plan, and
  a check that claims and screenshots are accurate.
- Experiment: one hypothesis, at most three treatments, the localizations in
  the test, the metric, and the rule for calling a winner.
- Review prompts: the positive moment that triggers them, the moments that
  never do, and a note that StoreKit decides whether anything appears.

Always state explicitly: popular but irrelevant keywords are rejected; the
custom page allowance is 70 per app; a test has up to three treatments; In-App
Events and ratings are ASO work.

Every App Store Connect number in this skill (field lengths, the 70-page
allowance, three treatments, the 90-day test limit, event media sizes, the
review-prompt cap) is as Apple's documentation stated it at the time of
writing. Apple changes these limits, so check App Store Connect Help before
quoting one as current.

## Name and subtitle

Search indexes both the name (30 characters) and the subtitle (30 characters),
so together they offer 60 indexed characters.

| Situation | Pattern |
|---|---|
| Brand already known | `Brand - Keyword` |
| New app competing on category terms | `Keyword - Brand` |
| Brand already contains a relevant word | A blended name |

- A word used in the name is wasted if repeated in the subtitle.
- The strongest keyword goes first in the field that still has spare room.
- Filler such as "the", "best" or "app" earns nothing in search.
- The subtitle states what the app does for the user, not a slogan.

## Keyword field

The keyword field holds 100 bytes of comma-separated terms. For Latin script
that is 100 characters; scripts such as Japanese, Chinese or Korean use more
bytes per character, so they fit fewer. Formatting rules at submission live in
`app-store-review`.

**Finding candidates**

1. Audit the 5 to 10 strongest apps in the category: which words appear in
   their names, subtitles and descriptions?
2. Map the category for related terms those competitors leave out.
3. Run Apple Ads discovery campaigns to see real high-intent queries with
   impression and tap data.
4. Revisit the set with every release using Apple Ads, App Analytics
   impressions and conversion data.

**Ranking candidates.** Relevance carries the most weight, then search volume,
then competition. Relevance wins every tie: an unrelated high-volume term
brings impressions that never convert. Think about what the searcher intends
first and how well the term fits the metadata second. Treat the primary
category as part of the keyword budget and never spend field space on it.

**Packing the field**

- Drop anything already in the name or subtitle.
- Keep one grammatical number per word; singular and plural of the same word
  count as duplicates.
- Leave out the category name; the primary category already counts.
- No space after commas; spaces use up bytes.
- Abbreviations and common misspellings are fine when people really type them.
- Spend bytes on high-intent, clearly relevant terms, not loosely descriptive
  ones.

Scoring, slot allocation and seasonal rotation are in the
[keyword research reference](references/keyword-research-methodology.md).

## Description

Search relevance is computed from the name, the subtitle, the keyword field and
the primary category, together with how users behave: downloads, ratings,
reviews. The description exists
to convert, so do not load it with keywords.

1. **Opening lines.** Only the first one to three lines show before "more". Put
   the strongest benefit or differentiator there; nothing else on the page
   matters as much.
2. **Features.** Four to six short lines starting with the Unicode bullet character (U+2022),
   because the store does not render Markdown. Describe outcomes, not internals.
3. **Proof.** One or two lines of awards, press quotes, user milestones or
   ratings.
4. **Close.** A short line naming the benefit and inviting the download.

The store shows plain text only: no Markdown, HTML or rich formatting, so use
Unicode characters for structure. Keep paragraphs short and separated by blank
lines; a wall of text loses readers. Each locale gets its own version that
keeps the structure rather than the literal wording.

## Promotional text

Promotional text sits on top of the description, holds up to 170 characters,
and can be edited whenever you like without shipping a build. Refresh it when a
feature ships, for a season, after an award or press mention, during a sale,
and while an In-App Event runs. It
should never sit unchanged across releases; when nothing is timely, cycle
through the strongest selling points.

## Screenshots and previews

Most visitors look at the first three screenshots and no further.

- Open with the main value proposition.
- Keep onboarding, splash and loading screens out of those three slots.
- Give each of the three a different benefit.

**Captions** describe what the user gets, not the name of the screen:
"Never miss a deadline" rather than "Calendar View". Keep a two-to-five-word
headline above the screenshot and at most one short line below, and start with
a verb such as Plan, Share, Find or Build.

**Order**

| Slot | Content |
|---|---|
| 1 | Main value proposition |
| 2 | The key differentiator |
| 3 | The next strongest feature |
| 4 and later | Supporting features, social proof, edge cases |

An app preview video, when present, takes the first position. For viewers with
autoplay off, its poster frame is all they see, so pick a frame that could stand
alone as a screenshot. Device sizes and other screenshot requirements are in
`app-store-review`.

## Asking for reviews in the app

Use the SwiftUI environment value `RequestReviewAction` or, from UIKit,
`AppStore.requestReview(in:)`. The full StoreKit surface is covered in
`storekit`.

```swift
import StoreKit
import SwiftUI

struct TripSummaryView: View {
    @Environment(\.requestReview) private var requestReview
    let completedTrips: Int

    var body: some View {
        TripSummaryContent()
            .onAppear {
                if completedTrips == 5 { requestReview() }
            }
    }
}
```

- The system shows the prompt at most three times in 365 days per device for
  someone who has not rated the app.
- Calling the API is a request; StoreKit decides whether anything appears.
- Development builds always show it; TestFlight builds never do.
- Good moments: a meaningful task just finished, a milestone or streak, a
  visible success, several active sessions.
- Bad moments: the very first launch, the onboarding flow, any error or crash,
  a purchase that failed, or directly after a button tap.
- Do not put a "Do you like this app?" dialog in front of the system prompt.
  Apple discourages intercepting it and may reject apps that do.

For a permanent "Write a review" row in settings, open
`https://apps.apple.com/app/id{APP_ID}?action=write-review`. It goes straight
to the review sheet and does not count against the three-per-year limit.

## Custom Product Pages

Each app gets an allowance of 70 Custom Product Pages. A page may swap in its
own screenshots, preview videos and promotional text, and carry its own search
keywords.

- A recommendation to use them always says two things: the allowance is 70
  pages, and keywords assigned to a page let it surface in search. Map every page to an
  audience, a message, a keyword or ad intent, and a measurement plan.
- Typical uses: ad groups in Apple Ads, social campaigns, landings for one
  feature, seasonal pushes, and any path that needs a matching first screenshot
  and promotional text.
- Each page has its own App Store URL for ads, deep links and websites.
- An approved page can surface in search for its assigned keywords; those are
  chosen from the keywords of the most recently approved app version.
- Each page can be localized on its own.
- Create them in App Store Connect on the Custom Product Pages tab, with
  descriptive internal names such as `Search-TrailMaps` or
  `Social-SummerLaunch`.

URL format, channel mapping and maintenance are in the
[page variants reference](references/product-page-variants.md).

## In-App Events

Events are shown in search, on Today and in recommendations tailored to
each user. They raise visibility while they run and can bring lapsed
users back.

- Badges (seven): Challenge, Competition, Live Event, Major Update, New
  Season, Premiere, Special Event. Pick the one that matches what actually happens in
  the app, and never create an event without real time-bound content.
- Text limits in characters: 30 for the name, 50 for the short description,
  120 for the long one.
- Media: an event card image or video at 16:9 (1920 x 1080) and an event
  details page image or video at 9:16 (1080 x 1920).
- Time them with feature releases, seasonal moments and content drops.
- Write the name and short description for someone scanning search results;
  they appear on the event cards in Search and Today.
- The card is shown on the product page as well, and a well-timed card lifts
  tap-through.
- Line events up so a new one starts as the previous one ends, keeping a card
  in search at all times.

## Product Page Optimization

Product Page Optimization is the built-in App Store Connect A/B test for the
default product page.

- Testable: the app icon (using alternate icons), screenshots (order, content,
  captions) and the preview video.
- Up to three treatments run against the original page.
- Plan at least seven days so every weekday is included, and longer for apps
  with little traffic, until the result is significant.
- Keep a single hypothesis per test, even when using all three treatments.
- Choose which localizations take part; all supported ones are selected by
  default.
- The longest a test runs is 90 days; you can end it sooner.
- App Analytics shows results once the test has been credited with five or
  more first-time downloads.
- Any test you propose spells out the hypothesis, its (at most three)
  treatments, which localizations take part, the metric, and how a winner is
  declared.
- Decide on the change in conversion rate from impressions to downloads, never
  on download totals. App Store Connect shows each variant's conversion rate,
  its lift and a confidence level; require at least 90% before accepting a
  "Performing Better" or "Performing Worse" label.
- Once a winner is applied, pause testing long enough for a fresh baseline.

## Ratings and reviews

Star ratings and written reviews are visible on the product page and in
search, and they move both ranking and conversion.

- Earn more recent positive reviews: prompt after successes and answer
  complaints constructively.
- Answer critical reviews from App Store Connect. A calm, specific reply
  improves how the app looks even when the rating does not change: acknowledge
  the problem, say what is fixed or in progress, keep the tone neutral.
- Read reviews as research into what users want, what frustrates them and the
  words they use, then feed that into metadata and captions.
- Submitting a new version offers the option of resetting the summary rating. Do it only
  when the shown rating is far below current quality after major fixes. Keep a
  good rating that reflects the app fairly, skip the reset for routine fixes, and after
  a risky redesign wait until it has settled.

## Localized Metadata Optimization

A localized listing is a separate job from translating the app's screens.
Keywords, descriptions and captions are researched and written per market.

- Research keywords in each market. The term people use to find a photo editor
  in Japanese is not a word-for-word translation of the English one.
- Rewrite the description per locale, adapting opening lines, features, proof
  and close to local expectations.
- Localize every surface (description, keywords, previews, screenshots), and do
  not count on literal translations or on one locale's keywords being indexed
  elsewhere.
- Caption screenshots in the market's language; native captions convert better
  than English ones.
- Localizing strings inside the app (String Catalogs, `FormatStyle`,
  right-to-left layout) is covered by `ios-localization`.

## Mistakes to catch

- Words from the name, subtitle or category repeated in the keyword field.
- Captions that name features instead of promising benefits.
- Keywords translated instead of researched per market.
- Review requests fired during onboarding or after an error, crash or failed
  purchase.
- Weak first three screenshots, or onboarding and splash screens in them.
- Promotional text that never changes between releases or campaigns.
- Tests stopped too early, run without enough traffic, or mixing hypotheses.
- A space typed after each comma in the keyword field.
- Every Custom Product Page using the same assets.
- Negative reviews left unanswered and unread.

## Review checklist

- [ ] The name pairs the brand with a high-value keyword, and the subtitle
      repeats none of its words.
- [ ] The subtitle states the main value within 30 characters.
- [ ] The keyword field uses its full 100 bytes, has no spaces after commas, no
      words from the name or subtitle, and one form per word.
- [ ] The description follows opening, features, proof, close, and its first
      three lines work before the fold.
- [ ] Promotional text reflects the latest release or event.
- [ ] The first three screenshots show the strongest screens with benefit
      captions.
- [ ] Any preview video shows the core feature within its first five seconds.
- [ ] `requestReview()` follows a positive moment, never first launch or an
      error.
- [ ] Each major acquisition channel has a Custom Product Page with its own
      screenshots.
- [ ] In-App Events are planned for upcoming launches, seasons and releases.
- [ ] Every supported locale has metadata based on its own keyword research.
- [ ] Before submitting, every metadata field clears the `app-store-review`
      checklist.

## References

- [Keyword research](references/keyword-research-methodology.md):
  what search indexes, the research process, scoring, slot allocation, seasonal
  rotation, before and after examples.
- [Page variants](references/product-page-variants.md): custom
  page setup and channel mapping, test patterns and limits, In-App
  Event configuration, caption writing.