1# App Store Metadata
2 
3Manage App Store metadata and optimize for ASO using EAS Metadata.
4 
5## What is EAS Metadata?
6 
7EAS Metadata automates App Store presence management from the command line using a `store.config.json` file instead of manually filling forms in App Store Connect. It includes built-in validation to catch common rejection pitfalls.
8 
9**Current Status:** Preview, Apple App Store only.
10 
11## Getting Started
12 
13### Pull Existing Metadata
14 
15If your app is already published, pull current metadata:
16 
17```bash
18eas metadata:pull
19```
20 
21This creates `store.config.json` with your current App Store configuration.
22 
23### Push Metadata Updates
24 
25After editing your config, push changes:
26 
27```bash
28eas metadata:push
29```
30 
31**Important:** You must submit a binary via `eas submit` before pushing metadata for new apps.
32 
33## Configuration File
34 
35Create `store.config.json` at your project root:
36 
37```json
38{
39  "configVersion": 0,
40  "apple": {
41    "copyright": "2025 Your Company",
42    "categories": ["UTILITIES", "PRODUCTIVITY"],
43    "info": {
44      "en-US": {
45        "title": "App Name",
46        "subtitle": "Your compelling tagline",
47        "description": "Full app description...",
48        "keywords": ["keyword1", "keyword2", "keyword3"],
49        "releaseNotes": "What's new in this version...",
50        "promoText": "Limited time offer!",
51        "privacyPolicyUrl": "https://example.com/privacy",
52        "supportUrl": "https://example.com/support",
53        "marketingUrl": "https://example.com"
54      }
55    },
56    "advisory": {
57      "alcoholTobaccoOrDrugUseOrReferences": "NONE",
58      "gamblingSimulated": "NONE",
59      "medicalOrTreatmentInformation": "NONE",
60      "profanityOrCrudeHumor": "NONE",
61      "sexualContentGraphicAndNudity": "NONE",
62      "sexualContentOrNudity": "NONE",
63      "horrorOrFearThemes": "NONE",
64      "matureOrSuggestiveThemes": "NONE",
65      "violenceCartoonOrFantasy": "NONE",
66      "violenceRealistic": "NONE",
67      "violenceRealisticProlongedGraphicOrSadistic": "NONE",
68      "contests": "NONE",
69      "gambling": false,
70      "unrestrictedWebAccess": false,
71      "seventeenPlus": false
72    },
73    "release": {
74      "automaticRelease": true,
75      "phasedRelease": true
76    },
77    "review": {
78      "firstName": "John",
79      "lastName": "Doe",
80      "email": "[email protected]",
81      "phone": "+1 555-123-4567",
82      "notes": "Demo account: [email protected] / password123"
83    }
84  }
85}
86```
87 
88## App Store Optimization (ASO)
89 
90### Title Optimization (30 characters max)
91 
92The title is the most important ranking factor. Include your brand name and 1-2 strongest keywords.
93 
94```json
95{
96  "title": "Budgetly - Money Tracker"
97}
98```
99 
100**Best Practices:**
101 
102- Brand name first for recognition
103- Include highest-volume keyword
104- Avoid generic words like "app" or "the"
105- Title keywords boost rankings by ~10%
106 
107### Subtitle Optimization (30 characters max)
108 
109The subtitle appears below your title in search results. Use it for your unique value proposition.
110 
111```json
112{
113  "subtitle": "Smart Expense & Budget Planner"
114}
115```
116 
117**Best Practices:**
118 
119- Don't duplicate keywords from title (Apple counts each word once)
120- Highlight your main differentiator
121- Include secondary high-value keywords
122- Focus on benefits, not features
123 
124### Keywords Field (100 characters max)
125 
126Hidden from users but crucial for discoverability. Use comma-separated keywords without spaces after commas.
127 
128```json
129{
130  "keywords": [
131    "finance,budget,expense,money,tracker,savings,bills,income,spending,wallet,personal,weekly,monthly"
132  ]
133}
134```
135 
136**Best Practices:**
137 
138- Use all 100 characters
139- Separate with commas only (no spaces)
140- No duplicates from title/subtitle
141- Include singular forms (Apple handles plurals)
142- Add synonyms and alternate spellings
143- Include competitor brand names (carefully)
144- Use digits instead of spelled numbers ("5" not "five")
145- Skip articles and prepositions
146 
147### Description Optimization
148 
149The iOS description is NOT indexed for search but critical for conversion. Focus on convincing users to download.
150 
151```json
152{
153  "description": "Take control of your finances with Budgetly, the intuitive money management app trusted by over 1 million users.\n\nKEY FEATURES:\n• Smart budget tracking - Set limits and watch your progress\n• Expense categorization - Know exactly where your money goes\n• Bill reminders - Never miss a payment\n• Beautiful charts - Visualize your financial health\n• Bank sync - Connect 10,000+ institutions\n• Cloud backup - Your data, always safe\n\nWHY BUDGETLY?\nUnlike complex spreadsheets or basic calculators, Budgetly learns your spending habits and provides personalized insights. Our users save an average of $300/month within 3 months.\n\nPRIVACY FIRST\nYour financial data is encrypted end-to-end. We never sell your information.\n\nDownload Budgetly today and start your journey to financial freedom!"
154}
155```
156 
157**Best Practices:**
158 
159- Front-load the first 3 lines (visible before "more")
160- Use bullet points for features
161- Include social proof (user counts, ratings, awards)
162- Add a clear call-to-action
163- Mention privacy/security for sensitive apps
164- Update with each release
165 
166### Release Notes
167 
168Shown to existing users deciding whether to update.
169 
170```json
171{
172  "releaseNotes": "Version 2.5 brings exciting improvements:\n\n• NEW: Dark mode support\n• NEW: Widget for home screen\n• IMPROVED: 50% faster sync\n• FIXED: Notification timing issues\n\nLove Budgetly? Please leave a review!"
173}
174```
175 
176### Promo Text (170 characters max)
177 
178Appears above description; can be updated without new binary. Great for time-sensitive promotions.
179 
180```json
181{
182  "promoText": "🎉 New Year Special: Premium features free for 30 days! Start 2025 with better finances."
183}
184```
185 
186## Categories
187 
188Primary category is most important for browsing and rankings.
189 
190```json
191{
192  "categories": ["FINANCE", "PRODUCTIVITY"]
193}
194```
195 
196**Available Categories:**
197 
198- BOOKS, BUSINESS, DEVELOPER_TOOLS, EDUCATION
199- ENTERTAINMENT, FINANCE, FOOD_AND_DRINK
200- GAMES (with subcategories), GRAPHICS_AND_DESIGN
201- HEALTH_AND_FITNESS, KIDS (age-gated)
202- LIFESTYLE, MAGAZINES_AND_NEWSPAPERS
203- MEDICAL, MUSIC, NAVIGATION, NEWS
204- PHOTO_AND_VIDEO, PRODUCTIVITY, REFERENCE
205- SHOPPING, SOCIAL_NETWORKING, SPORTS
206- STICKERS (with subcategories), TRAVEL
207- UTILITIES, WEATHER
208 
209## Localization
210 
211Localize metadata for each target market. Keywords should be researched per locale—direct translations often miss regional search terms.
212 
213```json
214{
215  "info": {
216    "en-US": {
217      "title": "Budgetly - Money Tracker",
218      "subtitle": "Smart Expense Planner",
219      "keywords": ["budget,finance,money,expense,tracker"]
220    },
221    "es-ES": {
222      "title": "Budgetly - Control de Gastos",
223      "subtitle": "Planificador de Presupuesto",
224      "keywords": ["presupuesto,finanzas,dinero,gastos,ahorro"]
225    },
226    "ja": {
227      "title": "Budgetly - 家計簿アプリ",
228      "subtitle": "簡単支出管理",
229      "keywords": ["家計簿,支出,予算,節約,お金"]
230    },
231    "de-DE": {
232      "title": "Budgetly - Haushaltsbuch",
233      "subtitle": "Ausgaben Verwalten",
234      "keywords": ["budget,finanzen,geld,ausgaben,sparen"]
235    }
236  }
237}
238```
239 
240**Supported Locales:**
241`ar-SA`, `ca`, `cs`, `da`, `de-DE`, `el`, `en-AU`, `en-CA`, `en-GB`, `en-US`, `es-ES`, `es-MX`, `fi`, `fr-CA`, `fr-FR`, `he`, `hi`, `hr`, `hu`, `id`, `it`, `ja`, `ko`, `ms`, `nl-NL`, `no`, `pl`, `pt-BR`, `pt-PT`, `ro`, `ru`, `sk`, `sv`, `th`, `tr`, `uk`, `vi`, `zh-Hans`, `zh-Hant`
242 
243## Dynamic Configuration
244 
245Use JavaScript for dynamic values like copyright year or fetched translations.
246 
247### Basic Dynamic Config
248 
249```js
250// store.config.js
251const baseConfig = require("./store.config.json");
252 
253const year = new Date().getFullYear();
254 
255module.exports = {
256  ...baseConfig,
257  apple: {
258    ...baseConfig.apple,
259    copyright: `${year} Your Company, Inc.`,
260  },
261};
262```
263 
264### Async Configuration (External Localization)
265 
266```js
267// store.config.js
268module.exports = async () => {
269  const baseConfig = require("./store.config.json");
270 
271  // Fetch translations from CMS/localization service
272  const translations = await fetch(
273    "https://api.example.com/app-store-copy"
274  ).then((r) => r.json());
275 
276  return {
277    ...baseConfig,
278    apple: {
279      ...baseConfig.apple,
280      info: translations,
281    },
282  };
283};
284```
285 
286### Environment-Based Config
287 
288```js
289// store.config.js
290const baseConfig = require("./store.config.json");
291 
292const isProduction = process.env.EAS_BUILD_PROFILE === "production";
293 
294module.exports = {
295  ...baseConfig,
296  apple: {
297    ...baseConfig.apple,
298    info: {
299      "en-US": {
300        ...baseConfig.apple.info["en-US"],
301        promoText: isProduction
302          ? "Download now and get started!"
303          : "[BETA] Help us test new features!",
304      },
305    },
306  },
307};
308```
309 
310Update `eas.json` to use JS config:
311 
312```json
313{
314  "cli": {
315    "metadataPath": "./store.config.js"
316  }
317}
318```
319 
320## Age Rating (Advisory)
321 
322Answer content questions honestly to get an appropriate age rating.
323 
324**Content Descriptors:**
325 
326- `NONE` - Content not present
327- `INFREQUENT_OR_MILD` - Occasional mild content
328- `FREQUENT_OR_INTENSE` - Regular or strong content
329 
330```json
331{
332  "advisory": {
333    "alcoholTobaccoOrDrugUseOrReferences": "NONE",
334    "contests": "NONE",
335    "gambling": false,
336    "gamblingSimulated": "NONE",
337    "horrorOrFearThemes": "NONE",
338    "matureOrSuggestiveThemes": "NONE",
339    "medicalOrTreatmentInformation": "NONE",
340    "profanityOrCrudeHumor": "NONE",
341    "sexualContentGraphicAndNudity": "NONE",
342    "sexualContentOrNudity": "NONE",
343    "unrestrictedWebAccess": false,
344    "violenceCartoonOrFantasy": "NONE",
345    "violenceRealistic": "NONE",
346    "violenceRealisticProlongedGraphicOrSadistic": "NONE",
347    "seventeenPlus": false,
348    "kidsAgeBand": "NINE_TO_ELEVEN"
349  }
350}
351```
352 
353**Kids Age Bands:** `FIVE_AND_UNDER`, `SIX_TO_EIGHT`, `NINE_TO_ELEVEN`
354 
355## Release Strategy
356 
357Control how your app rolls out to users.
358 
359```json
360{
361  "release": {
362    "automaticRelease": true,
363    "phasedRelease": true
364  }
365}
366```
367 
368**Options:**
369 
370- `automaticRelease: true` - Release immediately upon approval
371- `automaticRelease: false` - Manual release after approval
372- `automaticRelease: "2025-02-01T10:00:00Z"` - Schedule release (RFC 3339)
373- `phasedRelease: true` - 7-day gradual rollout (1%, 2%, 5%, 10%, 20%, 50%, 100%)
374 
375## Review Information
376 
377Provide contact info and test credentials for the App Review team.
378 
379```json
380{
381  "review": {
382    "firstName": "Jane",
383    "lastName": "Smith",
384    "email": "[email protected]",
385    "phone": "+1 (555) 123-4567",
386    "demoUsername": "[email protected]",
387    "demoPassword": "ReviewDemo2025!",
388    "notes": "To test premium features:\n1. Log in with demo credentials\n2. Navigate to Settings > Subscription\n3. Tap 'Restore Purchase' - sandbox purchase will be restored\n\nFor location features, allow location access when prompted."
389  }
390}
391```
392 
393## ASO Checklist
394 
395### Before Each Release
396 
397- [ ] Update keywords based on performance data
398- [ ] Refresh description with new features
399- [ ] Write compelling release notes
400- [ ] Update promo text if running campaigns
401- [ ] Verify all URLs are valid
402 
403### Monthly ASO Tasks
404 
405- [ ] Analyze keyword rankings
406- [ ] Research competitor keywords
407- [ ] Check conversion rates in App Analytics
408- [ ] Review user feedback for keyword ideas
409- [ ] A/B test screenshots in App Store Connect
410 
411### Keyword Research Tips
412 
4131. **Brainstorm features** - List all app capabilities
4142. **Mine reviews** - Find words users actually use
4153. **Analyze competitors** - Check their titles/subtitles
4164. **Use long-tail keywords** - Less competition, higher intent
4175. **Consider misspellings** - Common typos can drive traffic
4186. **Track seasonality** - Some keywords peak at certain times
419 
420### Metrics to Monitor
421 
422- **Impressions** - How often your app appears in search
423- **Product Page Views** - Users who tap to learn more
424- **Conversion Rate** - Views → Downloads
425- **Keyword Rankings** - Position for target keywords
426- **Category Ranking** - Position in your categories
427 
428## VS Code Integration
429 
430Install the [Expo Tools extension](https://marketplace.visualstudio.com/items?itemName=expo.vscode-expo-tools) for:
431 
432- Auto-complete for all schema properties
433- Inline validation and warnings
434- Quick fixes for common issues
435 
436## Common Issues
437 
438### "Binary not found"
439 
440Push a binary with `eas submit` before pushing metadata.
441 
442### "Invalid keywords"
443 
444- Check total length is ≤100 characters
445- Remove spaces after commas
446- Remove duplicate words
447 
448### "Description too long"
449 
450Description maximum is 4000 characters.
451 
452### Pull doesn't update JS config
453 
454`eas metadata:pull` creates a JSON file; import it into your JS config.
455 
456## CI/CD Integration
457 
458Automate metadata updates in your deployment pipeline:
459 
460```yaml
461# .eas/workflows/release.yml
462jobs:
463  submit-and-metadata:
464    steps:
465      - name: Submit to App Store
466        run: eas submit -p ios --latest
467 
468      - name: Push Metadata
469        run: eas metadata:push
470```
471 
472## Tips
473 
474- Update metadata every 4-6 weeks for optimal ASO
475- 70% of App Store visitors use search to find apps
476- Apps with 4+ star ratings get featured more often
477- Localized apps see 128% more downloads per country
478- First 3 lines of description are most critical (shown before "more")
479- Use all 100 keyword characters—every character counts
480