mcpField
G
ga4-events

ga4-events

github.com/cognyaiマーケティング・グロース11158 回インストール2 週間前に更新
リポジトリ

ga4-events について

Google Analytics 4 のイベント実装、監査、検証を支援するリファレンススキルです。イベントパラメーター、コード例、検証手順をまとめています。

主な機能

  1. 01自動収集イベントと拡張計測イベント
  2. 02推奨イベントのパラメーター
  3. 03Eコマースイベントの例
  4. 04カスタムイベントの命名規則
  5. 05イベントの検証手順
  6. 06GTM と Measurement Protocol のパターン

活用シーン

  1. 01purchase イベントの実装
  2. 02Eコマースイベントファネルの構築
  3. 03イベント名とパラメーターの確認
  4. 04DebugView や BigQuery でのデータ検証

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/cognyai/claude-code-marketing-skills --skill ga4-events

インストール後、Claude Code で/ga4-eventsを入力して読み込まれたか確認します。

詳細

GA4 イベント実装リファレンス

Google Analytics 4 イベントの実装に関する完全なリファレンスです。自動収集イベント、拡張計測イベント、推奨イベント、カスタムイベントについて、正確なパラメーター一覧、コード例、検証方法を説明します。

ドキュメント全文：https://cogny.com/docs/ga4-event-implementation

使い方

/ga4-events                          # Show event model overview
/ga4-events purchase                 # Show purchase event parameters and code
/ga4-events ecommerce                # Full e-commerce event funnel reference
/ga4-events enhanced measurement     # Enhanced measurement events list
/ga4-events custom events            # Custom event naming rules and limits
/ga4-events validation               # DebugView, Realtime, and BigQuery checks
/ga4-events gtm                      # GTM dataLayer implementation patterns
/ga4-events measurement protocol     # Server-side Measurement Protocol examples

手順

あなたは GA4 イベント実装のエキスパートです。このリファレンスを使って、ユーザーが GA4 イベントを正しく実装、監査、検証できるよう支援してください。正確で、そのままコピーして使えるコード例を提示してください。

ユーザーから質問されたら、該当するセクションを見つけ、すぐに実行できる回答と、そのまま使えるコードを提示してください。GA4 MCP ツールが利用可能な場合は、ユーザーの実際のプロパティ設定（カスタムディメンション、データストリーム、コンバージョンイベント）を確認し、状況に即したアドバイスを提供してください。

ユーザーが引数として特定のイベント名やトピックを指定した場合は、その内容に焦点を当ててください。指定がない場合は、イベントモデルの概要を説明してください。

イベントモデルの概要

GA4 はイベントベースのデータモデルを使用しており、すべてがイベントです。Universal Analytics のヒットタイプ（ページビュー、イベント、トランザクション）とは異なり、GA4 の概念は、パラメーターを持つイベントに統一されています。

概念Universal AnalyticsGA4
データモデルヒットベース（ページビュー、イベント、トランザクション）イベントベース（すべてがイベント）
イベント構造カテゴリ／アクション／ラベル／値イベント名＋パラメーター（キーと値のペア）
セッションサーバーで定義、タイムアウトは30分session_start イベントから導出
ページビュー専用のヒットタイプpage_location パラメーターを持つ page_view イベント
E コマースEnhanced Ecommerce プラグインitems 配列を含む組み込みの推奨イベント
カスタムデータカスタムディメンション／指標（インデックスベース）イベントパラメーター＋カスタムディメンション／指標（名前ベース）

GA4 のすべてのイベントには、次の要素があります。

  • イベント名：文字列の識別子（例：page_view、purchase）
  • イベントパラメーター：キーと値のペア（例：page_location、transaction_id）
  • ユーザープロパティ：ユーザーに関連付けられた永続的な属性（例：membership_tier）

自動収集イベント

設定なしで自動的に収集されます。無効にはできません。

ウェブ
イベントトリガー主なパラメーター
first_visitユーザーが初めて訪問（新しい Cookie）なし
session_start新しいセッションの開始（タイムアウトは30分）ga_session_id、ga_session_number
page_viewページの読み込みごと（SPA では history.pushState の実行時も）page_location、page_title、page_referrer
user_engagement操作を伴い、ページが1秒以上フォーカスされているengagement_time_msec
モバイル（Firebase SDK）
イベントトリガー主なパラメーター
first_openインストール後、初めてアプリを開くprevious_gmp_app_id、updated_with_analytics
session_start新しいセッションの開始ga_session_id、ga_session_number
screen_view画面の切り替えfirebase_screen、firebase_screen_class、firebase_screen_id
user_engagementアプリがフォアグラウンドに1秒以上表示されているengagement_time_msec
app_updateアプリを更新して起動previous_app_version
app_removeアプリの削除（Android のみ）なし
os_updateOS の更新previous_os_version
自動付加パラメーター（すべてのイベント）

language、page_location、page_referrer、page_title、screen_resolution、ga_session_id、ga_session_number、engagement_time_msec

拡張計測イベント

Admin > Data Streams > Enhanced Measurementで有効にすると、自動的に収集されます。各イベントは個別に切り替えられます。

イベントトリガー主なパラメーター
scrollユーザーがページの90％を超えてスクロールpercent_scrolled（常に90）
click外部リンクのクリックlink_url、link_domain、link_classes、link_id、outbound
view_search_resultsURLに検索クエリパラメーターが含まれるsearch_term
video_startYouTubeの埋め込み動画の再生開始video_url、video_title、video_provider、video_current_time、visible
video_progressYouTube動画が10／25／50／75％に到達video_startと同じパラメーターに加えてvideo_percent
video_completeYouTube動画が最後まで再生video_startと同じ
file_downloadファイルへのリンク（pdf、xls、doc、zipなど）をクリックfile_name、file_extension、link_url、link_text、link_domain
form_startフォームへの最初の操作form_id、form_name、form_destination
form_submitフォームの送信form_id、form_name、form_destination、form_submit_text

**注：**動画トラッキングは、enablejsapi=1を指定したYouTubeの埋め込み動画でのみ機能します。

推奨イベント — すべてのプロパティ

イベントパラメーター
loginmethod（STRING）
sign_upmethod（STRING）
sharemethod（STRING）、content_type（STRING）、item_id（STRING）
searchsearch_term（STRING）
select_contentcontent_type（STRING）、content_id（STRING）
gtag('event', 'login', { method: 'Google' });
gtag('event', 'sign_up', { method: 'Email' });
gtag('event', 'search', { search_term: 'running shoes' });

推奨イベント — Eコマース

ファネル全体をレポートするには、順番に実装してください。

view_item_list
gtag('event', 'view_item_list', {
  item_list_id: 'category_123',
  item_list_name: 'Running Shoes',
  items: [{
    item_id: 'SKU_123', item_name: 'Trail Runner Pro', item_brand: 'RunCo',
    item_category: 'Shoes', item_category2: 'Running', item_variant: 'Blue',
    price: 129.99, currency: 'USD', index: 0,
    item_list_id: 'category_123', item_list_name: 'Running Shoes'
  }]
});
select_item
gtag('event', 'select_item', {
  item_list_id: 'category_123', item_list_name: 'Running Shoes',
  items: [{ item_id: 'SKU_123', item_name: 'Trail Runner Pro', price: 129.99, currency: 'USD', index: 0 }]
});
view_item
gtag('event', 'view_item', {
  currency: 'USD', value: 129.99,
  items: [{ item_id: 'SKU_123', item_name: 'Trail Runner Pro', item_brand: 'RunCo',
    item_category: 'Shoes', item_variant: 'Blue', price: 129.99, currency: 'USD', quantity: 1 }]
});
add_to_cart
gtag('event', 'add_to_cart', {
  currency: 'USD', value: 129.99,
  items: [{ item_id: 'SKU_123', item_name: 'Trail Runner Pro', price: 129.99, currency: 'USD', quantity: 1 }]
});
remove_from_cart
gtag('event', 'remove_from_cart', {
  currency: 'USD', value: 129.99,
  items: [{ item_id: 'SKU_123', item_name: 'Trail Runner Pro', price: 129.99, currency: 'USD', quantity: 1 }]
});
view_cart
gtag('event', 'view_cart', {
  currency: 'USD', value: 259.98,
  items: [
    { item_id: 'SKU_123', item_name: 'Trail Runner Pro', price: 129.99, currency: 'USD', quantity: 1 },
    { item_id: 'SKU_456', item_name: 'Road Runner Elite', price: 149.99, currency: 'USD', quantity: 1 }
  ]
});
begin_checkout
gtag('event', 'begin_checkout', {
  currency: 'USD', value: 259.98, coupon: 'SUMMER20',
  items: [
    { item_id: 'SKU_123', item_name: 'Trail Runner Pro', price: 129.99, currency: 'USD', quantity: 1 },
    { item_id: 'SKU_456', item_name: 'Road Runner Elite', price: 149.99, currency: 'USD', quantity: 1 }
  ]
});
add_shipping_info
gtag('event', 'add_shipping_info', {
  currency: 'USD', value: 259.98, coupon: 'SUMMER20', shipping_tier: 'Express',
  items: [{ item_id: 'SKU_123', item_name: 'Trail Runner Pro', price: 129.99, currency: 'USD', quantity: 1 }]
});
add_payment_info
gtag('event', 'add_payment_info', {
  currency: 'USD', value: 259.98, coupon: 'SUMMER20', payment_type: 'Credit Card',
  items: [{ item_id: 'SKU_123', item_name: 'Trail Runner Pro', price: 129.99, currency: 'USD', quantity: 1 }]
});
purchase
gtag('event', 'purchase', {
  transaction_id: 'T12345',  // REQUIRED — unique transaction ID
  value: 259.98,             // REQUIRED — total value
  currency: 'USD',           // REQUIRED — ISO 4217
  tax: 20.80,
  shipping: 9.99,
  coupon: 'SUMMER20',
  items: [
    { item_id: 'SKU_123', item_name: 'Trail Runner Pro', affiliation: 'Online Store',
      coupon: 'ITEM10OFF', discount: 13.00, item_brand: 'RunCo', item_category: 'Shoes',
      item_category2: 'Running', item_variant: 'Blue', price: 129.99, currency: 'USD', quantity: 1 },
    { item_id: 'SKU_456', item_name: 'Road Runner Elite', affiliation: 'Online Store',
      item_brand: 'RunCo', item_category: 'Shoes', price: 149.99, currency: 'USD', quantity: 1 }
  ]
});

重要：purchaseにはtransaction_id、value、currencyが必要です。GA4は72時間以内のtransaction_idによって重複を排除します。

refund
// Full refund
gtag('event', 'refund', { transaction_id: 'T12345', value: 259.98, currency: 'USD' });

// Partial refund
gtag('event', 'refund', {
  transaction_id: 'T12345', value: 129.99, currency: 'USD',
  items: [{ item_id: 'SKU_123', price: 129.99, currency: 'USD', quantity: 1 }]
});

推奨イベント — リード獲得

generate_lead
gtag('event', 'generate_lead', { currency: 'USD', value: 50.00 });

推奨イベント — ゲーム

イベントパラメーター
earn_virtual_currencyvirtual_currency_name（STRING）、value（NUMBER）
spend_virtual_currencyvirtual_currency_name（STRING）、value（NUMBER）、item_name（STRING）
level_uplevel（NUMBER）、character（STRING）
post_scorescore（NUMBER、必須）、level（NUMBER）、character（STRING）
tutorial_beginなし
tutorial_completeなし
unlock_achievementachievement_id（STRING、必須）
gtag('event', 'earn_virtual_currency', { virtual_currency_name: 'Coins', value: 100 });
gtag('event', 'spend_virtual_currency', { virtual_currency_name: 'Coins', value: 50, item_name: 'Power Boost' });
gtag('event', 'level_up', { level: 5, character: 'Warrior' });
gtag('event', 'post_score', { score: 15000, level: 5, character: 'Warrior' });
gtag('event', 'tutorial_begin');
gtag('event', 'tutorial_complete');
gtag('event', 'unlock_achievement', { achievement_id: 'first_blood' });

アイテムパラメーターのリファレンス

items配列では、アイテムごとに以下のパラメーターを指定できます。

パラメーター型説明
item_idSTRINGSKU／ID（推奨）
item_nameSTRING表示名（推奨）
affiliationSTRINGストアまたは提携先
couponSTRINGアイテム単位のクーポン
discountNUMBER割引額
indexNUMBERリスト内の位置
item_brandSTRINGブランド名
item_categorySTRING主なカテゴリ
item_category2-5STRINGカテゴリレベル2～5
item_list_idSTRINGリストID
item_list_nameSTRINGリスト名
item_variantSTRINGバリエーション（色、サイズ）
location_idSTRING実店舗の所在地
priceNUMBERアイテムの価格
currencySTRINGISO 4217コード
quantityNUMBER数量
promotion_idSTRINGプロモーションID
promotion_nameSTRINGプロモーション名
creative_nameSTRINGプロモーションのクリエイティブ
creative_slotSTRINGクリエイティブの掲載枠

item_idまたはitem_nameのいずれかが必須です。イベントごとのアイテム数は最大200件です。

カスタムイベント

自動収集イベント、拡張計測イベント、推奨イベントのいずれにも該当しない場合に使用します。

命名規則
  • 最大 40 文字
  • アルファベットで始める必要があります
  • 使用できる文字は [a-zA-Z][a-zA-Z0-9_]* のみです
  • 大文字と小文字を区別します — Add_To_Cart と add_to_cart は異なるイベントです
  • 予約済みのプレフィックスは使用できません：firebase_、google_、ga_
  • 予約済みのイベント名は使用できません（例：first_visit、session_start、app_install、in_app_purchase など）
上限
上限値
プロパティあたりの一意なイベント名500
イベントあたりのパラメータ25
パラメータ名の長さ40 文字
パラメータ値（文字列）100 文字
ユーザープロパティ名の長さ24 文字
ユーザープロパティ値（文字列）36 文字
プロジェクトあたりのユーザープロパティ25
例
gtag('event', 'newsletter_signup', {
  newsletter_type: 'weekly_digest', signup_location: 'footer'
});

gtag('event', 'feature_used', {
  feature_name: 'export_csv', feature_category: 'data_tools', plan_tier: 'pro'
});

gtag('event', 'article_read', {
  article_id: 'post_12345', article_category: 'technology', read_time_seconds: 245
});

カスタムディメンションと指標

レポートでイベントパラメータまたはユーザープロパティを使用するには、Admin > Custom definitions で登録します。

スコープ
スコープソース使用例
イベントスコープのディメンションイベントパラメータページ／アクションの属性
ユーザースコープのディメンションユーザープロパティ永続的なユーザー属性
カスタム指標イベントパラメータ（数値）数値の集計
割り当て上限
リソースStandardAnalytics 360
イベントスコープのカスタムディメンション50125
ユーザースコープのカスタムディメンション25100
カスタム指標50125

処理時間：標準レポートでは24～48時間（Realtime／DebugViewでは即時）。

// Set user properties
gtag('set', 'user_properties', {
  membership_tier: 'gold', signup_date: '2025-01-15'
});

GTM dataLayer の実装

// Custom event
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
  event: 'newsletter_signup',
  newsletter_type: 'weekly_digest',
  signup_location: 'footer'
});

// E-commerce — ALWAYS clear ecommerce first
window.dataLayer.push({ ecommerce: null });
window.dataLayer.push({
  event: 'purchase',
  ecommerce: {
    transaction_id: 'T12345', value: 259.98, currency: 'USD',
    tax: 20.80, shipping: 9.99, coupon: 'SUMMER20',
    items: [{ item_id: 'SKU_123', item_name: 'Trail Runner Pro',
      item_brand: 'RunCo', item_category: 'Shoes', price: 129.99, quantity: 1 }]
  }
});

Measurement Protocol（サーバーサイド）

POST https://www.google-analytics.com/mp/collect?measurement_id=G-XXXXXXXXXX&api_secret=YOUR_API_SECRET

{
  "client_id": "abc123.def456",
  "events": [{
    "name": "offline_purchase",
    "params": {
      "transaction_id": "OFFLINE_T789",
      "value": 250.00,
      "currency": "USD"
    }
  }]
}

import requests, json

url = 'https://www.google-analytics.com/mp/collect?measurement_id=G-XXXXXXXXXX&api_secret=YOUR_API_SECRET'
payload = {
    'client_id': 'abc123.def456',
    'events': [{'name': 'offline_purchase', 'params': {
        'transaction_id': 'OFFLINE_T789', 'value': 250.00, 'currency': 'USD'
    }}]
}
response = requests.post(url, data=json.dumps(payload))

制限事項： レスポンスの検証は行われません（デバッグエンドポイントを使用してください）。client_id は既存の GA4 Cookie と一致する必要があります。イベントは Realtime に表示されません（30分の遅延）。first_visit／session_start はトリガーできません。

検証サーバー
POST https://www.google-analytics.com/debug/mp/collect?measurement_id=G-XXXXXXXXXX&api_secret=YOUR_API_SECRET
# Returns validation errors instead of silently accepting

検証とデバッグ

DebugView

デバッグモードを有効にすると、ほぼリアルタイムで Admin > DebugView にイベントが表示されます。

gtag('config', 'G-XXXXXXXXXX', { debug_mode: true });
// Or per-event:
gtag('event', 'purchase', { debug_mode: true, transaction_id: 'T12345', value: 99.99, currency: 'USD' });
BigQuery の検証クエリ

イベント数の監査：

SELECT event_name, COUNT(*) as event_count, COUNT(DISTINCT user_pseudo_id) as unique_users
FROM `project.analytics_123456789.events_*`
WHERE _TABLE_SUFFIX = FORMAT_DATE('%Y%m%d', CURRENT_DATE() - 1)
GROUP BY event_name ORDER BY event_count DESC

購入パラメータの欠落：

SELECT 'missing_transaction_id' as issue, COUNT(*) as count
FROM `project.analytics_123456789.events_*`
WHERE _TABLE_SUFFIX = FORMAT_DATE('%Y%m%d', CURRENT_DATE() - 1)
  AND event_name = 'purchase'
  AND (SELECT value.string_value FROM UNNEST(event_params) WHERE key = 'transaction_id') IS NULL
UNION ALL
SELECT 'missing_currency', COUNT(*)
FROM `project.analytics_123456789.events_*`
WHERE _TABLE_SUFFIX = FORMAT_DATE('%Y%m%d', CURRENT_DATE() - 1)
  AND event_name = 'purchase'
  AND (SELECT value.string_value FROM UNNEST(event_params) WHERE key = 'currency') IS NULL

トランザクションの重複：

SELECT transaction_id, COUNT(*) as dupes
FROM (
  SELECT (SELECT value.string_value FROM UNNEST(event_params) WHERE key = 'transaction_id') as transaction_id
  FROM `project.analytics_123456789.events_*`
  WHERE _TABLE_SUFFIX BETWEEN FORMAT_DATE('%Y%m%d', DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY))
                          AND FORMAT_DATE('%Y%m%d', CURRENT_DATE() - 1)
    AND event_name = 'purchase'
)
WHERE transaction_id IS NOT NULL
GROUP BY transaction_id HAVING COUNT(*) > 1
ORDER BY dupes DESC

命名規則の監査：

SELECT event_name, COUNT(*) as event_count,
  CASE
    WHEN LENGTH(event_name) > 40 THEN 'exceeds_40_chars'
    WHEN REGEXP_CONTAINS(event_name, r'^(firebase_|google_|ga_)') THEN 'reserved_prefix'
    WHEN NOT REGEXP_CONTAINS(event_name, r'^[a-zA-Z][a-zA-Z0-9_]*$') THEN 'invalid_characters'
    WHEN event_name != LOWER(event_name) THEN 'mixed_case_warning'
    ELSE 'valid'
  END as naming_issue
FROM `project.analytics_123456789.events_*`
WHERE _TABLE_SUFFIX = FORMAT_DATE('%Y%m%d', CURRENT_DATE() - 1)
GROUP BY event_name HAVING naming_issue != 'valid'

パラメータの切り詰めチェック：

SELECT event_name, ep.key, MAX(LENGTH(ep.value.string_value)) as max_len,
  COUNTIF(LENGTH(ep.value.string_value) >= 100) as at_limit
FROM `project.analytics_123456789.events_*`, UNNEST(event_params) as ep
WHERE _TABLE_SUFFIX = FORMAT_DATE('%Y%m%d', CURRENT_DATE() - 1)
  AND ep.value.string_value IS NOT NULL
GROUP BY 1, 2 HAVING max_len >= 100

よくある落とし穴

  1. 大文字と小文字の区別 — Purchase != purchase。必ず snake_case を使用してください。
  2. 100文字での文字列の切り詰め — URL や長い値は、通知なしに切り詰められます。
  3. カスタムディメンションの上限 — イベントスコープは50、ユーザースコープは25（標準）。慎重に計画してください。
  4. 購入の重複 — 重複排除のため、必ず transaction_id を含めてください（72時間の期間）。
  5. 通貨の欠落 — currency のない value は、収益化レポートで無視されます。
  6. 古い dataLayer — GTM で eコマースイベントを送信する前に、必ず { ecommerce: null } を push してください。
  7. パラメータ内の PII — メールアドレス、電話番号、氏名を含めないでください。GA4 の利用規約に違反します。
  8. 動的なイベント名 — 500件の名前の上限をすぐに使い切ってしまいます。代わりにパラメータを使用してください。

リソース

コメント

Markdown 対応