name: 分析开发 description: 上下文感知路由到Anytype iOS分析系统。在添加分析事件、跟踪用户路由或使用AnytypeAnalytics和AnalyticsConstants时使用。

分析开发专家（智能路由器）

目的

上下文感知路由到Anytype iOS分析系统。帮助您添加分析事件、跟踪用户路由，并维护一致的分析模式。

何时自动激活

处理分析事件或AnytypeAnalytics时
添加路由跟踪或事件属性时
修改AnalyticsConstants.swift或AnytypeAnalytics+Events.swift时
关键词：分析、路由跟踪、logEvent、AnytypeAnalytics、AnalyticsConstants

🚨 关键规则（切勿违反）

始终在AnalyticsConstants.swift中定义路由枚举 - 切勿硬编码路由字符串
始终使用现有属性键 - 使用AnalyticsEventsPropertiesKey.*
切勿使用字符串字面量作为路由 - 使用带.rawValue的类型化枚举
始终对可选属性使用.compactMapValues { $0 } - 移除nil值
始终跟踪路由上下文 - 了解用户如何到达某个功能

📋 快速工作流

添加新分析事件

定义路由枚举（如果需要）：添加到AnalyticsConstants.swift
添加事件方法：添加到AnytypeAnalytics+Events.swift
在代码中使用：调用AnytypeAnalytics.instance().logYourEvent(...)

为现有屏幕添加路由跟踪

定义路由枚举：将YourFeatureRoute添加到AnalyticsConstants.swift
更新数据模型：添加route: YourFeatureRoute?参数
通过层次结构传递：Coordinator → View → ViewModel
更新分析调用：将路由传递给现有的日志方法

🎯 常见模式

模式1：屏幕分析（onAppear）

// ViewModel
final class HomeWidgetsViewModel {
    let route: HomeWidgetRoute?

    func onAppear() {
        AnytypeAnalytics.instance().logScreenWidget(route: route)
    }
}

// 分析方法（AnytypeAnalytics+Events.swift）
func logScreenWidget(route: HomeWidgetRoute?) {
    logEvent("ScreenWidget", withEventProperties: [
        AnalyticsEventsPropertiesKey.route: route?.rawValue
    ].compactMapValues { $0 })
}

// 路由枚举（AnalyticsConstants.swift）
enum HomeWidgetRoute: String, Hashable, Codable {
    case home = "Home"
    case space = "Space"
    case appLaunch = "AppLaunch"
}

模式2：按钮点击分析

// ViewModel
func onTapShare() {
    AnytypeAnalytics.instance().logClickShare(type: .link, route: .settings)
    output?.onShareSelected()
}

// 分析方法
func logClickShare(type: ShareType, route: ShareRoute) {
    logEvent("ClickShare", withEventProperties: [
        AnalyticsEventsPropertiesKey.type: type.rawValue,
        AnalyticsEventsPropertiesKey.route: route.rawValue
    ])
}

模式3：多空间事件

func logCreateObject(objectType: AnalyticsObjectType, spaceId: String, route: AnalyticsEventsRouteKind) {
    logEvent("CreateObject", spaceId: spaceId, withEventProperties: [
        AnalyticsEventsPropertiesKey.objectType: objectType.analyticsId,
        AnalyticsEventsPropertiesKey.route: route.rawValue
    ])
}

🗂️ 分析文件结构

关键文件

AnalyticsConstants.swift - 所有路由枚举、属性键（400+行）
AnytypeAnalytics+Events.swift - 所有事件方法（1,500+行）
Converters/ - 领域类型到分析值转换器

路由枚举位置

始终添加到AnalyticsConstants.swift，按功能分组：

// 小部件相关路由
enum AnalyticsWidgetRoute: String {
    case addWidget = "AddWidget"
    case inner = "Inner"
}

enum HomeWidgetRoute: String, Hashable, Codable {
    case home = "Home"
    case space = "Space"
    case appLaunch = "AppLaunch"
}

// 屏幕导航路由
enum SettingsSpaceShareRoute: String {
    case settings = "Settings"
    case navigation = "Navigation"
    case chat = "Chat"
}

📈 路由跟踪实现

分步指南：为屏幕添加路由

示例：为ScreenWidget添加路由跟踪

定义路由枚举（AnalyticsConstants.swift）：

enum HomeWidgetRoute: String, Hashable, Codable {
    case home = "Home"            // 主页按钮点击
    case space = "Space"          // 空间选择
    case appLaunch = "AppLaunch"  // 应用启动
}

更新数据模型：

struct HomeWidgetData: Hashable {
    let spaceId: String
    let route: HomeWidgetRoute?  // 添加路由参数
}

通过视图层次结构传递：

// Coordinator
HomeWidgetsView(info: info, output: model, route: data.route)

// View
HomeWidgetsViewModel(info: info, output: output, route: route)

更新分析调用：

// ViewModel
func onAppear() {
    AnytypeAnalytics.instance().logScreenWidget(route: route)
}

// 分析方法
func logScreenWidget(route: HomeWidgetRoute?) {
    logEvent("ScreenWidget", withEventProperties: [
        AnalyticsEventsPropertiesKey.route: route?.rawValue
    ].compactMapValues { $0 })
}

在导航点设置路由：

// 主页按钮
let data = HomeWidgetData(spaceId: spaceId, route: .home)

// 空间选择
let data = HomeWidgetData(spaceId: spaceId, route: .space)

// 应用启动
let data = HomeWidgetData(spaceId: spaceId, route: .appLaunch)

🔧 常见属性键

位于AnalyticsEventsPropertiesKey中：

键	用法	示例
`route`	导航上下文	`.home`, `.navigation`, `.widget`
`type`	主要分类	`.image`, `.video`, `.file`
`objectType`	对象类型ID	`type.analyticsType.analyticsId`
`spaceId`	空间标识符	`document.spaceId`
`count`	数量值	项目数量
`format`	数据格式	文件格式、日期格式

⚠️ 常见错误

❌ 硬编码路由字符串

// 错误
AnytypeAnalytics.instance().logScreenWidget(route: "Home")

// 正确
AnytypeAnalytics.instance().logScreenWidget(route: .home)

❌ 路由枚举放在错误文件中

// 错误 - 在功能文件中定义
enum HomeWidgetRoute: String {
    case home = "Home"
}

// 正确 - 在AnalyticsConstants.swift中定义

❌ 缺少compactMapValues

// 错误 - 会将nil值包含为NSNull
[AnalyticsEventsPropertiesKey.route: route?.rawValue]

// 正确 - 移除nil值
[AnalyticsEventsPropertiesKey.route: route?.rawValue].compactMapValues { $0 }

❌ 使用字符串字面量作为属性键

// 错误
["route": route.rawValue]

// 正确
[AnalyticsEventsPropertiesKey.route: route.rawValue]

🔍 查找现有模式

# 搜索现有事件
rg "logEvent.*EventName" Anytype/Sources/Analytics/

# 查找路由枚举
rg "enum.*Route.*String" Anytype/Sources/Analytics/AnalyticsConstants.swift

# 查找属性使用
rg "AnalyticsEventsPropertiesKey\." Anytype/Sources/Analytics/

# 查找屏幕分析
rg "func logScreen" Anytype/Sources/Analytics/AnytypeAnalytics+Events.swift

📚 完整文档

完整指南：Anytype/Sources/PresentationLayer/Common/Analytics/ANALYTICS_PATTERNS.md

涵盖以下内容：

分析系统架构
所有分析模式（用户操作、屏幕导航、内容创建）
路由上下文跟踪最佳实践
平台特定考虑
测试分析事件
添加参数的迁移模式
完整示例和代码片段

✅ 工作流检查清单

添加分析时：

[ ] 路由枚举添加到AnalyticsConstants.swift
[ ] 事件方法添加到AnytypeAnalytics+Events.swift
[ ] 使用现有属性键（AnalyticsEventsPropertiesKey.*）
[ ] 可选属性使用.compactMapValues { $0 }
[ ] 路由通过视图层次结构传递（如果跟踪导航）
[ ] 无硬编码字符串用于路由或属性键
[ ] 遵循现有命名约定（PascalCase事件、camelCase属性）

🔗 相关技能和文档

ios-dev-guidelines → IOS_DEVELOPMENT_GUIDE.md - 用于传递分析数据的MVVM/Coordinator模式
code-generation-developer → 理解构建系统
design-system-developer → 跟踪UI交互

导航：这是一个智能路由器。对于深度模式和示例，始终参考ANALYTICS_PATTERNS.md。