Every character counts when preparing an iOS application listing for App Store distribution. Exceeding Apple's strict character constraints by even a single character causes immediate validation errors in App Store Connect or API rejection. Formatting mistakes—such as inserting spaces into keyword strings or including unauthorized ranking superlatives—can lead to App Review rejections that delay your product launch.
Furthermore, Apple splits metadata across two distinct underlying resources: App Info Localizations (global app properties like Name and Subtitle) and App Store Version Localizations (version-specific properties like Description, Keywords, and What's New).
Using FlightDeck and your AI coding assistant, you can audit your current store listing, ensure all fields adhere strictly to Apple's length and formatting boundaries, draft optimized App Store Optimization (ASO) copy, and stage compliant updates directly from your development environment.
What You Need
Before auditing or updating App Store metadata:
- An active Apple Developer account with an application record in App Store Connect.
- FlightDeck installed and connected to your Apple Developer account.
- An AI coding assistant (Cursor, Claude Code, Antigravity, Windsurf, or Roo Code) connected to FlightDeck's MCP server. See Connecting Cursor to App Store Connect.
- An unreleased version draft in App Store Connect (required for version-specific fields and App Name/Subtitle changes).
App Store Metadata Field Specifications
The following master reference outlines exact character limits, resource ownership, and editing rules across iOS metadata fields:
| Field Name | Max Character Limit | Target API Resource | Editable Without New Version? | Requirement |
|---|---|---|---|---|
| App Name | 30 characters | appInfoLocalizations (name) |
No (requires version draft) | Required |
| Subtitle | 30 characters | appInfoLocalizations (subtitle) |
No (requires version draft) | Optional (Recommended) |
| Promotional Text | 170 characters | appStoreVersionLocalizations (promotionalText) |
Yes (any time!) | Optional |
| Description | 4,000 characters | appStoreVersionLocalizations (description) |
No (requires version draft) | Required |
| Keywords | 100 characters | appStoreVersionLocalizations (keywords) |
No (requires version draft) | Optional (Essential) |
| What's New | 4,000 characters | appStoreVersionLocalizations (whatsNew) |
No (requires version draft) | Required on updates |
| Support URL | 255 characters | appStoreVersionLocalizations (supportUrl) |
No (requires version draft) | Required |
| Marketing URL | 255 characters | appStoreVersionLocalizations (marketingUrl) |
No (requires version draft) | Optional |
| Privacy Policy URL | 255 characters | appInfoLocalizations (privacyPolicyUrl) |
Yes (any time!) | Required |
Characters vs. Bytes: Official Apple documentation specifies App Store metadata limits strictly in characters (not words or bytes). While basic ASCII characters count as one character each, Apple does not publicly document its internal Unicode normalization algorithm. In practice, non-ASCII characters, combining diacritics, emoji, and zero-width joiner (ZWJ) sequences can produce unexpected validation failures because different client libraries and server-side validation layers measure Unicode code points, UTF-16 code units, and UTF-8 bytes differently (which are distinct, non-equivalent measurements). For tightly constrained fields like App Name (30 characters), Subtitle (30 characters), and Keywords (100 characters), avoid composite emoji or combining characters and verify your strings in a draft release before final submission.
The Two Metadata Resources: App Info vs. Version Localizations
Apple divides store listing metadata across two distinct architectural layers:
┌────────────────────────────────────────────────────────────────────────┐
│ App Store Connect App Record │
├───────────────────────────────────┬────────────────────────────────────┤
│ App Info Localizations │ App Store Version Localizations │
│ (Global App Level) │ (Per-Version Draft Level) │
├───────────────────────────────────┼────────────────────────────────────┤
│ • App Name (30 chars) │ • Description (4,000 chars) │
│ • Subtitle (30 chars) │ • Keywords (100 chars) │
│ • Privacy Policy URL (255 chars) │ • Promotional Text (170 chars) │
│ │ • What's New / Notes (4,000 chars) │
│ │ • Support URL (255 chars) │
│ │ • Marketing URL (255 chars) │
└───────────────────────────────────┴────────────────────────────────────┘
1. App Info Localizations (appInfoLocalizations)
These fields apply to your entire application across all versions:
- In Apple's data model,
appInfoLocalizationsowns the application title and subtitle (appInfoLocalizations(subtitle)). - Changing your App Name or Subtitle requires an active, unreleased app version draft, but the values apply globally once that version passes review and releases.
- Your Privacy Policy URL can be updated at any time without submitting a new application version or binary.
2. App Store Version Localizations (appStoreVersionLocalizations)
These fields belong to a specific marketing version (such as version 1.0.0 or 1.1.0):
- Description, Keywords, and What's New are locked once a version is approved and released to the public. To change them, you must prepare a new version.
- Promotional Text is the sole exception: Apple allows developers to modify Promotional Text at any time on live production apps without submitting a new release candidate or waiting for App Review. Updates reflect on the live storefront within minutes.
Field-by-Field Breakdown and Optimization Rules
1. App Name (Max 30 Characters)
Your App Name is the single most heavily weighted factor in Apple's search algorithm:
- Rules: Must not exceed 30 characters. Apple prohibits misleading generic descriptors, pricing claims, or ranking claims (for example,
"Best Calculator - #1 Free Math App"violates Guideline 2.3.7). - Strategy: Pair your core brand name with 1–2 high-priority keywords if space permits (e.g.,
"FocusPulse: Habit Tracker"= 25 characters).
2. Subtitle (Max 30 Characters)
Appears directly below your App Name throughout the App Store on iOS 11 and later:
- Rules: Max 30 characters. Do not repeat words already used in your App Name; repeating keywords wastes space without increasing ranking weight.
- Strategy: Use a compelling, benefit-focused summary (e.g.,
"Daily Routines & Goal Tracker"= 29 characters).
3. Promotional Text (Max 170 Characters)
Promotional Text appears at the very top of your App Store description, above the fold:
- Superpower: Can be edited at any time in production without submitting a new version or waiting for App Review.
- Strategy: Use this field for time-sensitive announcements, seasonal promotions, press quotes, or limited-time events.
4. Keywords (Max 100 Characters)
The keywords field is private and never visible to users, but it is critical for App Store search ranking:
- Strict Formatting Rules:
- Separate individual terms with a single comma (
,). - DO NOT include spaces after commas. A space consumes 1 character against your 100-character budget without contributing to search matching (
habit,tracker,goals= 18 chars;habit, tracker, goals= 20 chars). - Do not repeat keywords that already appear in your App Name or Subtitle. Apple's search index combines your title, subtitle, and keyword field automatically.
- Do not use competitor brand names, trademarked terms, or offensive words.
- Use singular nouns; Apple's search engine automatically covers most plural variations.
- Example Valid Keyword String:
habit,routines,checklist,streaks,calendar,focus,productivity,planner(70 characters).
5. Description (Max 4,000 Characters)
A detailed overview of your application's features and functionality:
- Search Note: Unlike Google Play, Apple's App Store search algorithm does not index the text of your Description for keyword search. Its purpose is conversion, user education, and editorial review.
- Formatting: The first three lines (approximately 255 characters) are visible before users tap the "more" button. Place your most compelling hook and core value proposition in the first sentence.
6. What's New / Release Notes (Max 4,000 Characters)
Describes the changes, bug fixes, and improvements included in this release:
- Requirement: Required for all updates (versions after 1.0.0). Not required for your initial 1.0.0 launch.
- Best Practice: Avoid generic phrases like "Bug fixes and performance improvements". Reviewers and users appreciate specific, conversational release notes highlighting new features and resolved community issues.
Auditing and Updating Metadata with Your AI Assistant
With FlightDeck connected to your AI assistant, managing App Store metadata requires no JSON editing or manual API requests.
flowchart TD
A["Developer Prompt in AI Chat"] --> B["AI Assistant Queries Metadata via FlightDeck"]
B --> C["Assistant Audits Character Counts & Formatting"]
C --> D["Assistant Stages Proposed Update"]
D --> E["FlightDeck Desktop Approval Center Shows Staged Diff"]
E --> F["Developer Reviews & Clicks Approve"]
F --> G["Changes Committed to App Store Connect"]
Step 1: Prompt Your AI Assistant to Audit Current Metadata
Ask your assistant to inspect your active draft metadata and verify character counts:
Inspect the App Store metadata for [App Name] in App Store Connect for the English (en-US) localization. Check our App Name, Subtitle, Keywords, Description, and Promotional Text. Report the exact character count of each field, flag any that exceed Apple's limits, and identify any formatting issues like spaces after commas in keywords.
What Your Assistant Does Behind the Scenes:
- It queries App Store Connect to retrieve active draft localizations across both
appInfoLocalizationsandappStoreVersionLocalizations. - It measures the character length of each string.
- It audits your keyword string to identify redundant terms, spaces after commas, and character count headroom.
- It presents an executive summary with optimization recommendations.
Step 2: Prompt Your Assistant to Stage Optimized Metadata
Once you agree on the revised wording, instruct your assistant to stage the update:
Please update our English (en-US) draft metadata for [App Name]:
- Subtitle: "Daily Routines & Goal Tracker"
- Keywords: "habit,routines,checklist,streaks,calendar,focus,planner"
- Promotional Text: "Special launch update: Track daily habits and build streaks with interactive widgets!"
Stage these changes in FlightDeck so I can inspect them before committing.
What Your Assistant Does Behind the Scenes:
- The assistant stages global properties using
app_info_localization_update(for Subtitle or Name). - It stages version-specific properties using
app_store_version_localization_update(for Keywords, Promotional Text, Description, or What's New). - FlightDeck halts execution and opens a confirmation card in the Desktop Approval Center.
FlightDeck Desktop Approval Center:
Because updating metadata modifies your public store listing, FlightDeck presents the changes for verification:
Illustrative representation of the FlightDeck Approval Center sheet:
┌────────────────────────────────────────────────────────────────────────┐
│ FlightDeck Desktop Approval Center │
├────────────────────────────────────────────────────────────────────────┤
│ Operation: Update App Store Metadata │
│ App: FocusPulse (ID: 6471234567) | Locale: en-US │
│ Version: 1.2.0 (Draft) │
│ │
│ Subtitle: │
│ [-] "Build habits and track goals" (28 chars) │
│ [+] "Daily Routines & Goal Tracker" (29 chars) │
│ │
│ Keywords: │
│ [+] "habit,routines,checklist,streaks,calendar,focus,planner" (56 ch) │
│ │
│ Promotional Text: │
│ [+] "Special launch update: Track daily habits and build streaks..." │
│ │
│ [ Reject ] [ Approve & Commit ] │
└────────────────────────────────────────────────────────────────────────┘
Inspect the proposed text and character counts, then click Approve & Commit. FlightDeck dispatches the updates directly to App Store Connect.
Verify Success: Read-Back Audit Prompt
After approving the changes, instruct your AI assistant to read back the live remote state from App Store Connect:
Query App Store Connect for [App Name] and read back the updated English (en-US) metadata. Confirm that the Subtitle, Keywords, and Promotional Text now match our staged values and remain strictly within Apple's character limits.
Your assistant retrieves the newly committed records and confirms that the updated copy is saved in Apple's database.
Common Rejection Triggers to Avoid
- Guideline 2.3.7 (Inaccurate Metadata): Including terms like "Free", "Discount", "#1 Best", or competitor trademarks in your App Name or Subtitle.
- Guideline 2.3.8 (Keyword Spamming): Inserting unrelated popular search terms (e.g., adding "Minecraft" or "Instagram" to a productivity app's keywords).
- Broken Support or Privacy URLs: Reviewers verify every external link. Ensure your support site and privacy policy return an HTTP 200 status code before submitting.
- Keyword Character Overflow: Even 101 characters in the keywords field will trigger an immediate API rejection. Always validate string lengths before sending.
Related Guides
- Automating App Store Multi-Language Localization and What's New with AI
- Bulk Uploading App Store Screenshots via MCP: Automating Display Sets
- Top App Store Rejections for Vibe-Coded Apps
- Pre-Flight App Store Submission Readiness Check
- Resolving Guideline 2.1 Rejections: Broken Links, Incomplete Features, and Demo Credentials