App Discoverability

Overview

Core principle Feed the system metadata across multiple APIs, let the system decide when to surface your app.

iOS surfaces apps in Spotlight, Siri suggestions, and system experiences based on metadata you provide through App Intents, App Shortcuts, Core Spotlight, and NSUserActivity. The system learns from actual usage and boosts frequently-used actions. No single API is sufficient—comprehensive discoverability requires a multi-API strategy.

Key insight iOS boosts shortcuts and activities that users actually invoke. If nobody uses an intent, the system hides it. Provide clear, action-oriented metadata and the system does the heavy lifting.

---

When to Use This Skill

Use this skill when:

• Making your app appear in Spotlight search results
• Enabling Siri to suggest your app in relevant contexts
• Adding app actions to Action Button (iPhone/Apple Watch Ultra)
• Making app content discoverable system-wide
• Planning discoverability architecture before implementation
• Troubleshooting "why isn't my app being suggested?"

Do NOT use this skill when:

• You need detailed API reference (use app-intents-ref, axiom-app-shortcuts-ref, axiom-core-spotlight-ref)
• You're implementing a specific API (use the reference skills)
• You just want to add a single App Intent (use app-intents-ref)

---

The 6-Step Discoverability Strategy

This is a proven strategy from developers who've implemented discoverability across multiple production apps. Implementation time: One evening for minimal viable discoverability.

Step 1: Add App Intents

App Intents power Spotlight search, Siri requests, and Shortcut suggestions. Without AppIntents, your app will never surface meaningfully.

struct OrderCoffeeIntent: AppIntent {
    static var title: LocalizedStringResource = "Order Coffee"
    static var description = IntentDescription("Orders coffee for pickup")

    @Parameter(title: "Coffee Type")
    var coffeeType: CoffeeType

    @Parameter(title: "Size")
    var size: CoffeeSize

    func perform() async throws -> some IntentResult {
        try await CoffeeService.shared.order(type: coffeeType, size: size)
        return .result(dialog: "Your \(size) \(coffeeType) is ordered")
    }
}

Why this matters App Intents are the foundation. Everything else builds on them.

See: app-intents-ref for complete API reference

---

Step 2: Add App Shortcuts with Suggested Phrases

App Shortcuts make your intents instantly available after install. No configuration required.

struct CoffeeAppShortcuts: AppShortcutsProvider {
    @AppShortcutsBuilder
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: OrderCoffeeIntent(),
            phrases: [
                "Order coffee in \(.applicationName)",
                "Get my usual coffee from \(.applicationName)"
            ],
            shortTitle: "Order Coffee",
            systemImageName: "cup.and.saucer.fill"
        )
    }

    static var shortcutTileColor: ShortcutTileColor = .tangerine
}

Why this matters Without App Shortcuts, users must manually configure shortcuts. With them, your actions appear immediately in Siri, Spotlight, Action Button, and Control Center.

Critical Use suggestedPhrase patterns—this increases the chance that the system proposes them in Spotlight action suggestions and Siri's carousel.

See: app-shortcuts-ref for phrase patterns and best practices

---

Step 3: Expose Searchable Content via Core Spotlight

Index content that matters. The system will surface items that match user queries.

import CoreSpotlight
import UniformTypeIdentifiers

func indexOrder(_ order: Order) {
    let attributes = CSSearchableItemAttributeSet(contentType: .item)
    attributes.title = order.coffeeName
    attributes.contentDescription = "Order from \(order.date.formatted())"
    attributes.keywords = ["coffee", "order", order.coffeeName]

    let item = CSSearchableItem(
        uniqueIdentifier: order.id.uuidString,
        domainIdentifier: "orders",
        attributeSet: attributes
    )

    CSSearchableIndex.default().indexSearchableItems([item]) { error in
        if let error = error {
            print("Indexing error: \(error)")
        }
    }
}

Why this matters Core Spotlight makes your app's content searchable. When users search for "latte" in Spotlight, your app's orders appear.

Index only what matters Don't index everything. Focus on user-facing content (orders, documents, notes, etc.).

See: core-spotlight-ref for batching, deletion patterns, and best practices

---

Step 4: Use NSUserActivity for High-Value Screens

Mark important screens as eligible for search and prediction.

func viewOrder(_ order: Order) {
    let activity = NSUserActivity(activityType: "com.coffeeapp.viewOrder")
    activity.title = order.coffeeName
    activity.isEligibleForSearch = true
    activity.isEligibleForPrediction = true
    activity.persistentIdentifier = order.id.uuidString

    // Connect to App Intents
    activity.appEntityIdentifier = order.id.uuidString

    // Provide rich metadata
    let attributes = CSSearchableItemAttributeSet(contentType: .item)
    attributes.contentDescription = "Your \(order.coffeeName) order"
    attributes.thumbnailData = order.imageData
    activity.contentAttributeSet = attributes

    activity.becomeCurrent()

    // In your view controller or SwiftUI view
    self.userActivity = activity
}

Why this matters The system learns which screens users visit frequently and suggests them proactively. Lock screen widgets, Siri suggestions, and Spotlight all benefit.

Critical Only mark screens that users would want to return to. Not settings, not onboarding, not error states.

See: core-spotlight-ref for eligibility patterns and activity continuation

---

Step 5: Provide Correct Intent Metadata

Clear descriptions and titles are critical because Spotlight displays them directly.

❌ DON'T: Generic or unclear

static var title: LocalizedStringResource = "Do Thing"
static var description = IntentDescription("Performs action")

✅ DO: Specific, action-oriented

static var title: LocalizedStringResource = "Order Coffee"
static var description = IntentDescription("Orders coffee for pickup")

Parameter summaries must be natural language:

static var parameterSummary: some ParameterSummary {
    Summary("Order \(\.$size) \(\.$coffeeType)")
}
// Siri: "Order large latte"

Why this matters Poor metadata means users won't understand what your intent does. Clear metadata = higher usage = system boosts it.

---

Step 6: Usage-Based Boosting

The system boosts shortcuts and activities that users actually invoke. If nobody uses an intent, the system hides it.

This is automatic—you don't control it. What you con