App Store Optimization (ASO)

# --- App Identity (REQUIRED) ---
app_name: ""                              # canonical app name as displayed in stores
developer_account_name: ""                # Apple team name / Google Play developer name
bundle_id_ios: ""                         # com.example.app
package_name_android: ""
app_store_id_ios: 0                       # numeric ID from App Store URL
play_store_url: ""

# --- Platforms ---
platforms:
  ios: false
  android: false
  ipados: false
  mac_catalyst: false
  vision_os: false
  android_tablets: false
  android_tv: false
  wear_os: false

# --- Distribution Status ---
ios_status: ""                            # live | in_review | rejected | unpublished | not_submitted
android_status: ""                        # live | internal_testing | closed_testing | open_testing | unpublished
launch_date_ios: ""                       # YYYY-MM-DD
launch_date_android: ""

# --- Current Performance ---
downloads_ios_total: 0
downloads_android_total: 0
downloads_last_30d_ios: 0
downloads_last_30d_android: 0
mau_ios: 0
mau_android: 0
rating_ios: 0.0
rating_android: 0.0
review_count_ios: 0
review_count_android: 0
review_count_last_30d_ios: 0
review_count_last_30d_android: 0
crash_rate_ios: 0.0                       # Xcode Organizer
crash_rate_android: 0.0                   # Android Vitals
anr_rate_android: 0.0

# --- Category and Competition ---
primary_category_ios: ""
secondary_category_ios: ""
primary_category_android: ""
top_competitors: []

# --- Current ASO State ---
title_ios: ""                             # max 30
subtitle_ios: ""                          # max 30
keyword_field_ios: ""                     # 100
promotional_text_ios: ""                  # max 170
description_ios: ""                       # max 4000
title_android: ""                         # max 30
short_description_android: ""             # max 80
long_description_android: ""              # max 4000
screenshot_count_ios: 0
screenshot_count_android: 0
preview_video_ios: false
preview_video_android: false
custom_product_pages_ios: 0               # CPP
custom_store_listings_android: 0          # CSL
ppo_tests_ios: 0
sle_tests_android: 0

# --- Web Coordination Layer ---
marketing_page_url: ""
universal_links_configured: false         # apple-app-site-association at .well-known
android_app_links_configured: false       # assetlinks.json at .well-known
smart_app_banner_present: false           # iOS Safari meta tag
applinks_meta_present: false
softwareapplication_schema_present: false
app_pack_visibility: ""                   # yes | no | intermittent | unknown
spotlight_indexing_implemented: false
nsuseractivity_implemented: false

# --- Localization ---
primary_languages_ios: []
primary_languages_android: []
cross_localization_enabled: false         # English (US) plus Spanish (MX) stack etc.

# --- Goals ---
primary_goal: ""                          # increase_organic_installs | improve_cvr | expand_keywords | recover_rating | win_app_pack | launch_new
target_keywords_brief: ""

apple_app_store_ranking_signals:

  title:
    weight: "highest"
    max_chars: 30
    rule: "Brand plus 1 to 3 high-intent keywords. Strongest indexed field."
    source: "Search Engine Land 2022; AppTweak 2025 benchmark."

  subtitle:
    weight: "very_high"
    max_chars: 30
    rule: "Distinct keywords from title; weight roughly equal to the hidden keyword field."

  keyword_field:
    weight: "high"
    max_chars: 100
    rule: "Comma-separated, no spaces, no title/subtitle repeats, singular only."
    visibility: "Hidden from users."

  screenshot_text:
    weight: "high"
    method: "AI extraction (confirmed at WWDC 25; not classical OCR)"
    rule: "Caption text treated as keyword metadata; top and bottom regions weighted most."
    launched: "June 2025"
    source: "Appfigures, 'The Biggest App Store Algorithm Change is Here', June 2025."

  ai_generated_tags:
    weight: "emerging"
    status: "Beta iOS 26 as of WWDC 2025; not yet on public App Store"
    method: "LLM analyzes metadata, description, category, screenshots; tappable chips"
    developer_control: "Cannot add manually; can remove irrelevant ones in App Store Connect"
    source: "TechCrunch, June 2025."

  download_velocity:
    weight: "high"
    rule: "Recent velocity (last 7 to 30 days) outweighs total all-time downloads."

  conversion_rate:
    weight: "high"
    rule: "Product page views to installs. AppTweak 2025: 33.4% iOS median."

  retention:
    weight: "high_and_growing"
    note: "Post-install retention is a quality signal (AppScreenshotStudio 2026 ranking guide)."

  ratings_and_reviews:
    weight: "high"
    factors: ["Star rating", "Velocity", "Recency", "Helpful-vote weighting"]
    note: "Sensor Tower 2025: 4.3 to 4.6 lift increases conversion 22 to 28% in Finance and Health."

  category:
    weight: "medium"
    rule: "Drives Browse tab and category charts."

  in_app_purchase_names:
    weight: "low"
    rule: "IAP names indexed; can include keywords."

  developer_name:
    weight: "low_to_medium"

  description:
    weight: "negligible_for_search"
    note: "NOT indexed on iOS. Conversion only. Google Play DOES index its long description."

google_play_store_ranking_signals:

  app_title: {weight: "highest", max_chars: 30}

  short_description:
    weight: "high"
    max_chars: 80
    note: "Indexed for search; visible. Google auto-localizes (AppTweak 2025: 88% apps / 94% games)."

  long_description:
    weight: "medium_to_high"
    max_chars: 4000
    rule: "Indexed; repeat each primary keyword 2 to 3 times naturally."

  install_count_and_velocity: {weight: "high"}

  ratings_and_reviews:
    weight: "high"
    factors: ["Star rating", "Velocity", "Recency", "Sentiment analysis on review text (Play Console)"]

  uninstalls:
    weight: "negative"
    rule: "High uninstall rate suppresses ranking."

  retention: {weight: "high", source: "30-day retention exposed in Play Console"}

  android_vitals:
    weight: "medium_to_high"
    thresholds:
      crash_rate: "under 1.09% (Play Store Bad Behavior threshold)"
      anr_rate: "under 0.47%"
    additional: ["Slow rendering", "Slow start", "Excessive wakeups", "Stuck wake locks"]
    source: "Android Vitals dashboard in Play Console."

  tags: {weight: "medium", rule: "Controlled vocabulary; up to 5 per app"}

  content_rating: {weight: "low", note: "Higher ratings limit reach; filter, not direct ranking signal"}

  developer_account_trust: {weight: "medium"}

keyword_research_sources:

  apple_app_store:
    apple_search_ads:
      url: "searchads.apple.com"
      data: "Search Popularity score (1 to 100, Apple internal)"
      access: "Free"
      caveat: "October 2025 update dropped the number of US App Store keywords with popularity above 5 by 77% (aso.dev analysis). Cross-reference with third-party data."
    apple_search_term_rank_report:
      status: "Insights section of Apple Search Ads, beta as of October 2025"
      data: "Monthly report; how search terms rank within genres and countries."
    third_party: ["AppTweak", "Sensor Tower", "AppFigures", "Mobile Action"]

  google_play_store:
    play_console_search_term_acquisition:
      path: "Acquire reports > Search term acquisition"
      data: "Real acquisition performance by search term for your own app"
    google_keyword_planner:
      note: "Web search volume; correlated to Play Store volume for high-intent terms"
    play_store_autocomplete:
      method: "Type seed term in Play Store search; record suggestions"
    third_party: ["AppTweak", "Sensor Tower", "AppFigures", "Mobile Action", "ASOdesk"]

aso_keyword_heuristics:
  brand_terms: "Exact brand in title; brand searches convert at 50%+ install rate."
  high_intent_unbranded: "Subtitle (iOS) and short description (Android) hold 2 to 4 high-intent unbranded terms."
  long_tail_keyword_field: "iOS 100-char field holds long-tail combinations that do not fit in title or subtitle."

  cross_localization_ios:
    pattern: "Apple indexes keywords from primary language plus one or more secondary localizations."
    us_example: "In US, Apple indexes English (US) plus Spanish (Mexico), Russian, Chinese, others."
    leverage: "Use Spanish (Mexico) keyword field on US-targeted app for 100 additional English keyword characters (if not localized into Spanish)."
    citation: "AppTweak 'How to Benefit from Cross-Localization on the App Store'; AppFigures '10x Your Keyword List'."

  apple_search_ads_research_loop: "Discovery campaign broad-match harvests converting terms into organic keyword field."
  google_play_long_description_repetition: "Each primary keyword 2 to 3 times naturally; no stuffing (Google detects density anomalies)."
  competitor_gap_analysis: "Pull top 3 competitors' indexed keyword lists; target their high-volume terms you do not yet cover."

ios_keyword_field_rules:

  total_chars: 100
  format: "Comma-separated, no spaces after commas (every space wastes a char)."
  case: "Lowercase; capitalization does not affect matching."
  no_repeats: "Do not include words already in title or subtitle."
  singular_only: "Apple matches plural automatically. Including both wastes chars."
  no_competitor_names: "Trademark rejection risk under Guideline 4.0."
  no_apple_terms: "Avoid 'free', 'app', 'iPhone', 'iPad', 'app store'. Apple strips or rejects."
  no_punctuation_other_than_comma: true
  per_localization: "Each localization has its own 100-char field. Use cross-localization to expand surface."

  example:
    bad: "best, free, meditation, app, sleep, meditation app, sleeping, meditate"
    why_bad: "'best' and 'free' are filler; 'app' rejected; 'meditation app' repeats 'meditation'; 'sleeping' is just plural of 'sleep'."
    good: "meditation,sleep,calm,anxiety,mindfulness,breathing,relax,unwind,zen"
    why_good: "Nine distinct indexed terms in 67 chars; 33 chars remain."

icon_guidelines:
  technical:
    ios: "1024x1024 PNG no alpha; Apple applies rounded-corner mask at runtime."
    android: "512x512 PNG alpha allowed; adaptive icon treatment."
  design:
    simplicity: "Recognizable at 60x60 px home screen size."
    contrast: "Strong against light and dark store backgrounds."
    no_text: "Brand letter only; full text illegible at thumbnail size."
    palette: "Two to three colors max."
    category_signaling: "Category-signaling icons outperform clever-but-ambiguous marks (SplitMetrics 2024-2025)."
  conversion_lift: "5 to 15% on average; outliers 30%+ (SplitMetrics 2024-2025)."
  priority: "Highest-leverage single asset to test first for most categories; Shopping exception (first screenshot leads)."
  testing:
    ios: "PPO; up to 3 treatments vs control."
    android: "SLE."

screenshot_guidelines:

  technical_ios:
    iphone_6_7: "1290x2796 px (iPhone 15 Pro Max). Required; Apple downsizes for smaller devices."
    iphone_5_5: "1242x2208 px legacy. Optional."
    ipad_12_9: "2048x2732 px. Required if iPad-compatible."
    count: "Up to 10 per device size."

  technical_android:
    phone: "Min 320 px, max 3840 px; aspect ratio 16:9 to 9:16."
    count: "Up to 8."
    feature_graphic: "1024x500 px banner at top of listing."

  composition:
    first_two_critical: "First two seen before scroll. Most decisions happen here."
    caption_text: "Since June 2025 Apple AI-extracts caption text as keyword metadata. Captions must be both human benefit AND indexed keyword."
    caption_example:
      bad: "The best app ever!"
      good: "Track Sleep Patterns"
      why: "Good caption surfaces 'track sleep' and 'sleep patterns' as indexed terms while reading as a benefit."
    device_frame_vs_full_bleed: "A/B test by category."
    visual_hierarchy: "Large text first, UI second, micro-text last."

  storytelling_pattern:
    s1: "Hero benefit with brand"
    s2: "Primary feature"
    s3: "Social proof"
    s4_5: "Secondary and tertiary features or use cases"
    s6_to_10: "Additional features and edge benefits"

  conversion_lift:
    source: "AppTweak 2025 ASO Trends and Benchmarks; SplitMetrics A/B compilation"
    findings:
      - "Quarterly A/B testing yields 20 to 30% higher CVR than static screenshots"
      - "Screenshot A/B tests produce 11.8% median CVR lift across variants"
      - "If first two screenshots do not change between PPO variants, the test is effectively identical to control"

  category_priorities:
    productivity: "Icon, then screenshots, then subtitle"
    shopping: "First screenshot, second screenshot, then preview video"
    games: "Gameplay screenshots and preview video dominate"
    finance_health: "Trust signaling critical (security badges, certifications, ratings)"

preview_video_guidelines:

  technical_ios:
    duration: "Up to 30 seconds"
    count: "Up to 3 per language"
    format: "MOV, M4V, MP4; under 500 MB"
    resolution: "Match device size (e.g., 2796x1290 for iPhone 15 Pro Max)"
    autoplay: "Yes, muted, on product page and in search results"
    source: "App Store Connect Help: App preview specifications."

  technical_android:
    hosting: "YouTube-hosted; one promo video per listing"
    duration: "Recommended under 30 sec; 2 min hard limit"
    autoplay: "On the listing page"

  content:
    audio_muted_default: "On-screen text and visuals must carry the message."
    first_3_seconds: "Open with hero benefit visually."
    actual_app_footage: "Both stores require footage of the actual app; concept videos risk rejection."

  conversion_lift:
    source: "Hilomedia 2025 Preview Videos guide; SplitMetrics aggregated data"
    findings:
      - "Well-produced preview lifts CVR 20 to 40% over screenshots-only listings"
      - "Watchers and engagers are roughly 2x more likely to install"
      - "At least half of viewers watch through to end"

  poster_frame_ios: "Apple shows when autoplay disabled. Pick a frame conveying value prop with caption text."

custom_pages:

  ios_cpp:
    customizable: "Screenshots, preview videos, promotional text, deep link target"
    fixed: "Name, subtitle, icon, description, keywords"
    max_per_app: 70                       # since October 29, 2025
    keyword_assignment: "Since mid-2025 CPPs can be assigned keywords; appear in organic search results."
    deep_links: "Each CPP can deep-link into a specific in-app destination after install."
    use_cases: ["Audience segments", "Traffic sources", "Markets within a locale", "Feature emphasis for paid"]
    source: "Apple Developer App Store Connect Help: Custom Product Pages."

  ios_ppo:
    elements: "Icon, screenshots, preview videos"
    treatments: "Up to 3 vs control"
    duration: "Up to 90 days per test; one at a time"
    reporting: "App Analytics"

  android_csl:
    customizable: "Title, short description, long description, graphics, video"
    max_per_app: 50
    targeting: "Country, language, install state, pre-registration"
    google_ads_integration: "Integrates with Google Ads campaigns"
    ai_text_generation: "2025: experimental Gemini AI generates CSL text by theme, tone, audience."

  android_sle:
    elements: "Icon, feature graphic, screenshots, short description"
    concurrent_tests: "Up to 5 on main listing; up to 5 per CSL (50 CSLs = 250+ parallel)"
    reporting: "Significance and confidence interval"

review_acquisition:

  ios_skstorereviewcontroller:
    api: "StoreKit SKStoreReviewController / requestReview()"
    throttle: "Apple limits prompts to 3 per user per 365-day period."
    timing: "Only after demonstrated user value. Never on launch."
    apple_control: "Apple decides whether to actually show; developer has no override."
    source: "Apple Developer Documentation: SKStoreReviewController."

  android_in_app_review_api:
    api: "Google Play In-App Review API (Play Core library)"
    throttle: "Quota enforced; over-frequent calls silently no-op."

  prohibited:
    - "Incentivized reviews (paying, rewarding, unlocking content for reviews)"
    - "Review gating (asking satisfaction first; only prompting happy users)"
    - "Custom non-platform review prompts (Apple Guideline 1.1.7)"
    - "Buying reviews"
    - "Asking employees, family, or paid actors"
  citation: "Apple App Store Review Guideline 1.1.7; Google Play Developer Program Policy on Ratings, Reviews, and User-Generated Content."

  ethical_pattern:
    - "Trigger after a moment of value"
    - "Pre-empt complaints with a voluntary in-app support channel that does NOT gate the rating prompt"

review_response:
  why:
    ranking: "Developer responses are visible; signal active management."
    conversion: "Prospective users read responses to negative reviews."
    rating_recovery: "AppFollow benchmark: 5 to 15% of users update rating up after a thoughtful response."
  pattern:
    structure: ["Acknowledge specific issue", "Apologize where warranted (no unverified bug admissions)", "Offer specific next step", "Sign as a person"]
    tone: "Human, specific, accountable."
    timing: "Within 7 days; AppFollow top-100 median is under 48 hours."
    languages: "Respond in the language of the review."
  priority: "1-star first, 2-star second, selective on 4-5 star."
  rating_decay:
    finding: "Reviews older than 12 to 24 months deeply discounted in both stores."
    implication: "An app with 100K reviews from 5 years ago but 10 in the last 30 days behaves like a low-velocity app."
    citation: "Local Falcon; Sensor Tower review velocity studies."

negative_review_recovery:
  triage: ["Pull last 30 days of 1- and 2-star reviews", "Categorize: bugs, feature requests, UX, content, monetization", "Identify dominant category"]
  fix_then_respond:
    - "Ship fix addressing dominant complaint"
    - "Respond to each negative review noting the fix; ask user to try new version"
    - "Bump version conspicuously"
  reset_options:
    ios: "Reset applies to new version only; cumulative still includes legacy."
    android: "No reset feature; dilute via fresh positive velocity."
  flag_for_removal: "Both stores allow flagging spam, off-topic, or defamatory reviews; success rate varies."

app_marketing_page_structure:

  url:
    pattern: "/apps/[app-slug]/ or /[app-slug]/"
    rule: "Stable. Do not version; deep-link records depend on it."

  above_the_fold:
    - "App name (H1)"
    - "One-line value proposition"
    - "App Store badge"
    - "Google Play badge (both present; missing platform labeled 'Coming soon' or 'Not available on [platform]')"
    - "Hero image"
    - "Star rating and review count"

  body_content:
    - "What the app does (3 to 5 paragraphs)"
    - "Key features (5 to 10 bullets)"
    - "How it works (3 to 5 steps)"
    - "Screenshots gallery (3 to 6 with captions)"
    - "Reviews (2 to 5 best, linked to stores)"
    - "FAQ (5 to 10: pricing, platforms, privacy, support, cancellation)"
    - "About the developer (1 to 2 paragraphs, linked to Organization)"
  rule: "Content first. Every section in initial server response HTML, not JS-injected. See framework-contentfirst.md."

  conversion_elements:
    primary_cta: "Both store badges in hero"
    secondary_cta: "Repeated badges after each major section"
    smart_app_banner: "iOS Safari meta tag (Section 8.3)"
    qr_code_for_desktop: "QR opening store page on user's phone"

  trust_signals: ["Star rating linked to store reviews", "Press logos if real", "Privacy and terms", "Award badges if real and current"]

<a href="https://apps.apple.com/us/app/example-app/id123456789">
  <img src="/img/app-store-badge.svg" alt="Download on the App Store" width="180" height="60">
</a>
<a href="https://play.google.com/store/apps/details?id=com.example.app">
  <img src="/img/google-play-badge.png" alt="Get it on Google Play" width="200" height="60">
</a>

<meta name="apple-itunes-app" content="app-id=123456789, app-argument=https://example.com/path/to/content">

<meta property="al:ios:url" content="exampleapp://path/to/content">
<meta property="al:ios:app_store_id" content="123456789">
<meta property="al:ios:app_name" content="Example App">
<meta property="al:android:url" content="exampleapp://path/to/content">
<meta property="al:android:package" content="com.example.app">
<meta property="al:android:app_name" content="Example App">
<meta property="al:web:url" content="https://example.com/path/to/content">

location = /.well-known/apple-app-site-association {
    default_type application/json;
    add_header Cache-Control "public, max-age=3600";
}
location = /.well-known/assetlinks.json {
    default_type application/json;
    add_header Cache-Control "public, max-age=3600";
}

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "MobileApplication",
  "name": "Example App",
  "applicationCategory": "HealthApplication",
  "applicationSubCategory": "Meditation",
  "operatingSystem": "iOS, Android",
  "offers": {"@type": "Offer", "price": "0", "priceCurrency": "USD", "availability": "https://schema.org/InStock"},
  "aggregateRating": {"@type": "AggregateRating", "ratingValue": "4.7", "ratingCount": "12453", "bestRating": "5", "worstRating": "1"},
  "downloadUrl": ["https://apps.apple.com/us/app/example-app/id123456789", "https://play.google.com/store/apps/details?id=com.example.app"],
  "installUrl": ["https://apps.apple.com/us/app/example-app/id123456789", "https://play.google.com/store/apps/details?id=com.example.app"],
  "screenshot": ["https://example.com/img/screenshot-1.jpg", "https://example.com/img/screenshot-2.jpg", "https://example.com/img/screenshot-3.jpg"],
  "publisher": {"@type": "Organization", "name": "Example, Inc.", "url": "https://example.com"},
  "datePublished": "2024-03-15",
  "softwareVersion": "3.2.1"
}
</script>

universal_links_setup:

  capabilities:
    location: "Xcode > Project > Signing and Capabilities > Associated Domains"
    add: "applinks:example.com"

  aasa_file:
    path: "https://example.com/.well-known/apple-app-site-association"
    content_type: "application/json"
    https: "Required; no HTTP fallback."
    no_redirect: "Apple's request must hit a 200 directly."
    size_limit: "128 KB uncompressed."
    example: |
      {"applinks": {"apps": [],
        "details": [{"appID": "ABCD1234EF.com.example.app",
                     "paths": ["/path/to/content/*", "/another/*", "NOT /admin/*"]}]}}
    appID_format: "TeamID.BundleID (10-char Apple Developer Team ID)."
    paths_syntax: "Glob patterns; NOT prefix excludes."

  validation:
    apple_validator: "search.developer.apple.com/appsearch-validation-tool/"
    curl_check: "curl -I https://example.com/.well-known/apple-app-site-association"
    cache: "iOS caches AASA up to 7 days; force refresh by deleting and reinstalling."

  source: "Apple Developer Documentation: Supporting universal links in your app."

android_app_links_setup:

  manifest:
    location: "AndroidManifest.xml > Activity > intent-filter"
    example: |
      <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="https" android:host="example.com" android:pathPrefix="/path" />
      </intent-filter>

  assetlinks_file:
    path: "https://example.com/.well-known/assetlinks.json"
    content_type: "application/json"
    example: |
      [{"relation": ["delegate_permission/common.handle_all_urls"],
        "target": {"namespace": "android_app",
                   "package_name": "com.example.app",
                   "sha256_cert_fingerprints": ["14:6D:E9:83:C5:73:..."]}}]
    sha256_source: "`keytool -list -v -keystore [keystore]` or Play Console > Setup > App Integrity."

  dynamic_app_links_2025:
    feature: "Android 15 (API 35)+ supports Dynamic App Links."
    declaration: "Path, query, fragment matchers in assetlinks.json itself; merged with manifest at runtime."
    source: "Android Developers Blog: Dynamic App Links, October 2025."

  validation:
    google_tool: "developers.google.com/digital-asset-links/tools/generator"
    curl_check: "curl -I https://example.com/.well-known/assetlinks.json"
    auto_verify: "android:autoVerify=true triggers fetch on install."

  source: "Google Developers Digital Asset Links; Android Developers Configure website associations."

core_spotlight_indexing:

  apis:
    nsuseractivity: "Index activities as user performs them (visiting page, creating content, viewing items)."
    corespotlight: "Index content programmatically without user visit. For documents, photos, persistent data."
    web_markup: "Web URLs with matching schema can also be crawled by Apple for Spotlight."

  best_practice: "Use the same identifier across NSUserActivity, CoreSpotlight, and web URL. Apple deduplicates by identifier; same item in multiple APIs ranks stronger."

  privacy: "Index is on-device. Apple does not see the content."

  source: "Apple Developer Documentation: Core Spotlight; Technical Note TN2416 iOS Search API Best Practices."

app_pack_inclusion:
  prerequisite_published: "Live on at least one store; apps in review do not appear."
  prerequisite_metadata_alignment: "Store title or category aligns with query."
  signal_install_velocity: "Recent install velocity in relevant category."
  signal_rating: "Higher star rating favored."
  signal_marketing_page_seo: "Well-ranked marketing page increases App Pack inclusion for target queries."
  signal_appindex_legacy: "Historical Google App Indexing signals persist in part."
  practical_strategy:
    - "Optimize store metadata for target query"
    - "Optimize marketing page for target query"
    - "Link marketing page to store URLs"
    - "Configure Universal Links and assetlinks.json"
    - "Monitor via Semrush, Ahrefs, AccuRanker SERP features filter"

apple_intelligence_app_discovery:

  spotlight_search:
    description: "Device-wide search (swipe down on home; Cmd+Space on Mac)."
    indexes: "Apps, files, contacts, messages, calendar, in-app content (via CoreSpotlight)."
    ai_layer: "Results personalized by on-device AI; usage patterns, time, location, recent activity."
    scale: "Approximately 700 to 900M daily users globally; 85% of iPhone users engage weekly (TechLila 2026 statistics)."

  siri_suggestions:
    description: "Proactive suggestions in Lock Screen, Notifications, Spotlight."
    overlap: "80 to 90% same data as Spotlight."

  app_store_today_tab:
    scale: "Approximately 500M weekly users begin discovery here (Apple Developer documentation)."
    ai_layer: "AI-generated tag chips (beta in iOS 26)."
    featuring: "Featuring Nominations in App Store Connect; 2-week minimum notice."

  ai_generated_tags:
    description: "Tappable chips grouping apps by inferred function ('Meditation', 'Sleep Tracking')."
    status: "Beta iOS 26 developer build as of WWDC 2025; not yet on public App Store."
    source: "TechCrunch June 2025; Apple WWDC 2025 keynote."

  writing_tools_app_picks: "Some flows suggest apps during Apple Intelligence drafting, replying, summarizing."
  control_center_widget_suggestions: "Suggested apps in Control Center and Widget Gallery."

apple_intelligence_aso_levers:
  spotlight_indexing: "Implement CoreSpotlight and NSUserActivity (Section 9.5)."
  app_store_metadata_quality: "AI tags pull from metadata, screenshots, description, category. Precise metadata leads to accurate tags."
  ai_tags_review: "When live, audit and remove inaccurate tags in App Store Connect at launch and quarterly."
  featuring_nominations: "Submit for Today tab editorial consideration."
  category_choice: "Primary category drives Today tab placement."
  cannot_influence: ["Personalization weights", "Siri Suggestions ranking", "Spotlight ranking from external content"]

common_aso_mistakes:

  m1_keyword_stuffing_title:
    pattern: "Title is 'YourBrand: Meditation, Sleep, Calm, Yoga, Mindfulness'."
    why_bad: "Apple rejects under Guideline 2.3 (misleading metadata). Users skip as spammy."
    fix: "Brand plus 1 to 2 keywords; subtitle for additional terms."

  m2_skipping_subtitle:
    pattern: "Subtitle blank or generic tagline like 'The best app ever'."
    why_bad: "Wastes 30 chars equivalent in weight to the keyword field."
    fix: "Keyword-dense readable description: 'Sleep, Meditate, Relax Daily'."

  m3_keyword_field_repeats_title:
    pattern: "Title has 'meditation'; keyword field has 'meditation, meditate, meditations'."
    why_bad: "Title/subtitle indexed separately; repetition wastes the 100-char field."
    fix: "Audit after each metadata change."

  m4_screenshots_without_captions:
    pattern: "Bare device renders, no caption text."
    why_bad: "Since June 2025 Apple AI-extracts caption text as metadata. Wasted ranking signal."
    fix: "Caption every screenshot; match to real keywords with conversion phrasing."

  m5_no_a_b_testing:
    pattern: "Screenshots and icon set at launch, never updated."
    why_bad: "AppTweak: quarterly A/B testers see 20 to 30% higher CVR."
    fix: "Quarterly PPO (iOS) / SLE (Android)."

  m6_review_gating:
    pattern: "Asks 'Are you happy?' then only prompts SKStoreReviewController on yes."
    why_bad: "Violates Apple Guideline 1.1.7 and Google Play Developer Policy. Removal risk."
    fix: "Trigger native prompt unconditionally after value moment; separate support channel for complaints."

  m7_no_universal_links_no_assetlinks:
    pattern: "Marketing page links to store URLs but app does not handle domain via Universal Links / App Links."
    why_bad: "Installed-app users land on marketing page instead of in the app."
    fix: "Implement both; validate .well-known files."

  m8_marketing_page_is_csr_spa:
    pattern: "Client-rendered React/Vue; server returns empty shell."
    why_bad: "AI bots (GPTBot, ClaudeBot, PerplexityBot) cannot render; page invisible to AI citation. App Pack suffers."
    fix: "Server-render. Next.js, Astro, Hugo, plain HTML. See framework-contentfirst.md."

  m9_no_schema:
    pattern: "No MobileApplication or SoftwareApplication schema."
    why_bad: "No rich results; AI engines cannot extract app as structured entity."
    fix: "MobileApplication in @graph cross-referencing Organization and WebSite. Validate at validator.schema.org."

  m10_ignoring_play_long_description:
    pattern: "200-word Play long description with no keyword strategy."
    why_bad: "Google Play indexes long description for search."
    fix: "1500 to 3000 chars; each primary keyword 2 to 3 times naturally."

first_90_days:
  day_0_to_7:
    - "Pull current metadata, assets, ratings, reviews into intake"
    - "Run keyword research (Apple Search Ads, Play Console, AppTweak/Sensor Tower)"
    - "Identify top 10 target keywords per platform"
    - "Audit competitor metadata for top 3"
  day_8_to_30:
    - "Rewrite title, subtitle, keyword field (iOS); short description (Android)"
    - "Write new long description (Android) with target keywords"
    - "Design and ship new screenshots with keyword-aligned captions"
    - "Submit new metadata for review"
    - "Build or refresh marketing page; ship schema, AppLinks, Smart App Banner"
    - "Deploy apple-app-site-association and assetlinks.json"
  day_31_to_60:
    - "Launch first PPO (iOS) / SLE (Android) on icon or first screenshot"
    - "Configure first CPPs / CSLs"
    - "Implement SKStoreReviewController / In-App Review API"
    - "Implement Core Spotlight indexing (iOS)"
    - "Set up review response workflow"
    - "Submit featuring nomination for an upcoming product moment"
  day_61_to_90:
    - "Conclude first test; ship winner"
    - "Launch second test on next priority element"
    - "Add 2 to 3 additional CPPs / CSLs"
    - "Refine keyword performance"
    - "Audit App Pack inclusion; refine marketing page if not appearing"
    - "Audit Apple Intelligence surfaces"
    - "Generate first 90-day report"

aso_maintenance_cadence:
  weekly:
    - "Rating and review velocity"
    - "Respond to 1- and 2-star within 7 days"
    - "Monitor App Pack and Spotlight visibility for top queries"
    - "Crash rate (Xcode Organizer) and Android Vitals"
  monthly:
    - "Keyword ranking deltas"
    - "Competitor metadata changes"
    - "PPO / SLE; ship winners; queue next test"
    - "Downloads and CVR numbers"
    - "Refresh featuring nominations if product moment"
  quarterly:
    - "Full metadata audit (title, subtitle, keyword field, descriptions)"
    - "Refresh screenshots with new feature or seasonal angle"
    - "Refresh preview video if older than 6 to 9 months"
    - "Re-run keyword research"
    - "Audit Apple AI-generated tags when public"
    - "Audit Universal Links and assetlinks.json"
    - "Review marketing page SEO (Core Web Vitals, schema, content)"
  annually:
    - "Full ASO audit against Section 13 rubric"
    - "Strategic competitive position review"
    - "Re-evaluate primary category if app function drifted"
    - "Refresh icon if older than 18 to 24 months and trend shifted"

aso_monthly_report:
  period: "[YYYY-MM-DD] to [YYYY-MM-DD]"
  downloads:
    ios_new: 0
    android_new: 0
    delta_vs_prior: ""
  conversion_rate:
    ios_cvr_pct: 0.0                      # store as percentage; compare to category benchmark
    android_cvr_pct: 0.0
  ratings:
    ios_rating: 0.0
    android_rating: 0.0
    new_reviews_ios: 0
    new_reviews_android: 0
    response_rate_pct: 0
  keyword_ranking:
    tracked_top_10_ios: "N of N"
    tracked_top_10_android: "N of N"
    notable_movements: []
  tests:
    active_or_concluded: []
  web_marketing_page:
    sessions: 0
    branded_query_rank: 0
    non_branded_query_rank: 0
    app_pack_visibility: ""
  action_items_next_period: []

aso_quarterly_report:
  quarter: "Q[N] [YYYY]"
  executive_summary: ""                   # two to four sentence narrative
  downloads_trend:
    quarter_total: 0
    prior_quarter: 0
    yoy_delta_pct: 0.0
    monthly_breakdown: []
  conversion_rate_trend:
    ios_q_minus_1: 0.0
    ios_q: 0.0
    android_q_minus_1: 0.0
    android_q: 0.0
  ratings_trend:
    ios_q_minus_1: 0.0
    ios_q: 0.0
    android_q_minus_1: 0.0
    android_q: 0.0
  test_outcomes: []                       # list of {test_name, winner_shipped, lift_pct}
  keyword_strategy_update:
    keywords_added: 0
    keywords_retired: 0
    ranking_distribution: ""
  web_marketing_page:
    organic_sessions_qoq_delta_pct: 0.0
    schema_audit: ""
    universal_links_status: ""
    assetlinks_status: ""
    core_web_vitals: ""
  goals_next_quarter: []