HN 日本語サマリー

← 一覧へ戻る
プログラミング

セルフホスト型UmamiをiOSアプリ分析に利用する

Using self-hosted Umami for iOS app analytics (hjerpbakk.com)

51 pointsby Sankra7 コメント

要約

この記事では、セルフホスト型のWeb分析ツールUmamiを、IDFAプロンプトやサードパーティによるデータ収集を避けたいiOSアプリの分析に利用する方法を紹介しています。開発者は、軽量なSwiftパッケージ`umami-swift`を作成し、アプリをUmami上でウェブサイトとして登録することで、訪問者数や画面表示数などをWebサイトと同様のダッシュボードで追跡できるようになります。

全文翻訳

セルフホスト型UmamiをiOSアプリの分析に利用する

2026年7月14日 7分で読める

Umamiをセルフホストしているので、重い分析SDKやIDFAプロンプト、あるいは第三者にデータを収集されることなく、アプリでも同様の体験を求めていました。これを実現するために、小規模なオープンソースSwiftパッケージumami-swiftを作成しました。これにより、実際のウェブサイトと同じダッシュボードで、訪問者数やセッション数を得ることができます。

私のUmamiインスタンスにアプリも追加された

各アプリはUmamiでウェブサイトとして登録され、実際のウェブサイトと並んで、アプリのアイコン付きでウェブサイトリストに表示されます。

[画像: Simplest Workout TrackerやPantelappenのようなアプリが、実際のウェブサイトと並んでUmamiのウェブサイトリストに表示されており、各アプリは実際のアイコンを表示している]

アプリの概要はウェブサイトの概要と全く同じで、訪問者数、セッション数、閲覧数が同じようにカウントされます。

[画像: Simplest Workout TrackerのUmami概要画面。過去24時間で5人の訪問者、6回のセッション、42回の閲覧が表示されている]

アプリの画面はページとして報告されます。私のワークアウトトラッカーSimplest Workout Trakcerでは、カレンダー、年間サマリー、設定シート、ワークアウト記録シートがそれぞれ表示され、ページリストには人々が実際にアプリのどの部分を使用しているかが示されます。

[画像: ワークアウトトラッカーのUmamiページリスト。/settings, /summary, /calendar, /log-workoutなどの画面がパスとして訪問者数とともにリストされている]

実装方法

[画像: umami-swiftを搭載したiOSアプリが、HTTPS経由でイベントをFly.io上のUmamiコンテナに直接送信し、Supabaseに書き込んでいる。ウェブサイトで使用されるCloudflare Workerはスキップされている]

umami-swiftは、依存関係のないオープンソースのSwiftパッケージです。公開APIは意図的に小さくされています。

import Umami

// 起動時:
Umami.configure(
    websiteId: "your-website-id",
    host: "cardgame.ios",
    baseURL: URL(string: "https://your-umami-host")!
)

// どこからでも:
Umami.track("game_started")
Umami.track("level_completed", ["level": 7, "won": true])

// ユーザーが別の画面に移動したとき:
Umami.screen("settings")

// オプトアウト:
Umami.setEnabled(false)

configureはウェブサイトIDとホスト文字列を受け取ります。ホストはUmamiでウェブサイトを追加する際に指定するドメインです。アプリには実際のドメインがないため、simplestworkouttracker.iosのような疑似ドメインを使用しています。baseURLは、前の投稿で触れたFlyマシンであるhttps://hjerpbakk-analytics.fly.devに設定しました。Umamiを実行している他の人は、各自のインスタンスを指すことになります。設定時には、起動時のページビューとapp_startedイベントもキューイングされるため、追加のコードなしで起動がUmamiの概要に含まれます。

trackは、追加データを含む名前付きイベントを送信します。screenは、名前付き画面のページビューを送信します。どちらもディスクにキューイングされ、バッチで送信されるため、ネットワークがない状態での起動でも何も失われず、UIが分析のために待たされることはありません。

アプリへの追加方法

自分のアプリに追加するには、いくつかの手順が必要です。

  1. Xcodeで、File → Add Package Dependencies を選択し、https://github.com/hjerpbakk/umami-swift を貼り付け、ルールを Up to Next Major Version の 1.3.0 に設定し、Umami プロダクトをアプリターゲットに追加します。Package.swift プロジェクトの場合は、dependencies に .package(url: "https://github.com/hjerpbakk/umami-swift", from: "1.3.0") を、ターゲットに Umami プロダクトを追加します。

  2. Umamiダッシュボードで、アプリ用の新しいウェブサイトを追加します。アプリには実際のドメインがないため、myapp.ios のような安定した疑似ドメインを付け、生成されるウェブサイトIDをコピーします。

  3. アプリの init (または application(_:didFinishLaunchingWithOptions:)) から、起動時に一度 Umami.configure を呼び出します。ウェブサイトID、Umamiで入力したのと同じドメインを host として、そして自身のUmamiインスタンスを baseURL として渡します。

    Umami.configure(
       websiteId: "<your-website-id>",
       host: "myapp.ios",
       baseURL: URL(string: "https://your-umami-host")!
    )
    
  4. アプリを実行し、Umamiダッシュボードでそのウェブサイトを開きます。app_started イベントが数秒以内に表示され、ビジターIDが付与されていれば、イベントが流れていることが確認できます。

これで統合は完了です。

この記事の残りの部分は、すべてがどのように機能するかの詳細です。

同じバックエンドのための異なるクライアント

Umamiのトラッキングスクリプトは2つのエンドポイントと通信します: 単一イベント用の /api/send と、複数のイベント用の /api/batch です。どちらもJSONボディを受け取り、APIキーや署名付きリクエストは要求しません。Umamiは、送信元ではなく、ペイロード内の website-id によってウェブサイトを識別します。

したがって、Swiftアプリはブラウザやスクリプトタグなしで、同じエンドポイントに直接呼び出すことができます。トラッキングスクリプトが生成するものと同じ形状のJSONを送信し、Umamiのボットフィルターに引っかからないUser-Agentを使用します。前の投稿で触れたハニーポットはアプリにも適用されます。ボットのように見えるリクエストは200を返され、ヒットはダッシュボードに表示されません。

ユニークユーザーの正確なカウント

Umamiはトラフィックを2つの単位でカウントします: 訪問者(visitors)とセッション(visits)。訪問者とはセッションをまたいで持続するIDであり、セッションとは1回のセッションです。ウェブ上では、UmamiはIPアドレスとUser-Agentのクッキーレスハッシュから訪問者を計算します。アプリにはハッシュするブラウザセッションがないため、umami-swiftはビジターID自体を提供します。各イベントはpayload.id、つまりUmamiが既に計算されたビジター識別子として受け入れるUUIDを運びます。

このUUIDはランダムで、メモリ内にのみ存在し、カレンダーの日が変わるとローテーションします。デバイスには何も書き込まれないため、読み取るIDはなく、異なる日の使用をリンクすることはできません。IDはプロセスとともに消滅するため、実際には各起動が新しい訪問者としてカウントされ、典型的なライフタイムではなく1日を上限とします。これにより、アプリはUmamiのクッキーレスウェブトラッキングと同じ状態を保ちます。そこでは訪問者は保存された識別子ではなく、ローテーションするサーバーサイドハッシュです。ここにはIDFAやApp Tracking Transparencyには一切触れず、IDは誰かをアプリ、インストール、あるいは日をまたいで追跡することはできません。

ページビューが概要を機能させる

Umamiは、ページビューから訪問者数、セッション数、閲覧数を計算します。nameを持つペイロードはカスタムイベントであり、ページビューではないため、名前付きイベントだけでは概要はゼロのままで、イベントの下にのみ表示されます。

そのため、クライアントは起動ごと、およびフォアグラウンドに戻るたびに / のページビューを送信します。通信上では、隣接するapp_startedイベントとほぼ同じペイロードですが、ページビューにはnameがありません。これにより、概要には実際の数値が表示されます。つまり、起動ごとに1回の閲覧があり、セッション数と訪問者数はウェブサイトと同じようにカウントされます。

画面もオプトインできます。Umami.screen("settings")は/settingsのページビューを送信し、その画面はUmamiのページリストにウェブサイトのページのように表示されます。これが、投稿の前半で示されたページリストを埋めるものです。

前の投稿の多くはCloudflareの/np/パスについて扱っていました。なぜなら、ブラウザは訪問者がインストールしている広告ブロッカーやプライバシー拡張機能を通してすべてのリクエストをルーティングするからです。そこではブロッカーは完全なURLを見るため、EasyPrivacyのようなブロックリストはUmamiの通常のホスト名やスクリプトパスに一致します。/np/パスはそれを回避します。

アプリはブロックがより困難です。iOSで一般的なSafariコンテンツブロッカーは、Safari内でのみ機能し、ネイティブアプリのトラフィックを見ることはありません。1Blockerのファイアウォールのようなシステム全体ブロッカーや、NextDNSやAdGuardのようなDNSブロッカーは異なります。これらはオンデバイスVPNまたはリゾルバとして実行され、アプリとネットワークの間に配置されます。しかし、それが見るのはDNSルックアップとTLSハンドシェイクのサーバー名からのドメインだけです。パスは暗号化されたリクエスト内に留まるため、ブラウザでUmamiを捕捉するパスやスクリプト名のルールは一致するものがなく、残るのはホスト名だけです。hjerpbakk-analytics.fly.devのような目立たないドメイン上のセルフホストインスタンスは、ブロックリストに載っていないため、リクエストは通過します。その正確なドメインを手動でカスタムリストに追加すれば停止しますが、それ自体で停止することはありません。

したがって、umami-swiftはCloudflare Workerを経由せず、Flyオリジンに直接話しかけます。ウェブサイトのために/np/プロキシはその仕事をしますが、アプリはそれをスキップします。しかし、後述するように、それにはまだ役割があります。

Umamiでのアプリアイコン表示

Umamiはダッシュボードの各ウェブサイトの横に小さなアイコンを表示します。これは登録されたドメインに基づいてDuckDuckGoのファビコンサービスから取得されます。これは実際のウェブサイトでは機能します。私のアプリはsimplestworkouttracker.iosのような疑似ドメインで登録されているため、どのファビコンサービスも解決できません。そのため、すべてのアプリは同じ灰色の地球儀アイコンになりました。

セルフホストしているということは、これを変更できるということです。UmamiはFAVICON_URL環境変数を読み込み、{{domain}}プレースホルダーを持つURLテンプレートでファビコンサービスを置き換えます。私のものは前の投稿のCloudflare Workerを指しています。

FAVICON_URL=https://hjerpbakk.com/icons/{{domain}}

そのため、アプリはトラッキングのためにWorkerをスキップしますが、結局アプリのために小さな仕事をすることになりました。/icons/<domain>が要求されたとき、それはドメインを私のアプリのリストと照合します。一致した場合、アプリの実際のアイコン(Worker自体に埋め込まれた48x48ピクセルのPNG。ダッシュボードは16ポイントでレンダリングするため、48は3倍ディスプレイをカバーします)が返されます。それ以外のものはDuckDuckGoのファビコンサービスにリダイレクトされ、ウェブサイトは既に持っていたファビコンを維持します。小さなスクリプトがアプリの1024ピクセルアイコンをリサイズして埋め込むため、次のアプリのアイコンを追加するのは1つのコマンドで済みます。

[画像: Cloudflare Workerにアイコンを要求するUmamiウェブサイトリスト。アプリドメインはアプリの埋め込みアイコンを取得し、他のすべてのドメインはDuckDuckGoのファビコンサービスにリダイレクトされる]

純粋に装飾的なものですが、ウェブサイトリストはダッシュボードを開いたときに最初に見るものであり、最初のスクリーンショットが示すように、アプリはプレースホルダーではなく実際のアイコンを持つようになりました。