GA4の計測設計書をClaudeで作る — イベント名とパラメータの決め方

GA4の計測設計書は、「どのKPIを見るために、どのイベントを、どのパラメータ付きで送るか」を1枚にまとめた表です。Claudeに作らせるときの要点は、KPIから逆算させる順番を固定し、GA4の予約語と上限は人が書いたルールとスクリプトで機械的に検査することにあります。この記事では、BtoBサービスのサイトを例に、KPIの整理から命名規則、パラメータ表、検査スクリプトまでを順に作ります。

すでに集めたGA4のデータを自然言語で分析する方法は、Claude CodeにGA4のMCPサーバーを繋ぐ手順にあります。ここで扱うのは、データを取る前の設計です。

計測設計書に書く列は9つで足りる

設計書の列が多すぎると、実装者もClaudeも埋めきれません。次の9列に絞ると、設計と実装の受け渡しに必要な情報が揃います。

「種別」の列がこの表の核です。GA4のイベントは、自動収集、拡張計測機能、推奨、カスタムの4種類に分かれます。前の2つはタグを設定すれば集まり、推奨イベントは名前とパラメータが決まっていて実装は自分で行い、カスタムイベントは自分で定義します。同じ行動を測るなら、上から順に探して最初に当てはまる種類を使います。

KPIから逆引きする4つの問い

Claudeに「イベントを考えて」と丸投げすると、思いつく名前を並べるだけの表になります。代わりに、KPIごとに次の4問へ順に答えさせます。

この順番はGA4のヘルプにある考え方と同じです。カスタムイベントは他のイベントが適切でない場合にのみ作る、と書かれており、既存のイベントなら、レポートで使うディメンションと指標が自動的に入ります。

推奨イベントの候補は種類が多い

推奨イベントは、すべてのプロパティ向けのものと、オンライン販売向けのものに分かれています。すべてのプロパティ向けには、generate_lead(問い合わせ用のフォームやリクエストの送信)、sign_up(アカウント登録)、login、search、select_content、share、tutorial_begin、tutorial_complete などが並びます。ECを持たないBtoBサイトでも、この範囲だけで問い合わせ、登録、ログイン、検索、チュートリアルの計測がカバーできます。

オンライン販売向けには add_to_cart、begin_checkout、purchase、view_item などがあり、送信するとeコマース購入レポートにデータが入ります。物販やチケット販売でなければ、この一群は設計書に載せなくて構いません。

Claudeに渡す入力と、返してもらう形

設計書づくりでClaudeに渡すものは3つです。KPIの一覧、サイトの画面とボタンの一覧、そして守る命名規則です。命名規則は次のように書いて、プロジェクトのメモやプロンプトの冒頭に固定します。

# GA4 計測設計の規約
- イベント名・パラメータ名は小文字の英語 snake_case(例: cta_click)
- 動詞は「対象_動作」の順(例: select_plan ではなく plan_select)
- 同じ行動に推奨イベントがあれば必ずそれを使う。カスタムは理由を1行書く
- イベント名は39文字以内、パラメータは1イベント25個以内(GA4の上限)に収める
- 予約済みの名前と接頭辞(ga_ / google_ / firebase_ / gtag. / 先頭の _)は使わない
- 返す形式は CSV(列: kpi,action,event_name,type,parameters,key_event,custom_dimension)

入力のうち一番効くのは、KPIを数字ではなく行動の言葉で渡すことです。たとえば「CVRを上げたい」ではなく「資料請求フォームの送信完了と、料金ページからのCTAクリックを分けて見たい」と書くと、Claudeは行動単位でイベントを切り出せます。

プロンプトの例を示します。

次のKPIごとに、計測設計書の行を作ってください。
手順は KPI → ユーザー行動 → 自動収集/拡張計測で足りるか → 推奨イベントに
該当するか → どれにも当たらないときだけカスタム、の順です。
推奨イベントを選ぶときは、公式のイベント一覧に載っている名前だけを使い、
載っていない名前を推奨と呼ばないでください。不明な点は「要確認」と書いてください。
 
KPI:
1. 資料請求フォームの送信数
2. 無料トライアルのアカウント登録数
3. 料金ページで押されたCTAのうち、どの位置のボタンかの内訳
4. 料金プラン比較表で選ばれたプラン

最後の「載っていない名前を推奨と呼ばない」という一文が重要です。Claudeはもっともらしい推奨風の名前(request_demo のような)を作りやすく、それが公式の推奨イベントかどうかは人が一覧で確かめる必要があります。ここで確認用の一覧は、GA4ヘルプの「[GA4]推奨イベント」ページです。

返ってきた表の例

次の表は、上のKPIに対する設計書の例です。Claudeの出力そのものではなく、設計の考え方を示すための例です。

推奨イベントの既定パラメータ(generate_lead が持つものなど)は、各イベントのページで確認します。上の表では、自社で足すパラメータだけを書いています。

命名規則はGA4側の制約から先に決める

規約を人の好みだけで決めると、後から予約語にぶつかります。GA4が課している制約を先に表にしておくと、Claudeへの指示も短くなります。

イベント名の長さは、2つのページで「40文字」と「40文字未満」の書き方が違います。設計では39文字以内を規約にしておけば、どちらの読み方でも通ります。40文字を超えるイベント名は、キーイベントにしてもキーイベントとしてレポートされません。

もう一つ、イベント名には「英語と英語以外の単語および文字を使用できます」との記述がある一方、先頭は英字で英数字とアンダースコアのみとも書かれています。日本語のイベント名は避け、英語のsnake_caseに寄せるのが安全です。カスタムイベントのページ自体は、寄付を測るなら「寄付」のような名前を付けてよいと例示していますが、集計・共有・Claudeへの指示のしやすさを考えると、英語名にする理由のほうが大きくなります。

予約語と上限は、Claudeに頼らずスクリプトで検査する

GA4の予約済みイベント名には、page_view、scroll、file_download、form_start、form_submit、session_start などが含まれます。ここで落とし穴になるのが form_submit です。フォームの送信を測りたくて、素直に form_submit と名付けたくなりますが、予約済みなので使えません。推奨イベントの generate_lead に寄せるか、contact_form_submit のように別名にします。

予約済みのパラメータ名にも user_id、session_id、currency、gclid などがあり、これらはカスタムディメンションやカスタム指標の作成に使えません。「ユーザーを識別するパラメータを付けたい」と考えて user_id を選ぶと、レポートに出せなくなります。

予約語のリストは、ヘルプに「記載されていないものもあり、定期的に更新される可能性がある」とあります。そのため、検査スクリプトは「確実に落とせるものを落とす」道具と割り切り、最後の確認はGA4の管理画面で行います。

次のスクリプトは、設計書をCSV(列は event_name と、| で区切った parameters)で書き出したあとに実行します。

import csv, re, sys
 
RESERVED_EVENTS = {"ad_impression","app_remove","app_store_refund","file_download",
  "first_open","first_visit","form_start","form_submit","in_app_purchase","page_view",
  "scroll","session_start","user_engagement","view_search_results",
  "video_start","video_progress"}
RESERVED_PARAMS = {"cid","currency","customer_id","customerid","dclid","gclid",
  "session_id","sessionid","sfmc_id","sid","srsltid","uid","user_id","userid"}
BAD_PARAM_PREFIX = ("_", "firebase_", "ga_", "google_", "gtag.")
 
def check(path):
    errors = []
    with open(path, newline="", encoding="utf-8") as f:
        for n, row in enumerate(csv.DictReader(f), start=2):
            ev = row["event_name"].strip()
            params = [p.strip() for p in row["parameters"].split("|") if p.strip()]
            if not re.fullmatch(r"[A-Za-z][A-Za-z0-9_]*", ev):
                errors.append(f"L{n} {ev}: 先頭が英字・英数字とアンダースコアのみ、に違反")
            if ev != ev.lower():
                errors.append(f"L{n} {ev}: 大文字を含む(社内規約は小文字)")
            if len(ev) >= 40:
                errors.append(f"L{n} {ev}: 40文字未満にする")
            if ev in RESERVED_EVENTS:
                errors.append(f"L{n} {ev}: 予約済みイベント名")
            if len(params) > 25:
                errors.append(f"L{n} {ev}: パラメータが{len(params)}個(上限25)")
            for p in params:
                if len(p) > 40:
                    errors.append(f"L{n} {ev}.{p}: パラメータ名が40文字超")
                if p in RESERVED_PARAMS or p.startswith(BAD_PARAM_PREFIX):
                    errors.append(f"L{n} {ev}.{p}: 予約済みのパラメータ名または接頭辞")
    return errors
 
if __name__ == "__main__":
    errs = check(sys.argv[1])
    print("\n".join(errs) if errs else "OK")
    sys.exit(1 if errs else 0)

わざと違反を混ぜたCSVで動かすと、次のように出ます。

event_name,parameters
generate_lead,form_id|cta_location
cta_click,cta_location|cta_label
Plan_Select,plan_name|user_id
form_submit,form_id

python3 check_ga4_spec.py spec.csv

L4 Plan_Select: 大文字を含む(社内規約は小文字)
L4 Plan_Select.user_id: 予約済みのパラメータ名または接頭辞
L5 form_submit: 予約済みイベント名

Claude Codeを使っているなら、「設計書CSVを書いたら、このスクリプトを実行して、違反を直して再実行する。OKが出るまで繰り返す」と指示します。Claudeが自分の書いた表の誤りを、出力を読んで直す反復になります。スクリプトの結果は人が読み返さなくてよい部分を増やし、人は「このKPIにこのイベントで本当に足りるか」の判断に時間を使えます。

レポートに出したいパラメータだけ、カスタムディメンションにする

パラメータを送っても、レポートで見るにはカスタムディメンションかカスタム指標の作成が要ります。設計書の「カスタムディメンション」列は、ここを決めるためにあります。

• 送るだけで見ないパラメータ(実装確認や、BigQueryで後から使う用途)は、ディメンションを作らない
• レポートや探索で軸にしたいパラメータ(cta_location、plan_name など)だけ、イベントスコープで作成する
• 作成後、任意のレポートに追加できるようになるまで24〜48時間かかる

候補の値の数にも注意します。500個を超える値を持つディメンションは「高基数」とみなされ、レポートやデータ探索でシステム上の制限を受けて、値が「(other)」行にまとめられたり、サンプリングが入ったりします。page_location のようにURLごとに値が変わるものを、ディメンションの軸にする前に確認してください。cta_location のように、値が5〜10個に収まる設計が向いています。

また、ヘルプには、パラメータの整数値がアプリのイベントスコープのカスタムディメンションでは解析されない(ウェブでは解析される)旨が書かれています。ウェブとアプリの両方を計測する場合は、plan_name のように英数字の値を使うほうが取り違えません。

実装と確認の列は、手順まで書いておく

設計書で一番抜けやすいのが、「実装した人が合格を判断できる記述」です。確認方法の列には、GA4の2つのレポートのどちらで何を見るかを書きます。

• リアルタイムレポート: 「イベント名別のイベント数」カードに、過去30分のイベントと回数が出る。イベントをクリックすると、そのイベントと一緒に送られたパラメータが見える
• DebugView: 1人のユーザーが発火したすべてのイベントが出る。デバッグモードを有効にして使い、イベントとパラメータが正しく設定されているかの確認に向く

Claudeには、各行の「確認方法」を「DebugViewで cta_click が出て、cta_location が pricing_hero になること」のように、ボタンごとの期待値で書かせます。「イベントが出ること」だけでは、パラメータの取りこぼしを見逃します。

キーイベントは増やしすぎない

収集したどのイベントでもキーイベントにできます。キーイベントは、ビジネスの成功にとって特に重要なアクションを測るためのものです。上の例では generate_lead と sign_up だけをキーイベントにし、cta_click や plan_select は途中経過として残します。キーイベントは、バッチに含まれる場合でも即時に送信されます。キーイベントを増やすほど、成果の定義があいまいになります。

よくある食い違いと、Claudeへの指示の直し方

設計書をレビューするときに、Claudeの案で繰り返し見直すことになる点を並べます。

どの行も、原因はClaudeの能力ではなく、判断基準が指示に入っていないことにあります。基準を規約として文書にして、毎回の入力に貼る運用にすると、人が替わっても設計書の品質が揃います。

設計書ができたあとの使い方

計測設計書は、実装依頼のチケットに貼る資料でもあり、取れたデータを分析するときの辞書でもあります。

• 実装: タグマネージャーのトリガーやdataLayerの仕様に、設計書の行を1行ずつ落とす。Claudeにイベント行を渡して、dataLayerのpushコード案を作らせることもできる
• 分析: BigQueryへのエクスポートを使う場合の週次レポートの作り方は、GA4のBigQueryをClaudeで分析する手順にある
• 流入の側の確認: 検索流入が伸びないページの切り分けは、GA4とSearch Consoleの突き合わせで扱っている
• 離脱の理由: ヒートマップ系の観察はMicrosoft Clarityとの連携が補う

設計書を更新するたびに、検査スクリプトとプロンプトをそのまま再実行します。KPIが増えたら行を足し、イベントを廃止するときは「廃止日」の列を足して消さずに残すと、過去データの読み違いを防げます。

設計書に書かないほうがよいこと

最後に、Claudeに渡す前に決めておく線を挙げます。

• 個人を直接特定できる値(メールアドレスや氏名)をパラメータ例に入れない。例を作らせるときも、ダミー値と明記する
• Claudeが作った案を、そのまま本番のプロパティへ反映しない。設計書は検査スクリプトとDebugViewの2段階で確かめてから実装する
• 数量の上限や予約語は、今後変わる可能性がある。設計書のレビュー時に、GA4ヘルプの該当ページを開き直す

イベントの設計は、一度決めると変えにくい作業です。名前を変えると過去データと分断されるため、最初に規約と上限を固めておく価値があります。Claudeには、列挙と整形と検査の反復を任せ、KPIの定義と成果の判断は人が持つ、という分担が実務で扱いやすい形です。