Asc Metadata Sync

Asc Metadata Sync is a community skill for synchronizing app metadata between local files and App Store Connect, covering localized descriptions, keywords, screenshots, what-is-new text, and automated metadata deployment for App Store submissions.

What Is This?

Overview

Asc Metadata Sync provides patterns for managing App Store metadata as local files that sync to App Store Connect. It covers localized description management that stores descriptions per language in local files, keyword synchronization with per-locale character limit validation, screenshot management that uploads and orders device screenshots for each display size and locale, what-is-new text that updates release notes from local files during version submission, and automated deployment that pushes all metadata changes in a single operation. The skill enables teams to manage App Store metadata in version control.

Who Should Use This

This skill serves iOS teams managing localized metadata across many languages, release managers automating App Store submission metadata updates, and marketing teams maintaining app descriptions and keywords in version control.

Why Use It?

Problems It Solves

Editing metadata through the App Store Connect dashboard is slow and error-prone for multiple locales. Keyword updates that exceed character limits are rejected during submission without advance warning. Screenshot ordering and locale assignment requires manual work for each device size. Release notes are frequently forgotten during submission without an automated process.

Core Highlights

File-based metadata stores descriptions, keywords, and release notes in a directory structure per locale. Validation checks character limits and required fields before syncing. Screenshot uploader handles device-specific sizing and locale ordering. Sync engine pushes local changes to App Store Connect in a single batch.

How to Use It?

Basic Usage

import os
import json
from pathlib import Path

LIMITS = {
  'name': 30,
  'subtitle': 30,
  'keywords': 100,
  'description': 4000,
  'whatsNew': 4000,
  'promotionalText': 170,
}

class MetadataSync:
  def __init__(
    self,
    metadata_dir: str,
    api_client
  ):
    self.dir = Path(
      metadata_dir)
    self.api = api_client

  def validate(
    self
  ) -> list[str]:
    errors = []
    for locale_dir in\
        self.dir.iterdir():
      if not locale_dir\
          .is_dir():
        continue
      locale = locale_dir.name
      for field, limit\
          in LIMITS.items():
        fpath = locale_dir\
          / f'{field}.txt'
        if fpath.exists():
          text = fpath\
            .read_text().strip()
          if len(text) > limit:
            errors.append(
              f'{locale}/'
              f'{field}: '
              f'{len(text)}/'
              f'{limit} chars')
    return errors

  def sync(
    self,
    version_id: str
  ) -> dict:
    errors = self.validate()
    if errors:
      return {
        'success': False,
        'errors': errors}

    synced = []
    for locale_dir in\
        self.dir.iterdir():
      if not locale_dir\
          .is_dir():
        continue
      locale = locale_dir.name
      payload = {}
      for field\
          in LIMITS.keys():
        fpath = locale_dir\
          / f'{field}.txt'
        if fpath.exists():
          payload[field] =\
            fpath.read_text()\
              .strip()

      self.api.update_locale(
        version_id,
        locale,
        payload)
      synced.append(locale)
    return {
      'success': True,
      'synced': synced}

Real-World Examples

python3 sync.py validate \
  --dir metadata/

python3 sync.py push \
  --dir metadata/ \
  --app-id 123456 \
  --version 2.1.0

python3 sync.py pull \
  --dir metadata/ \
  --app-id 123456 \
  --version 2.1.0

Advanced Tips

Implement a pull command that downloads current metadata from App Store Connect to local files for initial setup and diff comparison. Use Git hooks to validate metadata character limits on commit to catch errors before deployment. Track keyword rankings alongside metadata changes to measure the impact of keyword updates.

When to Use It?

Use Cases

Sync localized app descriptions and keywords from Git-tracked files to App Store Connect during release. Validate all metadata field lengths before submission to avoid rejection. Automate screenshot uploads across device sizes and locales for app updates.

Related Topics

App Store Connect metadata, app localization, screenshot management, ASO optimization, and release automation.

Important Notes

Requirements

App Store Connect API key with metadata write permissions. Local directory structure organized by locale with text files for each metadata field. Screenshot files named and organized by device display size.

Usage Recommendations

Do: validate metadata locally before syncing to catch character limit violations early. Store metadata files in version control for change tracking and review. Test sync operations against a separate app before applying to production listings.

Don't: sync metadata without validation as rejected fields may partially update other locales. Modify metadata directly in App Store Connect after syncing from files which creates drift. Exceed keyword character limits by counting bytes instead of characters for multi-byte languages.

Limitations

Screenshot upload is slow for apps with many locales and device sizes. Promotional text cannot be set for the initial version and requires a live app. Some metadata fields have undocumented formatting restrictions.