analytics-setup

GA4 / Search Console のデータを BigQuery に集約し、Claude で自然言語分析できる環境を構築する。このスキルはクライアントの GCP 環境で Claude Code を起動して実行する（gcloud / bq / gh CLI と、対象プロジェクトへのオーナー相当権限が前提）。

Step 0 — ヒアリング

以下を確認してから始める（不明な項目は調べ方を案内する）:

Step 1 — プリフライト

gcloud config get-value project        # 対象プロジェクトか確認。違えば gcloud config set project
gcloud services enable bigquery.googleapis.com searchconsole.googleapis.com analyticsdata.googleapis.com

Step 2 — GA4 → BigQuery リンク

bq ls --project_id=<PROJECT> | grep analytics_<PROPERTY_ID>

• 存在する場合: bq show --format=prettyjson <PROJECT>:analytics_<PROPERTY_ID> | grep location でロケーションを控える（以降すべてこれに合わせる）
• 存在しない場合: ユーザーに GA4 管理画面での設定を案内 → 管理 → プロダクトのリンク → BigQuery のリンク → 対象プロジェクト・ロケーションを選択・毎日エクスポート ON。初回データは翌日以降。設定完了を待たずに次へ進んでよい

Step 3 — Search Console → BigQuery

1. IAM 付与（こちらで実行）:

gcloud projects add-iam-policy-binding <PROJECT> \
  --member="serviceAccount:search-console-data-export@system.gserviceaccount.com" \
  --role="roles/bigquery.jobUser" --condition=None
gcloud projects add-iam-policy-binding <PROJECT> \
  --member="serviceAccount:search-console-data-export@system.gserviceaccount.com" \
  --role="roles/bigquery.dataEditor" --condition=None

2. ユーザー操作を案内: Search Console → 設定 → 一括データエクスポート → プロジェクト ID / データセット名 searchconsole / ロケーションは Step 2 と同一
3. 所有権未検証の場合は docs/setup-guide.md の「所有権の検証」を案内（DNS TXT のドメインプロパティが最も確実。HTML ファイル方式はホスティングのリダイレクトで失敗しやすい）

Step 4 — Claude 分析環境

1. analytics.config.example.json を analytics.config.json にコピーし、ヒアリング内容を反映
2. 分析スキルを生成: templates/ga4-analysis/SKILL.md.tmpl の {{...}} プレースホルダを config の値で置換し、クライアントの作業リポジトリの .claude/skills/ga4-analysis/SKILL.md に配置
3. BigQuery MCP を登録（Google 公式のリモートサーバー。ローカルバイナリ不要・各利用者が自分の Google アカウントで OAuth）:

claude mcp add --scope project --transport http bigquery https://bigquery.googleapis.com/mcp

• 初回利用時に各自が対話セッションで /mcp → authenticate（ブラウザで Google ログイン）
• 非エンジニアの Claude（Desktop / claude.ai）は「設定 → コネクタ → カスタムコネクタを追加」に同 URL を貼るだけ
• 利用者ごとに BigQuery の IAM（roles/bigquery.dataViewer + jobUser）が必要
• オフライン環境やローカル実行が必要な場合のみ MCP Toolbox（stdio 版）を代替として使う

Step 5 — 月次レポート（任意）

1. Sheets 用サービスアカウントを作成し、鍵を発行して .env に GOOGLE_SHEETS_CLIENT_EMAIL / GOOGLE_SHEETS_PRIVATE_KEY を設定
2. 空のスプレッドシートを作成し、サービスアカウントのメールを編集者として共有 → ID を config の report.spreadsheetId に
3. npm run ga:report -- --month=YYYY-MM で手動実行を確認
4. 定期実行はクライアント環境に合わせて launchd / cron / Cloud Scheduler を選択（docs/setup-guide.md 参照）

Step 6 — 検証

# GA4 データ疎通（データを読まない dry run）
bq query --project_id=<PROJECT> --use_legacy_sql=false --dry_run \
  'SELECT COUNT(*) FROM `<PROJECT>.analytics_<PROPERTY_ID>.events_*`'

• 生成した分析スキル経由で「昨日の PV は？」を実行し、集計が返ることを確認
• チェックリスト（README の導入チェックリスト）を埋めてクライアントに引き渡す

詰まりどころ（必ず先回りで確認）

• Search Console API の有効化漏れ → 403（Step 1 で対応済みのはず）
• ロケーション不一致 → GA4 と GSC のデータセットが別リージョンだと JOIN 不可。作り直しになるので Step 2 で必ず確認
• GSC 一括エクスポートは設定日以降のみ。過去データが必要なら Search Console API でのバックフィルを別途提案
• 新規 GSC プロパティはデータ反映まで 1〜2 日。0 行でも異常ではない
• 開発者・社内アクセスの混入: 導入後に「特定ユーザーへの極端な集中」が見えたら内部トラフィック除外（GA4 データフィルタ + traffic_type マーキング）を提案する