sending-notifications

リアルタイム通知の送信

使用する場面

PostHog の機能に通知サポートを追加する場合 — たとえば、コメントでメンションされたとき、アラートが発火したとき、承認がリクエストされたときにユーザーへ通知する場合です。

ファサード API

通知の作成はすべて単一の関数を通じて行います。内部モジュールからではなく、ファサードからインポートしてください:

from products.notifications.backend.facade.api import (
    create_notification,
    NotificationData,
    NotificationType,
    Priority,
    TargetType,
)

NotificationData を構築し、create_notification を呼び出します:

event = create_notification(
    NotificationData(
        team_id=team.id,
        notification_type=NotificationType.ALERT_FIRING,
        priority=Priority.CRITICAL,
        title="Event ingestion latency > 30s",
        body="Events are queuing up. Ingestion pipeline is degraded.",
        target_type=TargetType.USER,
        target_id=str(user.id),
        resource_type="dashboard",
        resource_id="42",
        source_url="/dashboard/42",
    )
)

成功時は NotificationEvent を返し、フィーチャーフラグが無効である場合、受信者が解決されなかった場合、またはチームが存在しない場合は None を返します。どのようなコンテキストでも安全に呼び出せます。

NotificationData のフィールド

必須:

フィールド	型	説明
team_id	int	チームコンテキスト — 組織の参照とフィーチャーフラグの確認に使用されます
notification_type	NotificationType	UI のアイコンを決定します
title	str	通知の見出し (約100文字を推奨)
body	str	展開時に表示される長い説明。空文字列にできます
target_type	TargetType	受信者: user、team、organization、または role
target_id	str	ターゲットの ID (ユーザー ID、チーム ID、組織 UUID、またはロール UUID を文字列として指定)

任意:

フィールド	型	デフォルト	説明
resource_type	NotificationResourceType | None	None	アクセス制御された型 (例: "dashboard") は、閲覧権限のない受信者を自動的に除外します
resource_id	str	""	リンク用のリソースの ID
source_url	str	""	相対 URL パス (例: /dashboard/42)。UI ではリンクアイコンとして表示されます
priority	Priority	NORMAL	normal = ポップオーバーのみ、critical = ポップオーバー + 永続的なトースト
archivable	bool	False	受信者ごとの「アーカイブ」(削除) アクションを有効にし、通知を受信者のアーカイブタブに移動します。False の場合、受信者は既読/未読のマークのみ可能です (デフォルトのパターン)
resolver	RecipientsResolver | None	None	カスタムの受信者リゾルバー。デフォルトではユーザー/チーム/組織/ロールのターゲティングを処理します

パラメータの選択

通知タイプ

タイプ	使用する場面
comment_mention	ユーザーがコメントやディスカッションで @メンションされた
alert_firing	監視アラートのしきい値が超過した
approval_requested	変更にユーザーの承認が必要になった
approval_resolved	ユーザーが要求した承認が解決された
pipeline_failure	データパイプラインまたはバッチエクスポートが失敗した
issue_assigned	エラー追跡のイシューがユーザーに割り当てられた

優先度

critical の扱いには十分注意してください。 critical は、ユーザーの画面に重なって表示され、手動で閉じる必要がある永続的なトーストポップアップをトリガーします。これは意図的に邪魔になるように設計されています。停止、セキュリティアラート、SLA 違反など、真の緊急事態に限定して使用してください。critical を乱用すると、ユーザーは通知を完全に無視するように学習してしまいます。迷ったときは normal を使用してください。

ターゲットタイプ

ターゲット	target_id の値	受信者
user	ユーザー ID	そのユーザーのみ
team	チーム ID	チームの組織の全メンバー
organization	組織 ID	組織の全メンバー
role	ロール ID	その RBAC ロールを持つ全ユーザー

リソースタイプとアクセス制御

resource_type がアクセス制御されたリソース（ダッシュボード、feature_flag、experiment など）と一致する場合、viewer アクセスを持たない受信者は自動的に除外されます。通知専用のタイプ（pipeline、approval、comment）では、AC フィルタリングは適用されません。

配信パイプライン

Django (create_notification)
  → Postgres (NotificationEvent row)
  → Kafka (notification_events topic, on transaction commit)
  → Go livestream service (Kafka consumer)
  → Redis SPUBLISH (sharded pub/sub, keyed by org ID)
  → SSE (/notifications endpoint)
  → Browser (popover + optional toast)

Kafka へのパブリッシュは transaction.on_commit で行われます。トランザクションがロールバックされると実行されません。

新しい通知タイプの追加

1. products/notifications/backend/facade/enums.py に列挙値を追加する
2. frontend/src/lib/components/NotificationsMenu/notificationToasts.tsx（NOTIFICATION_TYPE_ICONS）にアイコンマッピングを追加する — これは単一のアイコンソースであり、getNotificationIcon によって読み取られ、それを呼び出すのは NotificationRow のみです。サイドパネルはその行をレンダリングすることでアイコンを取得します
3. frontend/src/lib/components/NotificationsMenu/NotificationRow.tsx（REALTIME_NOTIFICATION_TYPE_META）にラベル + 説明のエントリを追加する — これはタイプごとの通知設定 UI を制御します
4. python manage.py makemigrations notifications を実行する

テスト

テストではフィーチャーフラグをモックします:

from unittest.mock import patch

with patch("posthoganalytics.feature_enabled", side_effect=lambda flag, *a, **kw: flag == "real-time-notifications"):
    event = create_notification(data)