Enhanced suggestions for your journaling app
System Frameworks 进阶 20m

增强你的日记应用建议能力

Enhanced suggestions for your journaling app

2024年6月10日

在 Apple 官方观看视频

一句话判断

iOS 18 的 Journaling Suggestions API 新增了心理健康状态（State of Mind）、跑步运动记录、非 Apple 应用的媒体播放和反思提示（Reflection Prompts）四类数据源，你的日记应用可以获得更丰富的用户生活上下文。

这场 Session 讲了什么

Journaling Suggestions API 帮助用户反思生活。iOS 能感知用户生活中的重要事件——拍的照片、锻炼记录、去过的地方——然后作为日记写作的起点建议给用户。这个 API 在推出几个月内就获得了大量应用采纳。

iOS 18 带来了多项增强。首先是完整的横屏支持——选择器会自动跟随应用的方向设置，内容预览界面也利用了更宽的屏幕空间来展示更大的资产。

核心更新在四类新的资产类型。State of Mind（心理状态）让日记应用获取用户在 Health 中记录的情绪数据，包括瞬时情绪和每日心情，附带效价（Valence）、标签（Labels）和关联因素（Associations）。Motion Activity 新增了跑步和混合走路/跑步两种运动类型，覆盖没有 Apple Watch 但经常运动的用户。Generic Media 支持用户在非 Apple 应用中听的音乐和播客。Reflection Prompts 是之前只在 Apple Journal 中提供的反思提示，现在对所有开发者开放。

值得深挖的点

State of Mind 集成的隐私和体验设计

State of Mind 是 Health 在 iOS 17 引入的功能，让用户记录自己的情绪状态。研究显示，表达性写作（expressive writing）对心理健康有积极影响——无论是面对负面情绪还是品味正面情绪。

技术层面，State of Mind 资产类型是 JournalingSuggestion.StateOfMind，包含一个完整的 HKStateOfMind 样本：Valence 表示情绪在正面到负面轴上的位置，Labels 描述具体感受（如平静、满足、焦虑），Associations 描述可能的触发因素（如家庭、工作、健身）。资产还附带图片 URL、明暗模式配色和时间戳。

用户体验层面有一个重要细节：老用户升级到 iOS 18 后会在建议面板看到一个提示，引导他们开启 State of Mind 内容分享。新用户则可以在 onboarding 中开启。开发者不需要做额外引导，系统已经处理好了。所有情绪状态都值得记录——不论效价高低，这也是为什么 API 不会对数据进行任何过滤或评判。

Reflection Prompts 的开放

Reflection Prompts 是一类特殊的建议——它不是基于用户活动的数据，而是一个开放性的写作提示，比如”今天什么让你微笑？“或”你最近有什么新的发现？“。之前这只在 Apple 自家的 Journal 应用中可用，iOS 18 向所有第三方日记应用开放了。

这是一个重要的信号：Apple 在逐步把 Journal 应用的差异化能力通过 API 开放出来。对于日记应用开发者来说，Reflection Prompts 提供了一种不需要用户活动数据就能激发写作的方式，降低了用户开始写日记的门槛。

代码片段

处理 State of Mind 资产

// 从建议中获取 State of Mind 内容
func handleStateOfMind(from suggestion: JournalingSuggestion) {
    // 检索所有 State of Mind 类型的资产
    let stateOfMindItems = suggestion.content.compactMap { item in
        item as? JournalingSuggestion.StateOfMind
    }
    
    for item in stateOfMindItems {
        // HKStateOfMind 样本包含完整的情绪数据
        let sample = item.stateOfMind
        let valence = sample.valence  // 情绪效价
        let labels = sample.labels     // 情绪标签
        let associations = sample.associations  // 关联因素
        
        // 显示图标
        // AsyncImage(url: item.iconURL)
        
        // 用效价生成简单的表情符号
        let emoji = getEmotionEmoji(valence: valence)
        print("今日心情: \(emoji)")
    }
}

// 根据效价生成表情符号
func getEmotionEmoji(valence: Double) -> String {
    if valence > 0.3 {
        return "😊"  // 积极
    } else if valence < -0.3 {
        return "😔"  // 消极
    } else {
        return "😐"  // 中性
    }
}

坑点：State of Mind 数据需要用户在 Health 应用中主动记录过才能出现在建议中。如果用户从未使用过这个功能，你的应用不会收到任何 State of Mind 建议。

处理 Motion Activity 的新运动类型

// iOS 18 新增跑步和混合运动类型
func handleMotionActivity(from suggestion: JournalingSuggestion) {
    let motionItems = suggestion.content.compactMap { item in
        item as? JournalingSuggestion.MotionActivity
    }
    
    for item in motionItems {
        let movementType = item.movementType
        let label = getMotionActivityLabel(type: movementType)
        
        // 步数 + 运动类型 + 图标 + 时间戳
        print("运动记录: \(label), 步数: \(item.stepCount)")
        // AsyncImage(url: item.iconURL)
    }
}

// 解析新的运动类型
func getMotionActivityLabel(type: MovementType) -> String {
    switch type {
    case .walking:
        return "步行"
    case .running:
        return "跑步"
    case .walkingAndRunning:
        return "走跑混合"
    @unknown default:
        return "运动"
    }
}

横屏支持（无需额外代码）

// iOS 18 中 Journaling Suggestions 选择器自动支持横屏
// 只需要确保你的应用支持横屏方向即可

// 在 Info.plist 或项目设置中：
// Supported interface orientations 包含 Landscape left/right
// 选择器会自动跟随应用方向

// 内容预览界面会利用更宽的空间展示更大的资产
// 无需额外适配代码

最佳实践

如果你的日记应用已经集成了 Journaling Suggestions API，iOS 18 的升级几乎不需要改代码——横屏支持自动生效，新的资产类型作为 suggestion.content 中的新类型出现，用 compactMap 检查即可。建议优先接入 State of Mind，它与日记写作的核心场景高度契合。Motion Activity 的跑步类型覆盖了没有 Apple Watch 的运动用户群，值得支持。Reflection Prompts 的接入门槛最低，能立即提升应用的写作引导体验。处理这些数据时记住：所有情绪都是合法的记录对象，不要在你的 UI 中对效价做任何评判性展示。

还有什么值得关注

  • Generic Media 资产让用户可以记录在第三方 App 中听到的音乐和播客
  • Reflection Prompts 之前是 Apple Journal 的独有功能，开放给所有开发者是重要的平台策略变化
  • 建议相关的隐私控制和用户开关在 Journaling Suggestions Settings 中管理，开发者应熟悉这些开关的位置
WWDC 2024