analytics-insights

アナリティクスインサイト

Google の計測スタック（GA4、GTM、Search Console、BigQuery）をチャットから直接操作するオペレータースキルです。トラッキング計画の作成、レポートの実行、コンバージョンの設定、既存の設定の監査、会話を離れずに行うデータウェアハウスへのクエリをサポートします。

対象外 — 他のスキルを案内してください

リクエスト	案内先
キーワード調査、AI 検索での可視性、SEO の包括的な監査	seo-research（HyperSEO ツールキット。キーワード調査では GSC よりも幅広く、豊富な機能を備えています）
Google Ads キャンペーンのパフォーマンス	google-ads（キャンペーンレベル）。ただし、GA4 側のコンバージョンアトリビューションはこちらで扱います
Meta／Facebook 広告の指標	meta-ads
メール施策の指標	email-lifecycle（プロバイダー側）

GSC と HyperSEO は検索パフォーマンスデータが重複します。使い分けの目安：ユーザー自身のサイトの表示回数／クリック数／掲載順位データには、こちらの GSC を使います。キーワード調査、競合データ、AI 検索での可視性には、HyperSEO（seo-research 内）を使います。

要件

• Hyper MCP がインストールされ、接続されていること。 https://app.hyperfx.ai/mcp
• https://app.hyperfx.ai/apps で、以下のうち少なくとも 1 つが接続されていること：
  • Google Analytics — GA4 レポート、カスタム指標／ディメンション、キーイベント（コンバージョン）の管理。
  • Google Tag Manager — タグ／トリガー／変数／ワークスペース／バージョンの管理。
  • Google Search Console — 検索パフォーマンスデータ、サイトマップ、URL 検査。
  • BigQuery — GA4 エクスポート（またはその他のデータセット）に対する SQL クエリ。

google_analytics_ga4_reports_run、google_tag_manager_tags_manage、google_search_console_performance_get、bigquery_execute_query がすべてエージェントのツール一覧にない場合は、作業を中止し、Hyper MCP を有効にして、これらの連携のうち少なくとも 1 つを接続するようユーザーに伝えてください。

このスキルのツールを実行する方法

このスキルの各ツールは、正式なツール名で指定されています。利用するインターフェースに応じた呼び出し方法で実行してください。

インターフェース	ツールを探す	実行する
MCP クライアント（Claude、Cursor、Codex、ChatGPT）	search("<what you want to do>") を実行し、続いて describe("<name>") を実行	call("<name>", {...})
Hyper CLI	hyperai search "<what you want to do>" を実行し、続いて hyperai describe <name> を実行	hyperai call <name> --json '{...}'

ツールが見つからない場合、その連携は未接続か、ワークスペースで有効になっていません。作業を中止し、接続する連携をユーザーに伝えてください。

ツール一覧

グループ	ツール
GA4 — レポート	google_analytics_ga4_reports_run, google_analytics_accounts_list, google_analytics_properties_list, google_analytics_properties_get
GA4 — プロパティとデータストリーム	google_analytics_ga4_properties_create, google_analytics_properties_update, google_analytics_properties_delete, google_analytics_data_streams_create, google_analytics_data_streams_list, google_analytics_data_streams_get, google_analytics_data_streams_update, google_analytics_data_streams_delete, google_analytics_data_retention_get (読み取り専用 — MCP には更新用のバリアントはありません), google_analytics_data_collection_acknowledge
GA4 — キーイベント（コンバージョン）	google_analytics_key_events_create, google_analytics_key_events_list, google_analytics_key_events_get, google_analytics_key_events_update, google_analytics_key_events_delete
GA4 — カスタム指標／ディメンション	google_analytics_custom_metrics_create, google_analytics_custom_metrics_list, google_analytics_custom_metrics_get, google_analytics_custom_metrics_update, google_analytics_custom_metrics_archive, google_analytics_custom_dimensions_create, google_analytics_custom_dimensions_list, google_analytics_custom_dimensions_get, google_analytics_custom_dimensions_update, google_analytics_custom_dimensions_archive
GTM	google_tag_manager_accounts_manage, google_tag_manager_containers_manage, google_tag_manager_workspaces_manage, google_tag_manager_tags_manage, google_tag_manager_triggers_manage, google_tag_manager_variables_manage, google_tag_manager_built_in_variables_manage, google_tag_manager_folders_manage, google_tag_manager_environments_manage, google_tag_manager_versions_manage, google_tag_manager_version_headers_manage, google_tag_manager_user_permissions_manage, google_tag_manager_clients_manage, google_tag_manager_templates_manage, google_tag_manager_transformations_manage, google_tag_manager_zones_manage, google_tag_manager_destinations_manage
Google Search Console	google_search_console_performance_get, google_search_console_sites_list, google_search_console_sitemaps_list, google_search_console_sitemaps_get, google_search_console_sitemaps_submit, google_search_console_sitemaps_delete, google_search_console_urls_submit
BigQuery	bigquery_execute_query, bigquery_insert_rows

重要なルール

1. GA4 プロパティ ID — 引数名はツールによって異なります。 パターンは 3 つあります。（a）レポートツール（run_ga4_report、get_property）では、property_id="properties/123456789" を指定します。（b）作成・一覧表示ツール（create_key_event、list_key_events、create_custom_dimension、list_custom_dimensions など）では、parent="properties/123456789" を指定します。（c）取得・更新・削除ツールは特定のリソースを操作するため、完全なリソースパスを含む name=（例："properties/123456789/keyEvents/12345"）を指定します。いずれの場合も、何らかの形で properties/ プレフィックスが必要です。数字のみの ID を渡すと、エラーを通知せずに失敗します。迷った場合は、ツールのスキーマで required と指定されている引数を確認してください。
2. 日付範囲の開始日と終了日は、どちらも範囲に含まれます。 start_date="2026-04-01"、end_date="2026-04-30" の場合、29 日ではなく 30 日分が返されます。相対日付でも同様で、7daysAgo から today までは 7 日ではなく 8 日です。
3. GA4 ではイベント数が約 1,000 万件を超えるとサンプリングが発生します。 大量のデータを扱うプロパティでは、GA4 API が結果を通知せずにサンプリングします。精度が重要な場合（取締役会への報告、財務上のアトリビューションなど）は、BigQuery GA4 エクスポートを使用してください。詳細は references/bigquery-ga4-export.md を参照してください。
4. GA4 での「コンバージョン」は「キーイベント」です。 GA4 では 2024 年に「コンバージョン」が「キーイベント」に名称変更されました。ツールもこれに対応しています。イベントをコンバージョンとしてマークするには、google_analytics_key_events_create を使用してください。古いドキュメントに惑わされないようにしてください。
5. GTM の変更には、ワークスペース、バージョンの作成、公開が必要です。 ワークスペースで作成したタグ／トリガー／変数は、ワークスペースを新しいバージョンにコミットし、そのバージョンを公開するまで有効になりません。google_tag_manager_workspaces_manage → 変更 → google_tag_manager_versions_manage（作成）→ 公開の順に実行してください。
6. GSC のデータには 2～3 日の遅延があります。 GSC で「昨日」のデータをクエリしても結果があるとは限りません。安定した数値を得るには、3 日以上前をクエリしてください。一部の指標では、GA4 にも 24～48 時間の遅延があります。
7. Apple Mail Privacy Protection により、メール経由の GA4「エンゲージメント」セッション数が過大になります。 GA4 のメール経由のエンゲージメント数だけを信用しないでください。メールプロバイダー独自のクリックデータと照合してください。

ワークフロー — 適切な手順を選ぶ

このスキルでは、目的の異なる 4 つの作業を扱います。まず作業を選んでください。それぞれのワークフローは異なります。

ユーザーの目的…	手順	参考資料
レポートを作成する（「先月の実績はどうでしたか？」）	Phase R	—
トラッキングを設定する（「X を計測したい」）	Phase T	references/ga4-tracking-plan.md
既存の GTM／GA4 を監査する（「コンバージョンデータがおかしいのはなぜですか？」）	Phase A	references/gtm-audit.md
高精度／サンプリングなし／複数ソースの分析を行う	Phase B	references/bigquery-ga4-export.md

Phase R — レポートを実行する（最も一般的な方法）

データウェアハウスのオプション： ワークスペースに分析用データウェアハウスへの接続がある場合は、テーブルとスキーマを確認し、database_query でクエリを実行します。選択した接続の Warehouse Data Status を確認し、最後に正常に更新された日時を報告します。キャッシュが1時間ごとに更新される、またはデータがサンプリングされていないと決めつけないでください。そうでない場合は、GA4 には google_analytics_ga4_reports_run、GSC には google_search_console_performance_get を使用します。アカウント ID、日付、指標の定義は明示してください。

1. プロパティを確認します。 google_analytics_accounts_list() → google_analytics_properties_list(filter="parent:accounts/<account_id>")。複数ある場合は、ユーザーに選んでもらいます。会話の残りの間、properties/<id> を保存して使用します。
2. 日付範囲を選びます。 必ず確認してください。「過去30日間」は start_date="30daysAgo"、end_date="yesterday" です（部分的な日次データは安定しないため、today は避けます）。
3. 指標とディメンションを選びます。 1つのレポートに12個の指標 × 6個のディメンションを詰め込まないでください。結果が読みにくくなります。ユーザーの質問に答える2〜3個の指標と、意味のある切り口となる1〜2個のディメンションを選びます。
4. レポートを実行します。

google_analytics_ga4_reports_run(
  property_id="properties/123456789",
  start_date="30daysAgo",
  end_date="yesterday",
  metrics=["activeUsers", "sessions", "conversions", "totalRevenue"],
  dimensions=["sessionDefaultChannelGroup", "deviceCategory"],
)

5. 結果を表にして提示します。 解釈を添える場合も、必ず実数値を併記します。「オーガニック検索のセッション数は12,400（前月比+18%）でした」は、「オーガニックが増えました」より適切です。
6. データが示す場合は、追加調査を1回行います。 指標が目立つ変化を示している場合（例：モバイルのコンバージョン率が40%低下）、対象を絞った追加レポートを1回実行します。推測はしないでください。

GA4 の一般的な指標とディメンション

GA4 API ではキャメルケースの名前が使われます。特に役立つものは次のとおりです。

指標： activeUsers、sessions、screenPageViews、bounceRate、engagementRate、averageSessionDuration、conversions、eventCount、totalRevenue、transactions、purchaseRevenue、userEngagementDuration。

ディメンション： country、city、deviceCategory、operatingSystem、browser、sessionDefaultChannelGroup、sessionSource、sessionMedium、sessionCampaignName、pagePath、eventName、date、hour、landingPage。

一覧については、GA4 Data API リファレンスを参照できます。

Phase T — トラッキングを設定する

GA4 API では、プロパティ、データストリーム、キーイベント、カスタム指標、カスタムディメンションを作成できますが、GTM タグをページにデプロイすることはできません。この手順は GTM 側で行うか、サイトに直接ハードコードします。スキルのワークフローは次のとおりです。

1. まずトラッキング計画を作成します。 発火させるイベント、その発火場所、コンバージョン（キーイベント）として扱うイベントを定義します。テンプレート全体は references/ga4-tracking-plan.md を参照してください。
2. GA4 側の設定 — カスタムディメンション／指標を作成し、キーイベントとして設定します。

google_analytics_custom_dimensions_create(
  parent="properties/123456789",
  parameter_name="plan_tier",
  display_name="Plan Tier",
  scope="EVENT",
)

google_analytics_key_events_create(
  parent="properties/123456789",
  event_name="purchase",
  counting_method="ONCE_PER_EVENT",
)

3. GTM 側の設定 — ワークスペースでタグ、トリガー、変数を作成または更新し、バージョンを作成して公開します。

google_tag_manager_workspaces_manage(operation="create", account_id="...", container_id="...", name="purchase-tracking-v3")

google_tag_manager_tags_manage(operation="create", workspace_path="...", tag_definition={...})
google_tag_manager_triggers_manage(operation="create", workspace_path="...", trigger_definition={...})
google_tag_manager_variables_manage(operation="create", workspace_path="...", variable_definition={...})

google_tag_manager_versions_manage(operation="create", workspace_path="...", version_name="purchase-tracking-v3")
# then publish via the GTM UI or version operation

4. 検証します — Phase A を参照してください。

フェーズ A — 監査（既存の設定に問題がある、または疑わしい場合）

「分析データが間違っている」という苦情の原因は、ほとんどの場合、次のいずれかです。

症状	考えられる原因	確認方法
GA4 にコンバージョンイベントが表示されない	GTM ではイベントが発火しているものの、GA4 に届いていない（測定 ID が間違っている、同意ゲートでブロックされている、広告ブロッカーが動作している）	過去 7 日間の eventName=purchase を対象に google_analytics_ga4_reports_run を実行します → 0 の場合は GTM を確認します
コンバージョン数が大幅にずれている	イベントが確認ページだけでなくすべてのページで発火している、またはタグが重複している	google_tag_manager_tags_manage(operation="list") で GTM タグを監査し、同じトリガーで発火するタグが複数ないか確認します
GA4 と正式な記録元のプラットフォームで報告される売上が異なる	通貨の不一致、返金の処理、アトリビューション期間	両方のデータを並べて取得し、返金や通貨に関する行を確認します
モバイルトラフィックが突然ほぼ 0 になった	タグがデスクトップのトリガーでしか発火していない、または最近の GTM 公開によってモバイルコンテナに問題が生じた	google_tag_manager_versions_manage(operation="list") で最近の公開を確認し、前のバージョンとの差分を調べます
GSC のクリック数 ≠ GA4 のオーガニックセッション数	定義が異なるため、常に差が生じます。完全に一致させようとしないでください。	想定内です。記録して次に進みます

詳細な監査手順は、references/gtm-audit.md を参照してください。

フェーズ B — BigQuery GA4 エクスポート（高精度分析／複数データソースの分析）

サンプリングされていないデータ、カスタムアトリビューション、GA4 と注文データベース／CRM データの結合、またはコホート分析を行う場合に使用します。GA4 管理画面で GA4 → BigQuery エクスポートを有効にする必要があります（2023 年以降、標準プロパティでは無料です）。

bigquery_execute_query(
  query="""
    SELECT
      event_date,
      COUNT(DISTINCT user_pseudo_id) AS users,
      COUNTIF(event_name = 'purchase') AS purchases,
      SUM(IF(event_name = 'purchase', ecommerce.purchase_revenue, 0)) AS revenue
    FROM `your-project.analytics_123456789.events_*`
    WHERE _TABLE_SUFFIX BETWEEN '20260401' AND '20260430'
    GROUP BY event_date
    ORDER BY event_date
  """
)

スキーマ、よく使うクエリ、アトリビューションモデリングのワークフロー全体については、references/bigquery-ga4-export.md を参照してください。

出力基準

• 数値は必ず文章ではなく表で示してください。 「12,400 セッション、直帰率 8.2％、コンバージョン率 1.4％」→ Markdown の表にします。
• レポートの見出しには必ず日付範囲を含めてください。 「2026 年 4 月 1 日～30 日」—日付のない数値は役に立ちません。
• レポートの取得元であるプロパティ／サイトを必ず記載してください。 複数プロパティを扱う組織では、これが頻繁に問題になります。
• サンプリングについて注記してください。 GA4 が samplesReadCount < samplingSpaceSize を返した場合は、その旨を明記してください。財務報告や取締役会向け報告でその数値を信頼できるか、ユーザーが判断する必要があります。
• 「比率指標」と「合算可能な指標」を区別してください。 直帰率、エンゲージメント率、コンバージョン率は比率であり、合算できません。列の合計ではなく、1 つの数値として示してください。

参考ワークフロー

参考資料	参照するタイミング
references/ga4-tracking-plan.md	計測対象の設計時 — 推奨イベントスキーマ、カスタムディメンション／指標、キーイベントのマッピング、命名規則
references/gtm-audit.md	既存の GTM コンテナの監査時 — タグの重複、壊れたトリガー、未使用の変数、同意ゲートの不足を確認
references/bigquery-ga4-export.md	GA4 BigQuery エクスポートのクエリ実行時 — スキーマ、よく使うクエリ（DAU、ファネル、アトリビューション、コホート、リテンション）、結合パターン