add-google-analytics

Google Analytics を追加する

プロジェクトごとに本番用の GA4 プロパティとウェブ ストリームを 1 つずつ作成し、標準のページビューと拡張計測を追加します。共有のキー不要サービスアカウントを使用し、サービスアカウントキーは作成もダウンロードもしないでください。

譲れない安全ルール

• まずドライランの計画を提示します。変更を加える前に、明示的な確認を 1 回求めてください。
• 計画と検証は、作業ツリーが汚れていても実行できます。適用には、Git の作業ツリーがクリーンである必要があります。
• アプリケーションコードを退避、破棄、コミット、プッシュ、デプロイしないでください。
• Analytics のリソースや収集済みデータを削除しないでください。
• 既存のアナリティクスと併用してインストールしないでください。停止して、調査結果を提示してください。
• Next.js の両方のルーター、複数のパッケージマネージャー、複数の GA リソース、または複数の本番 URL が候補となる場合は、推測しないでください。
• 厳格なコンテンツセキュリティポリシー（CSP）が連携対象またはグローバルなレスポンスに適用されている場合は、停止して、ナンス／ハッシュに対応したプロジェクト固有の変更を提案してください。計測対象外のドキュメントのみに適用される CSP では、プロジェクト全体を停止するのではなく、明示的な境界のレビューが必要です。unsafe-inline や広範なオリジンを追加しないでください。
• プロジェクトの規模を理由に、プライバシー法の適用除外があると主張しないでください。このワークフローでは、同意ゲートなしでアナリティクスを読み込むことを意図しています。その事実を計画に記載してください。
• 認証情報やトークンを、リポジトリ、出力、シェル引数、ログに含めないでください。測定 ID と GA リソース ID は公開メタデータであり、秘密情報ではありません。

対応対象

• Next.js App Router と Pages Router
• プレーンな静的 HTML と Vite を利用したバニラ JavaScript
• Jinja テンプレートを使用する Flask アプリケーション

対応していないフレームワークは、独自に対応を試みず拒否してください。Next.js をアップグレードしたり、ルーターのアーキテクチャを変更したりしないでください。

1. 調査する

まず、リポジトリのガイドラインを読みます。プロジェクトのルートから、次を実行します。

node <skill-dir>/scripts/inspect-project.mjs .

ブロッカーが見つかった場合、インスペクターは終了コード 2 で終了しますが、JSON は引き続き計画の入力として使用します。デプロイ設定と、変更が及ぶすべてのファイルも確認してください。

以下を確認します。

• 対応対象が 1 つであること（または Next.js のルーターが明確に意図されていること）
• ロックファイル／パッケージマネージャーが 1 つであること
• 既存の GA タグ、測定 ID、@next/third-parties/google がないこと
• 連携対象またはグローバルなレスポンスに影響する CSP がないこと
• 対象外のルートに適用される CSP について、レビュー済みの明示的な除外があること
• 人が読んで理解できるプロパティ名
• 明示的に確認済みの正規の本番 URL
• 対象となるソースファイルの一覧がすべて揃っていること
• Vercel がリンクされているかどうか

Flask/Jinja の場合は、{% extends %} の関係をたどり、最も上位の共通ベーステンプレートを優先します。そのテンプレートでカバーされない単独のテンプレートを一覧にしてください。複数ページの静的サイトの場合は、デプロイされるファーストパーティの HTML エントリをすべて一覧にし、生成物／ベンダー出力は除外してください。

2. ドライラン計画をすべて整える

個人設定は ~/.config/add-google-analytics/config.json に保存し、プロジェクトの状態は追跡対象の .ga4.json ファイルに保存します。個人設定をスキルリポジトリに保存しないでください。

計画には以下を示します。

• GCP の割り当てプロジェクトと、必要な場合はキー不要のサービスアカウントの設定
• 選択した Analytics アカウント
• プロパティ名、正規 URL、America/Toronto／CAD のデフォルト値または上書き値
• 本番用ウェブ ストリーム 1 つ
• 操作があるたびにリセットされる、イベントとユーザーの 14 か月のデータ保持期間
• 拡張計測を有効化（履歴に基づくページ変更を含む）
• Google Signals が無効であること、および広告プロダクトとのリンクが存在しないことの確認
• ソース／依存関係に加える具体的な変更
• 本番環境のみのデプロイ設定
• 検証コマンドとブラウザーでの確認手順
• .ga4.json の各フィールドの内容（作成前の ID は不明）、アダプター、対象、レビュー済みの CSP パス除外があればその内容を含む
• 同意ゲートなしでアナリティクスを直ちに読み込むこと
• コミット、プッシュ、本番デプロイを行わないこと

この計画全体について、明示的な確認を 1 回求めてください。確認後は、Google アカウントへのアクセスで必要となる UI 操作と、新たに判明した競合を除き、自律的に進めてください。

3. キーレスアクセスを一度だけブートストラップする

ヘルパーとローカル設定を確認します。

node <skill-dir>/scripts/ga4-admin.mjs doctor

設定がない場合は、計画の承認後に次を実行します。

node <skill-dir>/scripts/ga4-admin.mjs bootstrap \
  --quota-project <project> \
  --time-zone America/Toronto \
  --currency CAD \
  --confirmed

これにより、analyticsadmin.googleapis.com と iamcredentials.googleapis.com のみが有効化され、analytics-automation@<project>.iam.gserviceaccount.com が作成または再利用されます。また、アクティブな gcloud ユーザーにはそのサービスアカウントに対する roles/iam.serviceAccountTokenCreator が付与され、サービスアカウントにはクォータプロジェクトに対する roles/serviceusage.serviceUsageConsumer が付与されます。後者は Analytics API のクォータの帰属を可能にするもので、他のプロジェクトリソースへのアクセス権を付与するものではありません。

IAM の変更が反映されるまで、約1分かかることがあります。ヘルパーは、想定される getAccessToken と serviceusage.services.use の反映遅延エラーに限り、上限付き指数バックオフで再試行します。実際の Analytics の認可エラーに対して、再試行の対象を広げないでください。

ユーザーは、表示されたサービスアカウントのメールアドレスを Google Analytics のアカウント アクセス管理で編集者として追加する必要があります。管理者を要求しないでください。次に、アクセス可能なアカウントを一覧表示します。

node <skill-dir>/scripts/ga4-admin.mjs accounts

初回は明示的なアカウント選択を必須とし、選択内容をローカルに書き込みます。以降の実行ではデフォルトを表示します。

node <skill-dir>/scripts/ga4-admin.mjs set-account --account accounts/<id>

4. プロビジョニング前に照合する

ライブ API の計画を実行します。

node <skill-dir>/scripts/ga4-admin.mjs plan \
  --property-name '<name>' \
  --url '<canonical-production-url>'

一致する名前または正規 URL が見つかった場合は停止します。候補を説明し、--adopt-property properties/<id> を渡す前に明示的な承認を求めます。重複を自動作成してはいけません。

承認された計画の後、プロビジョニングまたは照合を行います。

node <skill-dir>/scripts/ga4-admin.mjs apply \
  --property-name '<name>' \
  --url '<canonical-production-url>' \
  --confirmed

承認済みの既存プロパティを採用する場合は、--adopt-property properties/<id> を追加します。部分的な失敗を冪等に修復できるよう、ヘルパーはストリームの取得後すぐに .ga4.json を書き込みます。

ソースを調査した後、.ga4.json にシークレットではない統合メタデータとして adapter、ソースの target、excludedPaths を追加します。除外がある場合は cspBoundaryReviewed: true も追加します。明示的な承認なしに、境界をレビュー済みとしてマークしてはいけません。

5. プロジェクトに統合する

references/integrations.md を最後まで読み、該当するアダプターを使用します。

すべてのアダプターに共通するルール：

• 本番環境のみを計測します。
• レンダリングされる各ページにタグを正確に1つ追加します。
• .ga4.json の測定 ID を使用します。
• カスタムのビジネスイベントを追加しません。
• プロジェクトの書式と規約を維持します。
• “analytics” という名前の既存のアプリケーションコードを改名したり、別の用途に転用したりしないでください。GA の計測は別のものです。

Vercel にリンクされたプロジェクトでは、Vercel CLI を使用して 本番環境のみ に NEXT_PUBLIC_GA_MEASUREMENT_ID を設定します。既存の変数を先に確認し、プレビュー環境や開発環境には決して追加しないでください。デプロイを実行しないでください。

サポート対象外のホストでは、ソースへの統合を完了し、必要なデプロイ設定を正確に報告します。

6. 検証と確認

利用可能な場合は、リポジトリ独自のフォーマッター／チェックモード、型チェック、Lint、テスト、本番ビルドを実行します。検出されたパッケージマネージャーを使用し、別のロックファイルを作成しないでください。

ライブの Analytics 設定を確認します。

node <skill-dir>/scripts/ga4-admin.mjs verify

次に、統合リファレンスに記載された2段階のビルドとブラウザーによる手順に従います。本番環境変数なしのビルドでは GA リクエストが発生しないことを確認し、ビルド時に本番環境変数を設定して再ビルドします。gtag.js の読み込みを許可しながら収集エンドポイントを 204 でモックし、初回表示およびクライアントナビゲーション時のページビューに重複がないことを確認します。適用／修復では、ブラウザーレベルのリクエスト検証が必須です。

後日、別途依頼されたデプロイ後の検証では、ライブサイトを調査してもかまいません。インストール中に GA レポートを待たないでください。データの取り込みには遅延があります。

計画のみのモード

計画のみを求められた場合は、既存の設定で可能な範囲で、調査と読み取り専用のライブ API 計画を実行します。IAM のブートストラップ、API の有効化、GA リソースの作成、ファイルの編集、Vercel の変更は行いません。作業ツリーに未コミットの変更があってもかまいません。障害となる事項と、次に取るべき安全な手順を明確に列挙します。

修復モード

.ga4.json が存在する場合、plan と apply は新たに作成するのではなく、参照先の稼働中プロパティとの整合性を取ります。不足している、または差異のある非破壊的な設定と、ソース／デプロイ統合のみを修復します。広告プロダクトへのリンクがないことを確認します。引き継いだプロパティにリンクがある場合は報告して停止し、差異の修復のためにリソースを削除または置換してはなりません。