/apple-aso

name: apple-aso
user-invocable: true
description: Optimize Apple App Store metadata in store.config.json for ASO (App Store Optimization). Use when working with store.config.json, App Store keywords, titles, subtitles, descriptions, or localizing app metadata. Helps maximize app visibility and downloads.

Apple ASO (App Store Optimization)

Optimize App Store metadata following Apple's guidelines and ASO best practices to maximize visibility and downloads.

When to Use

• Creating or editing `store.config.json`
• Optimizing App Store keywords
• Localizing app metadata for new markets
• Reviewing existing metadata for ASO issues
• Adding new language localizations

Character Limits

| Field | Limit | Ranking Weight | Indexed | |-------|-------|----------------|---------| | **Title** | 30 chars | Highest | Yes | | **Subtitle** | 30 chars | 2nd highest | Yes | | **Keywords** | 100 chars | 3rd (same as subtitle) | Yes | | **Description** | 4,000 chars | None | No | | **Promo Text** | 170 chars | None | No | | **Release Notes** | 4,000 chars | None | No |

Keyword Field Rules

Format

keyword1,keyword2,multi word phrase,keyword3

**Critical formatting:**

• Comma-separated with NO spaces after commas (saves characters)
• Spaces allowed within multi-word phrases
• 100 characters total

Must Follow

1. **Never duplicate words from title/subtitle** - Apple indexes them automatically 2. **Use single words when possible** - Apple creates combinations automatically 3. **No plurals** if you have the singular form 4. **No special characters** - `@`, `#`, `-` are replaced with spaces 5. **No generic terms** - avoid "app", "game", "free", "best", "new" 6. **No competitor names or trademarks** 7. **No category names** - already indexed from category selection

Should Include

• Synonyms not in title/subtitle
• Alternate spellings (with/without accents)
• Related concepts and features
• Long-tail niche terms
• Regional variations
• Action verbs users search for

Localization Best Practices

Apple App Store Language Codes

| Language | Code | | Language | Code | |----------|------|-|----------|------| | English (US) | `en-US` | | German | `de-DE` | | English (UK) | `en-GB` | | French (France) | `fr-FR` | | English (AU) | `en-AU` | | French (Canada) | `fr-CA` | | Spanish (Spain) | `es-ES` | | Portuguese (Brazil) | `pt-BR` | | Spanish (Mexico) | `es-MX` | | Portuguese (Portugal) | `pt-PT` | | Italian | `it` | | Dutch | `nl-NL` | | Japanese | `ja` | | Russian | `ru` | | Korean | `ko` | | Chinese Simplified | `zh-Hans` | | Arabic | `ar-SA` | | Chinese Traditional | `zh-Hant` |

Localization Rules

1. **Don't just translate** - Research native search terms 2. **Include English keywords** in non-English locales (users often search in English) 3. **Remove diacritics** for keywords (users skip accents when typing) 4. **Add regional terms** - Different countries use different words 5. **Consider cross-localization** - Apple indexes multiple locales per territory

Cross-Localization (Free Extra Keywords)

Apple indexes keywords from multiple locales per territory:

• **US**: English (US) + Spanish (Mexico)
• **UK**: English (UK) + English (US)
• **Canada**: English (Canada) + French (Canada)
• **Australia**: English (AU) + English (UK)

This effectively gives you 200 characters in some markets.

Optimization Workflow

Step 1: Analyze Current Metadata

Check for these issues:

• [ ] Keywords duplicating title/subtitle words
• [ ] Redundant synonyms (e.g., "kids" and "children")
• [ ] Generic terms that waste space
• [ ] Missing regional variants
• [ ] Unused character space

Step 2: Research Keywords

Consider:

• **Relevance**: Does it describe your app?
• **Volume**: Are people searching for it?
• **Competition**: Can you realistically rank?

Step 3: Optimize Keywords

1. Remove all duplicates from title/subtitle 2. Remove plurals if singular exists 3. Add action verbs users search for 4. Add regional/cultural variants 5. Fill remaining space with related terms 6. Remove diacritics for better matching

Step 4: Validate

• [ ] Title ≤ 30 characters
• [ ] Subtitle ≤ 30 characters
• [ ] Keywords ≤ 100 characters (count with no spaces after commas)
• [ ] No duplicates across fields
• [ ] No prohibited terms

Example: Before & After

Before (Poor ASO)

{
  "title": "Call Santa Claus Now",
  "subtitle": "Magical Santa Voice Calls",
  "keywords": ["santa", "call santa", "santa claus", "voice call", "kids", "children"]
}

**Issues:**

• "santa", "call santa", "santa claus" duplicate title
• "voice call" duplicates subtitle
• "kids" and "children" are synonyms

After (Optimized)

{
  "title": "Call Santa Claus Now",
  "subtitle": "Magical Santa Voice Calls",
  "keywords": "christmas,xmas,holiday,north pole,father christmas,talk,phone,festive,rudolph,elves,family"
}

**Improvements:**

• No duplicates from title/subtitle
• Regional variant (father christmas for UK)
• Related terms (rudolph, elves, north pole)
• Alternate spellings (xmas)
• Action verb (talk)

store.config.json Schema

{
  "configVersion": 0,
  "apple": {
    "info": {
      "en-US": {
        "title": "App Name (max 30 chars)",
        "subtitle": "Value proposition (max 30 chars)",
        "description": "Full description (max 4000 chars)",
        "keywords": "comma,separated,no spaces,after commas",
        "releaseNotes": "What's new in this version",
        "promoText": "Short promotional text (max 170 chars)",
        "privacyPolicyUrl": "https://example.com/privacy",
        "supportUrl": "https://example.com/support",
        "marketingUrl": "https://example.com"
      }
    },
    "categories": ["PRIMARY_CATEGORY", "SECONDARY_CATEGORY"]
  }
}

Common Mistakes to Avoid

1. **Duplicating keywords across fields** - Wastes precious character space 2. **Direct translation** - Doesn't account for local search behavior 3. **Keyword stuffin