Add intelligence to your widgets

Highlight

iOS 15 引入了 Widget Suggestions 和增强的 Smart Rotate 机制，开发者通过三个 API（INRelevantShortcut、TimelineEntryRelevance、INInteraction）即可让 widget 在正确的时间自动出现在用户的 Smart Stack 中，无需用户手动添加。

核心内容

从被动等待到主动出现

以前，widget 被用户添加到主屏幕后就固定在那里。用户需要主动滑动查找，系统也不会根据场景自动切换。这意味着很多 widget 在大部分时间都处于”沉睡”状态，用户甚至不知道自己已经安装了某个可能有用的 widget。

iOS 15 改变了这个模式。Widget Suggestions 允许系统根据用户行为和应用提供的信息，将 widget 临时插入到 Smart Stack 中。Smart Rotate 则让系统能够在多个 widget 之间自动切换，展示当前最相关的信息。

三种让 widget 变聪明的方式

Apple 提供了三个独立的 API，开发者可以按需组合使用：

1. INRelevantShortcut：应用主动告知系统”现在有一个值得展示的信息”，系统会临时将 widget 插入 Smart Stack
2. TimelineEntryRelevance：widget 为每个时间线条目打分，告诉系统这个条目有多值得展示
3. INInteraction：应用记录用户查看特定信息的行为，系统学习规律后自动推荐

这三个 API 可以单独使用，也可以组合使用。核心思路都是让 widget 从”被动等待”变成”主动出现”。

详细内容

用 INRelevantShortcut 实现 Widget Suggestions（09:14）

当应用检测到某个高价值场景时，可以捐赠一个 INRelevantShortcut，让系统将对应的 widget 临时插入到用户的 Smart Stack 中。

// 用户刚刚完成一笔消费，捐赠相关 shortcut
var relevantShortcuts: [INRelevantShortcut] = []

let intent = ViewRecentPurchasesIntent()
intent.card = Card(identifier: card.identifier)
intent.category = .all

if let shortcut = INShortcut(intent: intent) {
    let relevantShortcut = INRelevantShortcut(shortcut: shortcut)
    relevantShortcut.shortcutRole = .information
    relevantShortcut.widgetKind = "CardRecentPurchasesWidget"

    let dateProvider = INDateRelevanceProvider(
        start: Date(),
        end: Date(timeIntervalSinceNow: 1800)
    )
    relevantShortcut.relevanceProviders = [dateProvider]

    relevantShortcuts.append(relevantShortcut)
}

INRelevantShortcutStore.default.setRelevantShortcuts(relevantShortcuts) { error in
    if let error = error {
        print("Failed to set relevant shortcuts. \(error)")
    } else {
        print("Relevant shortcuts set.")
    }
}

关键点：

• shortcutRole 设为 .information 表示这个 widget 展示的是信息类内容
• widgetKind 必须匹配 widget 的 kind 字符串
• INDateRelevanceProvider 指定了 30 分钟的有效期，过期后系统会自动移除 widget
• 通过替换整个 relevantShortcuts 数组来更新或撤销之前的捐赠

用 TimelineEntryRelevance 实现 Smart Rotate（12:35）

对于已经存在于 Smart Stack 中的 widget，可以通过 TimelineEntryRelevance 让系统知道什么时候应该旋转到这个 widget。

struct CardRecentPurchasesEntry: TimelineEntry {
    let date: Date
    let relevance: TimelineEntryRelevance?
    let card: IntentCard?
    let category: PurchaseCategory
}

let relevance = TimelineEntryRelevance(score: 16.29, duration: 1800)
let entry = CardRecentPurchasesEntry(
    date: Date(),
    relevance: relevance,
    card: card,
    category: category
)

关键点：

• score 是相对分数，越高表示越值得展示。正数表示可旋转，0 表示跳过
• duration 指定分数的有效期（秒），过期后系统视为 0
• 分数的绝对值不重要，重要的是同一 widget 所有时间线条目之间的相对大小
• 设置 duration: 0 表示分数一直有效，直到下一个提供 relevance 的条目

用 INInteraction 让系统学习用户习惯（17:01）

当用户在应用中查看与 widget 内容相关的信息时，捐赠一个 INInteraction，系统会学习用户的行为模式，在预测用户可能再次查看时自动推荐 widget。

.onAppear {
    let intent = ViewRecentPurchasesIntent()
    intent.card = Card(identifier: card.id.uuidString, displayString: card.name)
    intent.category = .all

    let interaction = INInteraction(intent: intent, response: nil)
    interaction.donate { error in
        if let error = error {
            print(error.localizedDescription)
        }
    }
}

关键点：

• 捐赠的时机很重要：在用户查看与 widget 内容对应的信息时捐赠
• 系统会收集多个捐赠数据点，建立行为模型
• 捐赠的 intent 必须与 widget 配置使用的 intent 完全一致
• 这种方式不需要应用主动判断”什么时候该展示”，由系统根据历史数据决定

配置 Intent 定义文件

使用 INRelevantShortcut 和 INInteraction 前，需要在 Intent Definition File 中确保：

1. “Intent is eligible for Siri Suggestions” 已勾选
2. 创建了包含必要参数的 Supported Combination

核心启发

1. 做什么：为电商/支付类应用添加”最近交易”widget，在用户完成支付后自动弹出

   • 为什么值得做：结合 INRelevantShortcut + INDateRelevanceProvider，用户在消费后 30 分钟内能在主屏幕直接看到交易详情，无需打开应用
   • 怎么开始：创建一个 IntentConfiguration widget，在用户完成支付回调中捐赠 INRelevantShortcut

2. 做什么：为健身应用添加训练状态 widget，根据当前训练强度自动切换展示

   • 为什么值得做：利用 TimelineEntryRelevance 的 score 机制，高强度训练时 widget 自动跳到 Smart Stack 顶部，低强度时隐藏
   • 怎么开始：在 getTimeline 中根据训练数据计算 score，训练强度越高 score 越高

3. 做什么：为新闻/内容类应用添加”继续阅读”widget，学习用户阅读习惯

   • 为什么值得做：通过 INInteraction 捐赠用户阅读行为，系统会在用户通常阅读的时间自动推荐 widget
   • 怎么开始：在文章详情页 onAppear 时捐赠 INInteraction，使用文章分类作为 intent 参数

4. 做什么：为出行应用添加行程 widget，航班/火车出发前自动出现在主屏幕

   • 为什么值得做：INRelevantShortcut 配合 INDateRelevanceProvider，在行程开始前 2 小时到结束后 1 小时自动展示
   • 怎么开始：在行程数据更新时计算起止时间，捐赠对应时间窗口的 relevant shortcut

关联 Session

• What’s new in WidgetKit — WidgetKit 基础更新和 iOS 15 新特性
• Meet the UIKit button system — iOS 15 UIKit 控件改进，与 widget 设计相关
• Build a workout app for Apple Watch — Apple Watch 应用与 widget 数据联动
• What’s new in SwiftUI — SwiftUI 在 iOS 15 的更新，可用于 widget 开发