vabole/apple-aso

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 stuffing in title - Hurts readability and conversion
4. Ignoring subtitle - Second most important ranking factor
5. Using spaces after commas - Wastes ~10% of keyword space
6. Frequent changes - Wait 3-4 weeks between keyword updates
7. Including app/game - Already indexed from category

Resources

• Apple Developer: App Store Search
• EAS Metadata Schema
• Project guidelines: docs/aso-guidelines.md

Commands

# Push metadata to App Store
eas metadata:push

# Pull current metadata from App Store
eas metadata:pull

# Validate metadata locally
# (Check JSON syntax and character limits)