用自托管 Umami 给 iOS App 加分析——轻量、隐私友好的方案

原文来源：Hjerpbakk - Using self-hosted Umami for iOS app analytics — 利用已有的自托管 Umami 实例，通过开源 Swift 包给 iOS 应用添加轻量级用户分析。

独立开发者在做 App 的时候，总会遇到一个纠结的问题：要不要加分析功能？

加吧——Google Analytics、Firebase、Mixpanel 这些 SDK 一个比一个重，而且还得弹 IDFA 授权框，用户一看就烦，转化率直接打折扣。不加吧——完全不知道用户怎么用你的 App，哪些功能受欢迎、哪些地方卡住了，两眼一抹黑。

这篇文章介绍的方案，可能是独立开发者最理想的选择：用自托管的 Umami 实例给 App 做分析，轻量、隐私友好、不依赖第三方。

Umami 是什么？

Umami 是一个开源的网站分析工具，用来替代 Google Analytics。它自托管在自己的服务器上，数据完全由你掌控，不需要同意弹窗、不需要 Cookie 声明。很多独立开发者用它来追踪自己的网站流量。

但很少有人知道——Umami 的追踪 API 也可以直接从 App 调用，不需要浏览器、不需要网页。这就意味着你可以用同一套分析系统同时追踪网站和 App，统一 Dashboard。

集成三步走

Hjerpbakk 做了一个开源 Swift 包 umami-swift，把整个集成过程压缩到了 3 步。

第一步：把包加到 Xcode 项目里

在 Xcode 中，File → Add Package Dependencies，粘贴仓库地址：

https://github.com/hjerpbakk/umami-swift

版本规则设为从 1.3.0 开始的最新大版本。

如果你的项目用 Package.swift 管理依赖，在 dependencies 里加上：

.package(url: "https://github.com/hjerpbakk/umami-swift", from: "1.3.0")

然后在 target 中加入 Umami 产品。

第二步：在 Umami 里为 App 创建一个"网站"

在 Umami Dashboard 中，添加一个新网站。这里有一个小技巧：由于 App 没有域名，你需要手动编一个稳定的伪域名，比如 myapp.ios。Umami 用这个来标识不同的数据源。

添加后，Umami 会生成一个 websiteId。记下来，下一步要用。

第三步：在 App 启动时配置并初始化

import Umami
 
Umami.configure(
    websiteId: "<你的-website-id>",
    host: "myapp.ios",
    baseURL: URL(string: "https://你的-umami-域名")!
)

这里三个参数分别是：

• websiteId：上一步从 Umami Dashboard 复制下来的
• host：跟你在 Umami 里填的伪域名一致
• baseURL：你的 Umami 实例地址

配置完成后，Umami 会自动发送一个 app_started 事件和一个页面浏览记录（/）。

第四步：跟踪事件和页面

集成完基础配置后，你可以在 App 的各个关键位置添加追踪代码：

// 追踪自定义事件
Umami.track("game_started")
Umami.track("level_completed", ["level": 7, "won": true])
 
// 追踪页面/屏幕浏览
Umami.screen("settings")
Umami.screen("profile")
 
// 用户选择退出时
Umami.setEnabled(false)

事件支持附带自定义数据（字典形式），方便做更细粒度的分析。

技术原理

Umami 的网页追踪脚本实际上是调用两个端点：/api/send 和 /api/batch。这个 Swift 包直接调用相同的端点，发送 JSON 请求体，不需要 API Key——Umami 通过 website-id 字段来区分数据来源。

Swift 包还特意设置了一个不会触发 Umami 机器人过滤的 User-Agent，确保 App 的数据能正常计入。

唯一用户识别——不走 IDFA

这个方案最吸引人的地方在于它完全绕过了 IDFA。

Apple 从 iOS 14.5 开始强制要求用户授权才能使用 IDFA，导致很多 App 的分析数据大打折扣。而这个方案的做法很简单：

• 每次启动时生成一个随机 UUID
• 只存在内存里，不持久化
• 每天重置一次
• 每个启动会话对应一个独立访客（最长存活期 1 天）

这和 Umami 网页版无 Cookie 的追踪方式是一致的。它不需要弹 IDFA 授权框，不需要写隐私合规说明，同时也保护了用户的隐私。

为什么值得一试

对于独立开发者来说，这个方案有以下几个明确的好处：

不需要额外的 IDFA 弹窗。 分析数据来自 Umami 实例的自定义端到端通信，不走 Apple 的 IDFA 通道，因此不需要征得用户授权。这对保持 App 良好的用户体验很重要——少弹一个窗，多留一个用户。

自托管，数据完全在你自己手里。 Umami 部署在你的服务器上（推荐 Fly.io + Supabase 组合），所有用户数据不会经过任何第三方分析平台。对隐私敏感的 App 来说，这是个很大的加分项。

没有广告拦截器干扰。 iOS 的 Safari 内容拦截器只影响 WebView，不影响原生 App。系统级的 DNS/VPN 拦截器最多看到你的 Umami 域名，看不到具体路径。而且自托管的域名不在任何拦截名单上。

轻量无负担。 比 Google Analytics 的 SDK 小得多，不需要额外依赖 CocoaPods 或 SPM 的大型框架，代码量也只有几十行配置。

和网站共享一个 Dashboard。 如果你的网站也用了 Umami，App 的数据会显示在同一个仪表盘上。App 在 Umami 中看起来像一个"网站"，有应用图标和页面浏览记录。不过需要注意，因为 App 的"域名"是伪域名（如 .ios），Umami 默认的 favicon 抓取服务无法解析。可以在 Umami 的 FAVICON_URL 环境变量中配置一个 Cloudflare Worker 来返回 App 图标——不过这只是装饰性的，不影响数据分析。

小结

如果你已经在用 Umami 分析网站流量，那再加一个 App 分析的成本几乎是零——安装一个开源 Swift 包，配置十几行代码就搞定了。如果你还没用 Umami，那它本身也是一个比 Google Analytics 更轻量、更隐私友好的替代方案。

对独立开发者来说，这是一个几乎最优的分析方案：自托管意味着可控，不依赖 IDFA 意味着不需要降低用户体验，轻量级意味着不影响 App 性能。推荐每个做 iOS App 的开发者都试试。