GA4 / GTM 連携実装仕様書¶

概要¶

Vendure 自体には GA4 / GTM 向けの dataLayer 自動送信機能がないため、本プロジェクトでは Storefront 側でカスタム実装を行っています。現在は GTM コンテナ / 任意スクリプトの注入に加え、主要な E コマースイベントを dataLayer に自動送信できる状態です。

現在の実装状況¶

有効な実装¶

GTM コンテナ / 任意スクリプト注入
Channel.customFields の gtmContainerId / headScript / bodyScript を Storefront が読み取り、head / body に挿入する。
Storefront の dataLayer 自動送信
商品一覧、商品詳細、カート、チェックアウト、購入完了、ログイン、初回セットアップ完了の主要イベントを自動送信する。
購入完了イベントの重複防止
purchase は同一ブラウザタブ内で注文コードごとに一度だけ送信する。

実装済みイベント一覧¶

イベント	受け入れ側で確認する操作	送信タイミング	備考
`view_item_list`	商品一覧ページを開く	商品一覧描画後	検索語・ブランド・カテゴリから list 名を構成
`select_item`	商品一覧カードから商品詳細へ遷移する	商品カードクリック時	一覧コンテキストを維持して送信
`view_item`	商品詳細ページを開く	商品詳細初期表示時	表示中バリアント単位で送信
`add_to_cart`	商品詳細 / 一覧からカート追加する	`addItemToOrder` 成功後	失敗時は送信しない
`remove_from_cart`	カートから商品を削除する	`removeOrderLine` 成功後	削除前の行情報を送信
`view_cart`	カートページを開く	注文明細表示時	明細が 1 行以上ある場合のみ送信
`begin_checkout`	チェックアウトページを開く	注文明細ありで初回表示した時	明細が空のときは送信しない
`add_shipping_info`	注文確定操作を行い配送方法設定が成功する	`setOrderShippingMethod` 成功後	配送方法名を `shipping_tier` として送信
`add_payment_info`	注文確定操作を行い決済追加が成功する	`addPaymentToOrder` 成功後	決済方法名を `payment_type` として送信
`purchase`	注文完了ページを表示する	完了ページ表示時	`paymentStatus=cancelled` のときは送信しない
`login`	ログインする	`login` 成功後	パスワードログインを `method=password` として送信
`sign_up`	初回セットアップを完了する	`updateCustomerCredentials` 成功後	公開会員登録ではなく「初回セットアップ完了」を計測

現在送信している主な dataLayer 情報¶

標準 E コマース項目¶

event
ecommerce.transaction_id
ecommerce.currency
ecommerce.value
ecommerce.shipping
ecommerce.items[]
item_id
item_name
item_brand
item_category
item_variant
item_list_id
item_list_name
index
price
quantity

B2B 向け追加項目¶

ecommerce.custom_dimensions として、Storefront から取得可能な範囲で次を送信します。

customer_type: 顧客ステータス
discount_rate: 掛率
shipping_mode: 配送モード (NORMAL / DIRECT)
order_type: shipping_mode から導出した注文種別

送信しない情報¶

メールアドレス
氏名
電話番号
配送先住所
その他の個人情報

受け入れ確認手順¶

対象 Channel に gtmContainerId を設定する。
GTM Preview mode または GA4 DebugView を有効にする。
以下の順で画面操作を行い、対応するイベント名が確認できることを確認する。
商品一覧表示 → view_item_list
商品カードクリック → select_item
商品詳細表示 → view_item
カート追加 → add_to_cart
カート表示 → view_cart
カート削除 → remove_from_cart
チェックアウト表示 → begin_checkout
注文確定成功 → add_shipping_info / add_payment_info
注文完了ページ表示 → purchase
ログイン成功 → login
初回セットアップ成功 → sign_up
同一タブ内で注文完了ページを再読み込みしても、同じ注文コードの purchase が重複送信されないことを確認する。

未対応 / 別途検討事項¶

現時点では以下は送信していません。

refund
payment_terms
business_unit
taxSummary ベースの税額詳細
ハッシュ化 User ID

これらを追加する場合は、Storefront だけで取得できない値をどこで生成・保持するか、ならびにプライバシー要件を先に整理してください。

設定と運用¶

Channel 側設定¶

gtmContainerId
headScript
bodyScript

運用上の注意¶

GTM / GA4 側でタグ・トリガー・変数を作成しない限り、dataLayer に push されても計測値として集計されません。
purchase の重複防止は 同一タブの sessionStorage を使っています。別タブや別セッションで完了ページを再表示した場合の扱いは、GTM / GA4 側でも重複排除方針を持つことを推奨します。
sign_up は一般公開の新規会員登録ではなく、仮 ID 利用者の初回セットアップ完了を意味します。

開発者向け補足¶

主な実装箇所は以下です。

apps/storefront/src/components/tracking/tracking-tag-injector.tsx
apps/storefront/src/lib/analytics/ga4.ts
apps/storefront/src/components/pages/products-page-content.tsx
apps/storefront/src/components/product/product-card.tsx
apps/storefront/src/components/product/product-detail.tsx
apps/storefront/src/components/product/add-to-cart-button.tsx
apps/storefront/src/components/cart/cart-page-content.tsx
apps/storefront/src/components/cart/cart-line-item.tsx
apps/storefront/src/components/checkout/checkout-page-content.tsx
apps/storefront/src/components/pages/checkout-complete-page-content.tsx
apps/storefront/src/components/auth/login-page-content.tsx
apps/storefront/src/components/auth/temporary-setup-form.tsx