axiom-app-discoverability

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

核心原则 通过多个API向系统提供元数据，由系统决定何时展示你的应用。

iOS会根据你通过App Intents、App Shortcuts、Core Spotlight和NSUserActivity提供的元数据，在Spotlight、Siri建议和系统体验中展示应用。系统会从实际使用情况中学习，并优先推荐频繁使用的操作。单一API不足以实现全面的可发现性——需要采用多API策略。

关键见解 iOS会优先推荐用户实际调用过的快捷指令和活动。如果没有用户使用某个intent，系统会将其隐藏。提供清晰的、以行动为导向的元数据，系统会完成后续的主要工作。

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)

在以下场景使用此技能：

让你的应用出现在Spotlight搜索结果中
让Siri在相关场景下推荐你的应用
为Action Button（iPhone/Apple Watch Ultra）添加应用操作
让应用内容在全系统范围内可被发现
在实现前规划可发现性架构
排查“为什么我的应用没有被推荐？”的问题

请勿在以下场景使用此技能：

你需要详细的API参考（使用app-intents-ref、axiom-app-shortcuts-ref、axiom-core-spotlight-ref）
你正在实现某个特定的API（使用参考技能）
你只想添加单个App Intent（使用app-intents-ref）

The 6-Step Discoverability Strategy

6步可发现性策略

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

步骤1：添加App Intents

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

swift

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

App Intents为Spotlight搜索、Siri请求和快捷指令推荐提供支持。没有AppIntents，你的应用无法获得有意义的展示机会。

swift

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")
    }
}

重要性 App Intents是基础，所有其他功能都构建在此之上。

参考：app-intents-ref 获取完整API参考

Step 2: Add App Shortcuts with Suggested Phrases

步骤2：添加带推荐短语的App Shortcuts

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

swift

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

App Shortcuts可让你的intents在安装后立即可用，无需用户配置。

swift

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
}

重要性 没有App Shortcuts，用户必须手动配置快捷指令。有了它，你的操作会立即出现在Siri、Spotlight、Action Button和控制中心中。

关键要点 使用

suggestedPhrase

模式——这会增加系统在Spotlight操作建议和Siri轮播中推荐它们的几率。

参考：app-shortcuts-ref 获取短语模式和最佳实践

Step 3: Expose Searchable Content via Core Spotlight

步骤3：通过Core Spotlight暴露可搜索内容

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

swift

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

为重要内容建立索引。系统会展示与用户查询匹配的条目。

swift

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)")
        }
    }
}

重要性 Core Spotlight让你的应用内容可被搜索。当用户在Spotlight中搜索“latte”时，你的应用订单会被展示。

只索引重要内容 不要索引所有内容。专注于用户可见的内容（订单、文档、笔记等）。

参考：core-spotlight-ref 获取批量处理、删除模式和最佳实践

Step 4: Use NSUserActivity for High-Value Screens

步骤4：为高价值页面使用NSUserActivity

Mark important screens as eligible for search and prediction.

swift

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

将重要页面标记为可被搜索和预测的对象。

swift

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

    // 连接到App Intents
    activity.appEntityIdentifier = order.id.uuidString

    // 提供丰富的元数据
    let attributes = CSSearchableItemAttributeSet(contentType: .item)
    attributes.contentDescription = "Your \(order.coffeeName) order"
    attributes.thumbnailData = order.imageData
    activity.contentAttributeSet = attributes

    activity.becomeCurrent()

    // 在你的视图控制器或SwiftUI视图中
    self.userActivity = activity
}

重要性 系统会学习用户频繁访问的页面，并主动推荐它们。锁屏小组件、Siri建议和Spotlight都会从中受益。

关键要点 仅标记用户可能想返回的页面。不要标记设置、引导页或错误状态页面。

参考：core-spotlight-ref 获取资格模式和活动续传相关内容

Step 5: Provide Correct Intent Metadata

步骤5：提供正确的Intent元数据

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

清晰的描述和标题至关重要，因为Spotlight会直接展示它们。

❌ DON'T: Generic or unclear

❌ 错误做法：通用或模糊

swift

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

swift

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

✅ DO: Specific, action-oriented

✅ 正确做法：具体、以行动为导向

swift

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

Parameter summaries must be natural language:

swift

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.

swift

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

参数摘要必须使用自然语言：

swift

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

重要性 糟糕的元数据会让用户无法理解你的intent的作用。清晰的元数据=更高的使用率=系统优先推荐。

Step 6: Usage-Based Boosting

步骤6：基于使用情况的优先推荐

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 control:

Discoverability — Make it easy to find (Steps 1-5)
Utility — Make it worth using (design good intents)
Promotion — Show users available shortcuts (SiriTipView)

swift

// Promote your shortcuts in-app
SiriTipView(intent: OrderCoffeeIntent(), isVisible: $showTip)
    .siriTipViewStyle(.dark)

Why this matters Even perfect metadata won't help if users don't know shortcuts exist. Educate users in your app's UI.

See: app-shortcuts-ref for SiriTipView and ShortcutsLink patterns

系统会优先推荐用户实际调用过的快捷指令和活动。如果没有用户使用某个intent，系统会将其隐藏。

这是自动的——你无法控制它。你可以控制的是：

可发现性 —— 让用户容易找到（步骤1-5）
实用性 —— 让它值得使用（设计优质的intents）
推广 —— 向用户展示可用的快捷指令（SiriTipView）

swift

// 在应用内推广你的快捷指令
SiriTipView(intent: OrderCoffeeIntent(), isVisible: $showTip)
    .siriTipViewStyle(.dark)

重要性 即使元数据完美，如果用户不知道快捷指令的存在也无济于事。在应用UI中引导用户。

参考：app-shortcuts-ref 获取SiriTipView和ShortcutsLink模式

Decision Tree: Which API for Which Use Case

决策树：不同场景对应哪个API

┌─ Need to expose app functionality? ────────────────────────────────┐
│                                                                      │
│  ┌─ YES → App Intents (AppIntent protocol)                         │
│  │        └─ Want instant availability without user setup?         │
│  │           └─ YES → App Shortcuts (AppShortcutsProvider)         │
│  │                                                                  │
│  └─ NO → Exposing app CONTENT (not actions)?                       │
│           │                                                         │
│           ├─ User-initiated activity (viewing screen)?             │
│           │  └─ YES → NSUserActivity with isEligibleForSearch      │
│           │                                                         │
│           └─ Indexing all content (documents, orders, notes)?      │
│              └─ YES → Core Spotlight (CSSearchableItem)            │
│                                                                     │
│  ┌─ Already using App Intents?                                     │
│  │  └─ Want automatic Spotlight search for entities?               │
│  │     └─ YES → IndexedEntity protocol                             │
│  │                                                                  │
│  └─ Want to connect screen to App Intent entity?                   │
│     └─ YES → NSUserActivity.appEntityIdentifier                    │
└──────────────────────────────────────────────────────────────────┘

┌─ 需要暴露应用功能？ ────────────────────────────────┐
│                                                                      │
│  ┌─ 是 → App Intents（AppIntent协议）                         │
│  │        └─ 想要无需用户设置即可立即使用？         │
│  │           └─ 是 → App Shortcuts（AppShortcutsProvider）         │
│  │                                                                  │
│  └─ 否 → 暴露应用内容（而非操作）？                       │
│           │                                                         │
│           ├─ 用户发起的活动（查看页面）？             │
│           │  └─ 是 → 启用isEligibleForSearch的NSUserActivity      │
│           │                                                         │
│           └─ 为所有内容建立索引（文档、订单、笔记）？      │
│              └─ 是 → Core Spotlight（CSSearchableItem）            │
│                                                                     │
│  ┌─ 已在使用App Intents？                                     │
│  │  └─ 想要为实体自动生成查找操作？               │
│  │     └─ 是 → IndexedEntity协议                             │
│  │                                                                  │
│  └─ 想要将页面与App Intent实体关联？                   │
│     └─ 是 → NSUserActivity.appEntityIdentifier                    │
└──────────────────────────────────────────────────────────────────┘

Quick Reference Table

快速参考表

Use Case	API	Example
Expose action to Siri/Shortcuts	`AppIntent`	"Order coffee"
Make action available instantly	`AppShortcut`	Appear in Spotlight immediately
Index all app content	`CSSearchableItem`	All coffee orders searchable
Mark current screen important	`NSUserActivity`	User viewing order detail
Auto-generate Find actions	`IndexedEntity`	"Find orders where..."
Link screen to App Intent	`appEntityIdentifier`	Deep link to specific order

使用场景	API	示例
向Siri/快捷指令暴露操作	`AppIntent`	"Order coffee"
让操作立即可用	`AppShortcut`	立即出现在Spotlight中
为所有应用内容建立索引	`CSSearchableItem`	所有咖啡订单可被搜索
标记当前页面为重要页面	`NSUserActivity`	用户查看订单详情
自动生成查找操作	`IndexedEntity`	"查找订单..."
将页面与App Intent关联	`appEntityIdentifier`	深度链接到特定订单

Quick Implementation Pattern ("One Evening" Approach)

快速实现模式（“一个晚上”方案）

For minimal viable discoverability:

实现最小可行可发现性：

1. Define 1-3 Core App Intents (30 minutes)

1. 定义1-3个核心App Intents（30分钟）

swift

// Your app's most valuable actions
struct OrderCoffeeIntent: AppIntent { /* ... */ }
struct ReorderLastIntent: AppIntent { /* ... */ }
struct ViewOrdersIntent: AppIntent { /* ... */ }

swift

// 你的应用最有价值的操作
struct OrderCoffeeIntent: AppIntent { /* ... */ }
struct ReorderLastIntent: AppIntent { /* ... */ }
struct ViewOrdersIntent: AppIntent { /* ... */ }

2. Create AppShortcutsProvider (15 minutes)

2. 创建AppShortcutsProvider（15分钟）

swift

struct CoffeeAppShortcuts: AppShortcutsProvider {
    @AppShortcutsBuilder
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: OrderCoffeeIntent(),
            phrases: ["Order coffee in \(.applicationName)"],
            shortTitle: "Order",
            systemImageName: "cup.and.saucer.fill"
        )
        // Add 2-3 more shortcuts
    }
}

swift

struct CoffeeAppShortcuts: AppShortcutsProvider {
    @AppShortcutsBuilder
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: OrderCoffeeIntent(),
            phrases: ["Order coffee in \(.applicationName)"],
            shortTitle: "Order",
            systemImageName: "cup.and.saucer.fill"
        )
        // 添加2-3个更多快捷指令
    }
}

3. Index Top-Level Content (30 minutes)

3. 为顶级内容建立索引（30分钟）

swift

// Index most recent/important content only
func indexRecentOrders() {
    let recentOrders = try await OrderService.shared.recent(limit: 20)
    let items = recentOrders.map { createSearchableItem(from: $0) }
    CSSearchableIndex.default().indexSearchableItems(items)
}

swift

// 仅为最近/重要内容建立索引
func indexRecentOrders() {
    let recentOrders = try await OrderService.shared.recent(limit: 20)
    let items = recentOrders.map { createSearchableItem(from: $0) }
    CSSearchableIndex.default().indexSearchableItems(items)
}

4. Add NSUserActivity to Detail Screens (30 minutes)

4. 为详情页面添加NSUserActivity（30分钟）

swift

// In your detail view controllers/views
let activity = NSUserActivity(activityType: "com.app.viewOrder")
activity.isEligibleForSearch = true
activity.becomeCurrent()
self.userActivity = activity

swift

// 在你的详情视图控制器/视图中
let activity = NSUserActivity(activityType: "com.app.viewOrder")
activity.isEligibleForSearch = true
activity.becomeCurrent()
self.userActivity = activity

5. Test in Spotlight and Shortcuts (15 minutes)

5. 在Spotlight和快捷指令中测试（15分钟）

Open Shortcuts app → Search for your app → Verify shortcuts appear
Search Spotlight → Search for your content → Verify results
Invoke Siri → "Order coffee in [YourApp]" → Verify works

Total time: ~2 hours for basic discoverability

打开快捷指令应用 → 搜索你的应用 → 验证快捷指令是否出现
搜索Spotlight → 搜索你的内容 → 验证结果是否出现
调用Siri → "Order coffee in [你的应用名]" → 验证是否可用

总耗时：约2小时 实现基础可发现性

Anti-Patterns (What NOT to Do)

反模式（请勿这样做）

❌ ANTI-PATTERN 1: Implementing just App Intents without App Shortcuts

❌ 反模式1：仅实现App Intents而不添加App Shortcuts

Problem Users must manually configure shortcuts. Your app won't appear in Spotlight/Siri automatically.

Fix Always create AppShortcutsProvider with suggested phrases.

问题用户必须手动配置快捷指令。你的应用不会自动出现在Spotlight/Siri中。

解决方案 始终实现带推荐短语的AppShortcutsProvider。

❌ ANTI-PATTERN 2: Indexing everything in Core Spotlight

❌ 反模式2：在Core Spotlight中索引所有内容

Problem Indexing thousands of items causes poor performance and quota issues. Users get overwhelmed.

swift

// ❌ BAD: Index all 10,000 orders
let allOrders = try await OrderService.shared.all()

Fix Index selectively—recent items, favorites, frequently accessed.

swift

// ✅ GOOD: Index recent orders only
let recentOrders = try await OrderService.shared.recent(limit: 50)

问题索引数千个条目会导致性能下降和配额问题。用户会感到信息过载。

swift

// ❌ 错误：索引所有10000个订单
let allOrders = try await OrderService.shared.all()

解决方案 选择性索引——最近的条目、收藏项、频繁访问的内容。

swift

// ✅ 正确：仅索引最近的订单
let recentOrders = try await OrderService.shared.recent(limit: 50)

❌ ANTI-PATTERN 3: Generic intent titles and descriptions

❌ 反模式3：使用通用的intent标题和描述

Problem Spotlight displays these directly. Generic text confuses users.

swift

// ❌ BAD
static var title: LocalizedStringResource = "Action"
static var description = IntentDescription("Does something")

Fix Use specific, action-oriented language.

swift

// ✅ GOOD
static var title: LocalizedStringResource = "Order Coffee"
static var description = IntentDescription("Orders your favorite coffee for pickup")

问题 Spotlight会直接展示这些内容。通用文本会让用户困惑。

swift

// ❌ 错误
static var title: LocalizedStringResource = "Action"
static var description = IntentDescription("Does something")

解决方案 使用具体的、以行动为导向的语言。

swift

// ✅ 正确
static var title: LocalizedStringResource = "Order Coffee"
static var description = IntentDescription("Orders your favorite coffee for pickup")

❌ ANTI-PATTERN 4: Not educating users about shortcuts

❌ 反模式4：不向用户推广快捷指令

Problem Perfect implementation means nothing if users don't know it exists.

Fix Use

SiriTipView

to promote shortcuts in your app's UI.

swift

// Show tip after user places order
SiriTipView(intent: ReorderLastIntent(), isVisible: $showTip)

问题即使实现完美，如果用户不知道其存在也无济于事。

解决方案 使用

SiriTipView

在应用UI中推广快捷指令。

swift

// 用户下单后展示提示
SiriTipView(intent: ReorderLastIntent(), isVisible: $showTip)

❌ ANTI-PATTERN 5: Marking every screen as eligible for search

❌ 反模式5：将每个页面都标记为可搜索

Problem System gets confused about what's important. Low-quality suggestions.

swift

// ❌ BAD: Settings screen marked for prediction
activity.isEligibleForPrediction = true // Don't predict Settings!

Fix Only mark screens users would want to return to (content, not chrome).

swift

// ✅ GOOD: Mark content screens only
if order != nil {
    activity.isEligibleForPrediction = true
}

问题系统会对重要内容产生混淆。导致低质量的推荐。

swift

// ❌ 错误：设置页面被标记为可预测
activity.isEligibleForPrediction = true // 不要预测设置页面！

解决方案 仅标记用户可能想返回的页面（内容页，而非框架页）。

swift

// ✅ 正确：仅标记内容页
if order != nil {
    activity.isEligibleForPrediction = true
}

❌ ANTI-PATTERN 6: Forgetting to connect NSUserActivity to App Intents

❌ 反模式6：忘记将NSUserActivity与App Intents关联

Problem NSUserActivity and App Intents remain siloed. Lost integration opportunities.

Fix Use

appEntityIdentifier

to connect them.

swift

// ✅ GOOD: Connect activity to App Intent entity
activity.appEntityIdentifier = order.id.uuidString

问题 NSUserActivity和App Intents相互独立，错失集成机会。

解决方案 使用

appEntityIdentifier

将它们关联起来。

swift

// ✅ 正确：将活动与App Intent实体关联
activity.appEntityIdentifier = order.id.uuidString

Code Review Checklist

代码审查清单

When reviewing discoverability implementation, verify:

App Intents:

Intents have clear, action-oriented titles
Descriptions explain what the intent does
Parameter summaries use natural language phrasing
```
isDiscoverable = true
```
for public intents

App Shortcuts:

AppShortcutsProvider is implemented
Suggested phrases include
```
\(.applicationName)
```
Phrases are short and action-oriented
ShortcutTileColor matches app branding
3-5 core shortcuts defined (not too many)

Core Spotlight:

Only valuable content is indexed (not everything)
Unique identifiers are stable and persistent
Domain identifiers group related content
Attributes include title, description, keywords
Deletion logic exists (when content removed)

NSUserActivity:

Only high-value screens marked eligible
```
becomeCurrent()
```
called when screen appears
```
resignCurrent()
```
called when screen disappears
```
appEntityIdentifier
```
connects to App Intent entities
```
contentAttributeSet
```
provides rich metadata

User Education:

SiriTipView used to promote shortcuts
ShortcutsLink available in settings/help
Onboarding mentions Siri/Spotlight support

Testing:

Shortcuts appear in Shortcuts app
Siri recognizes suggested phrases
Spotlight returns app content
Activity continuation works (tap Spotlight result)

审查可发现性实现时，验证以下内容：

App Intents：

Intents有清晰的、以行动为导向的标题
描述解释了intent的作用
参数摘要使用自然语言表述
公开的intents设置了
```
isDiscoverable = true
```

App Shortcuts：

已实现AppShortcutsProvider
推荐短语包含
```
\(.applicationName)
```
短语简短且以行动为导向
ShortcutTileColor与应用品牌匹配
定义了3-5个核心快捷指令（不要太多）

Core Spotlight：

仅索引有价值的内容（而非所有内容）
唯一标识符稳定且持久
域标识符对相关内容进行分组
属性包含标题、描述、关键词
存在删除逻辑（内容移除时）

NSUserActivity：

仅标记高价值页面
页面出现时调用
```
becomeCurrent()
```
页面消失时调用
```
resignCurrent()
```
使用
```
appEntityIdentifier
```
关联到App Intent实体
```
contentAttributeSet
```
提供丰富的元数据

用户引导：

使用SiriTipView推广快捷指令
设置/帮助页面中提供ShortcutsLink
引导页提及Siri/Spotlight支持

测试：

快捷指令出现在快捷指令应用中
Siri能识别推荐短语
Spotlight返回应用内容
活动续传正常（点击Spotlight结果）

Related Skills

Resources

资源

WWDC: 260, 275, 2022-10170

Docs: /appintents/making-your-app-s-functionality-available-to-siri, /corespotlight

Skills: axiom-app-intents-ref, axiom-app-shortcuts-ref, axiom-core-spotlight-ref

Remember Discoverability isn't one API—it's a strategy. Feed the system metadata across App Intents, App Shortcuts, Core Spotlight, and NSUserActivity. Let iOS decide when to surface your app based on context and user behavior.

WWDC: 260, 275, 2022-10170

文档: /appintents/making-your-app-s-functionality-available-to-siri, /corespotlight

技能: axiom-app-intents-ref, axiom-app-shortcuts-ref, axiom-core-spotlight-ref

记住可发现性不是单一API的问题——而是一种策略。通过App Intents、App Shortcuts、Core Spotlight和NSUserActivity向系统提供元数据。让iOS根据上下文和用户行为决定何时展示你的应用。

axiom-app-discoverability

Original

Translation

App Discoverability

应用可发现性

Overview

概述

When to Use This Skill

何时使用此技能

The 6-Step Discoverability Strategy

6步可发现性策略

Step 1: Add App Intents

步骤1：添加App Intents

Step 2: Add App Shortcuts with Suggested Phrases

步骤2：添加带推荐短语的App Shortcuts

Step 3: Expose Searchable Content via Core Spotlight

步骤3：通过Core Spotlight暴露可搜索内容

Step 4: Use NSUserActivity for High-Value Screens

步骤4：为高价值页面使用NSUserActivity

Step 5: Provide Correct Intent Metadata

步骤5：提供正确的Intent元数据

❌ DON'T: Generic or unclear

❌ 错误做法：通用或模糊

✅ DO: Specific, action-oriented

✅ 正确做法：具体、以行动为导向

Step 6: Usage-Based Boosting

步骤6：基于使用情况的优先推荐

Decision Tree: Which API for Which Use Case

决策树：不同场景对应哪个API

Quick Reference Table

快速参考表

Quick Implementation Pattern ("One Evening" Approach)

快速实现模式（“一个晚上”方案）

1. Define 1-3 Core App Intents (30 minutes)

1. 定义1-3个核心App Intents（30分钟）

2. Create AppShortcutsProvider (15 minutes)

2. 创建AppShortcutsProvider（15分钟）

3. Index Top-Level Content (30 minutes)

3. 为顶级内容建立索引（30分钟）

4. Add NSUserActivity to Detail Screens (30 minutes)

4. 为详情页面添加NSUserActivity（30分钟）

5. Test in Spotlight and Shortcuts (15 minutes)

5. 在Spotlight和快捷指令中测试（15分钟）

Anti-Patterns (What NOT to Do)

反模式（请勿这样做）

❌ ANTI-PATTERN 1: Implementing just App Intents without App Shortcuts

❌ 反模式1：仅实现App Intents而不添加App Shortcuts

❌ ANTI-PATTERN 2: Indexing everything in Core Spotlight

❌ 反模式2：在Core Spotlight中索引所有内容

❌ ANTI-PATTERN 3: Generic intent titles and descriptions

❌ 反模式3：使用通用的intent标题和描述

❌ ANTI-PATTERN 4: Not educating users about shortcuts

❌ 反模式4：不向用户推广快捷指令

❌ ANTI-PATTERN 5: Marking every screen as eligible for search

❌ 反模式5：将每个页面都标记为可搜索

❌ ANTI-PATTERN 6: Forgetting to connect NSUserActivity to App Intents

❌ 反模式6：忘记将NSUserActivity与App Intents关联

Code Review Checklist

代码审查清单

Related Skills

相关技能

Resources

资源