チャートアノテーションを使うと、重要なイベント（デプロイ、リリース、 マーケティングキャンペーン、インシデント、カスタムマイルストーン）を すべてのZenovay時系列チャートにマークできます。トラフィックや収益が変動 したとき、ダッシュボードを離れずに同じ時刻に何が起きたかを確認できます。
アノテーションが重要な理由
ほとんどの分析の問いは「何が変わった？」に集約されます。火曜午後の 予期しない落ち込みも、14時32分に「deploy: release v2.5」のマークが あれば、調査がはるかに容易になります。アノテーションは、ビジネス メトリクスと運用イベントが横並びに住む単一のタイムラインへと ダッシュボードを変えます。
5種類のアノテーション
| タイプ | 色 | 主な用途 |
|---|---|---|
deploy | 青 | コードデプロイ、インフラ変更、設定の本番反映 |
release | エメラルド | 公開リリース告知、バージョン区切り |
campaign | アンバー | マーケティングキャンペーン、広告開始、メール送信 |
incident | 赤 | 顧客影響のあるインシデント、障害 |
custom | バイオレット | その他すべて - 役員会、パートナー連携、監査など |
各タイプには専用のアイコンと色があり、チャート下のチップ列を一目で 判別できます。
アノテーションを作成する3つの方法
オプション1 - ダッシュボード内
Webサイトのダッシュボードを開き、Analyticsタブを選択してから、 訪問者チャートの任意のポイントのノートアイコンをクリックします。 日付の詳細ダイアログが3つのタブ（Notes、Annotations、Commits）で 開きます。Annotationsタブで、タイプ（deploy、release、campaign、incident、 またはcustom）を選択し、メッセージを入力して追加します。マーカーが すぐにチャートに表示されます。
これは単発のイベントをマークする最も速い方法です。定期的にデプロイを 行う場合は、以下のCLIがより適しています。
オプション2 - Zenovay CLI（CI推奨）
CIパイプラインからデプロイをマークする標準的な方法です。アカウント ログイン経由で認証を扱い、macOS、Linux、Windowsで動作します。
zenovay annotation create --type=deploy --message="release v2.5"
デプロイパイプラインの最後のステップとして追加すれば、各リリースが
自動でマークされます。コマンドはプラン制限（4）またはデュプリケート（5）
エラーの場合に異なるコードで終了するため、パイプラインで各ケースを
処理できます。フラグの完全リファレンスとGitHub Actions例は
CLI連携ガイド を参照。
オプション3 - REST API
ダッシュボード自体が使用する /api/annotations エンドポイントもあります。
ダッシュボードセッション（ブラウザで使用するのと同じログイン）で認証するため、
既に有効なセッションを保有するサーバーにのみ実用的です。外部 zv_*
API キーは現在このエンドポイントでは受け入れられません。そのため、
CI および他の自動化環境では、上記のCLIが適切なツールです。認証を
処理します。詳しくはチャートアノテーション API リファレンス
をご覧ください。
プラン上限と動作
- Free: チームあたり月10アノテーション。
- Pro以上: 無制限。
既存のアノテーションから5分以内の同じ type かつ 同じメッセージは
拒否されます。誤設定のCIパイプラインがタイムラインを重複で埋めることを
防ぎます。同じタイプで異なるメッセージのアノテーション2件
（例："checkout壊れた"、その後"checkout直った"）は両方許可されます。
アノテーションが表示される場所
- 顧客向けの各分析チャート下 に色付きのチップ列として表示。 ホバーすると完全なメッセージと正確な時刻が見えます。
- コンバージョンインシデント分析パネル に「疑わしい変更」として、 インシデント発生時刻の±2時間以内のものが一覧されます。
- ドメイン訪問者チャートの既存ノートアイコン位置。以前のノート 機能を使っている場合は両方のサーフェスが自動同期します。
チップ列の読み方
チャート下の各チップはタイプ別に色分けされ、左側にタイプアイコンが 表示されます。5色はすべてのチャート・ページで一貫しているため、 覚えてしまえば一目でスキャンできます。青の集まり = デプロイ、 アンバー = キャンペーン、赤 = インシデント。チップにはメッセージと 作成時刻が表示され、ホバーで完全なタイムスタンプを確認できます。
プライバシー：公開ダッシュボードではアノテーションを表示しません
チーム外の誰かと公開ダッシュボードのリンクを共有しても、アノテーション は表示されません。デプロイ／リリースのメッセージはサイトを運営する チーム向けの情報であり、訪問者向けではありません。アノテーションの 内容を公開する手段はありません。
よく使うパターン
本番デプロイをすべて自動マーク - CLIコマンドをデプロイ後ステップ として追加。最初の配線後は手作業ゼロ。
キャンペーン開始をマーク - 公開のタイミングで
zenovay annotation create --type=campaign --message="春のセール開始"
を実行。後でトラフィックリフトを見直すとき、すでにマーカーがチャート上に
あります。
既知のインシデントをマーク - インシデントアノテーションを投稿し、 チャート上で落ち込みの理由を見える化。コンバージョンインシデント分析 （未説明の落ち込みを自動検出）と自然に連携します。
トラブルシューティング
- 「Annotation limit reached」: Freeプランの月次上限到達。 無制限利用にはPro以上にアップグレード。
- HTTP 409 dedupエラー: 5分以内に同じタイプかつ同じメッセージの アノテーションを2件投稿しようとしています。待つか、メッセージを 変えるか、最初のマーカーで十分と判断してください。(CLIはこのケースで 終了コード5を返します)
- チップ列が表示されない: そのサイトに少なくとも1つの アノテーションがあるか確認してください。表示するものがない場合は 非表示のままです。
- チップが間違った言語またはテーマ: テーマはダッシュボードのテーマに 従い、言語はブラウザのロケールに従います。両方とも自動的に切り替わります。