gtm-implementation

GTM の実装 - DataLayer + GTM API

コードに dataLayer イベントを追加し、API を介して GTM の変数、トリガー、タグを作成することで、GTM トラッキングを完全に実装します。

主な目的

分析に対応した DOM 要素を、次の方法で完全にトラッキングされたイベントに変換します。

1. コードの実装：React／Next.js／Vue コンポーネントに dataLayer.push() の呼び出しを追加します
2. GTM の設定：GTM API を介して変数、トリガー、タグを作成します

ワークフロー

フェーズ 0：ビジネスコンテキストの読み込み（利用可能な場合）

プロジェクトのルートにある gtm-context.md を確認します。

• 見つかった場合：内容を表示せずに読み込み、このスキルの実行中はビジネスコンテキストを使用します
• 見つからない場合：通常どおり進め、ワークフロー中に必要に応じてコンテキストについて質問します

このファイルは、gtm-analytics-audit の初回実行の最後に自動作成されます。

フェーズ 1：コンテキストと前提条件

ステップ 1.1：トラッキング計画の読み込み

Check for gtm-tracking-plan.json (from gtm-strategy skill):
- If exists → Load events and parameters
- If missing → Ask user which events to implement OR suggest running gtm-strategy first

Check for gtm-config.json and gtm-token.json (from gtm-setup skill):
- If missing → Suggest running gtm-setup skill first
- If exists → Verify API connection

ステップ 1.2：フレームワークの検出

Check package.json:
- React version
- Next.js version and router type (App Router vs Pages Router)
- Vue version
- TypeScript vs JavaScript

This determines:
- Component file extensions (.tsx vs .jsx vs .vue)
- Import patterns
- Syntax for className vs class
- 'use client' directive for Next.js App Router

ステップ 1.3：対象要素のスキャン

Using Glob and Grep, find elements to instrument:

For CTA tracking:
- Search for: class=".*js-cta.*" or id="cta_.*"
- Search for: <button, <Link components

For form tracking:
- Search for: class=".*js-form.*" or id="form_.*"
- Search for: <form tags with onSubmit handlers

For navigation tracking:
- Search for: class=".*js-nav.*" or id="nav_.*"
- Search for: <Link, <a tags

Match found elements against events in tracking plan.

ステップ 1.4：アクティブなワークスペースの解決（動的）

GTM API の操作を行う前に、必ず現在のワークスペースを動的に解決します。

// List all workspaces for this container
const workspacesResponse = await tagmanager.accounts.containers.workspaces.list({
  parent: `accounts/${accountId}/containers/${containerId}`
})

const workspaces = workspacesResponse.data.workspace || []

if (workspaces.length === 0) {
  throw new Error('No workspaces found in this GTM container. Create one in the GTM UI first.')
}

// Always use the first available workspace
const workspace = workspaces[0]
const workspaceId = workspace.workspaceId

console.log(`✓ Active workspace: "${workspace.name}" (ID: ${workspaceId})`)

理由：GTM の UI で手動送信すると、GTM はワークスペースを削除し、新しい ID のワークスペースを作成します。gtm-config.json に保存されている workspaceId は古くなります。特定のワークスペース ID が存在すると決めつけないでください。

フェーズ 2：DataLayer の実装（コードの変更）

トラッキング計画内の各イベントについて、実際のコードファイルに dataLayer.push() を実装します。

ステップ 2.1：CTA クリックの実装

対象を見つける（例）：

// File: app/page.tsx
<button
  className="btn primary js-track js-cta js-click js-hero"
  id="cta_hero_get_started"
>
  Get Started
</button>

Edit ツールを使用してトラッキングを実装します。

変更前：

<button
  className="btn primary js-track js-cta js-click js-hero"
  id="cta_hero_get_started"
>
  Get Started
</button>

変更後：

<button
  className="btn primary js-track js-cta js-click js-hero"
  id="cta_hero_get_started"
  onClick={() => {
    if (typeof window !== 'undefined' && window.dataLayer) {
      window.dataLayer.push({
        event: 'cta_click',
        cta_location: 'hero',
        cta_type: 'primary',
        cta_text: 'Get Started',
        cta_destination: '/signup'
      })
    }
  }}
>
  Get Started
</button>

フレームワーク固有の考慮事項：

Next.js App Router（'use client' が必要）：

'use client'

import { useRouter } from 'next/navigation'

export default function HeroCTA() {
  const router = useRouter()

  return (
    <button
      className="btn primary js-track js-cta js-click js-hero"
      id="cta_hero_get_started"
      onClick={() => {
        // Track event
        if (typeof window !== 'undefined' && window.dataLayer) {
          window.dataLayer.push({
            event: 'cta_click',
            cta_location: 'hero',
            cta_type: 'primary',
            cta_text: 'Get Started',
            cta_destination: '/signup'
          })
        }
        // Navigate
        router.push('/signup')
      }}
    >
      Get Started
    </button>
  )
}

ステップ 2.2：フォーム送信の実装

対象を見つける：

<form
  className="contact-form js-track js-form js-submit js-hero"
  id="form_hero_contact"
  onSubmit={handleSubmit}
>

トラッキングを実装します。

変更前：

<form
  className="contact-form js-track js-form js-submit js-hero"
  id="form_hero_contact"
  onSubmit={handleSubmit}
>

変更後：

<form
  className="contact-form js-track js-form js-submit js-hero"
  id="form_hero_contact"
  onSubmit={(e) => {
    // Track form submission
    if (typeof window !== 'undefined' && window.dataLayer) {
      window.dataLayer.push({
        event: 'form_submit',
        form_name: 'contact',
        form_location: 'hero',
        form_type: 'contact_request'
      })
    }
    // Call original handler
    handleSubmit(e)
  }}
>

ステップ 2.3：ナビゲーションクリックの実装

対象を見つける（Next.js Link）：

<Link href="/pricing">Pricing</Link>

トラッキングを実装します。

変更前：

<Link
  href="/pricing"
  className="nav-link js-track js-nav js-click js-header"
  id="nav_header_pricing"
>
  Pricing
</Link>

変更後：

<Link
  href="/pricing"
  className="nav-link js-track js-nav js-click js-header"
  id="nav_header_pricing"
  onClick={() => {
    if (typeof window !== 'undefined' && window.dataLayer) {
      window.dataLayer.push({
        event: 'navigation_click',
        nav_location: 'header',
        nav_type: 'menu_link',
        nav_text: 'Pricing',
        nav_destination: '/pricing'
      })
    }
  }}
>
  Pricing
</Link>

ステップ 2.4：パラメーター抽出ロジック

DOM 要素からパラメーターを適切に抽出します。

cta_location：ID 属性から

// id="cta_hero_get_started" → location: "hero"
const id = element.getAttribute('id') // "cta_hero_get_started"
const location = id.split('_')[1] // "hero"

cta_text：ボタンの innerText から

// <button>Get Started</button> → cta_text: "Get Started"
cta_text: 'Get Started'

cta_destination：href またはプログラムによるナビゲーションから

// <Link href="/signup"> → cta_destination: "/signup"
// onClick={() => router.push('/pricing')} → cta_destination: "/pricing"

cta_type：CSS クラスから

// className includes "btn-primary" → type: "primary"
// className includes "btn-secondary" → type: "secondary"

フェーズ 3：GTM コンテナの設定（API 呼び出し）

DataLayer イベントを処理するため、GTM API を介して変数、トリガー、タグを作成します。

ステップ 3.1：データレイヤー変数の作成

各イベントの各パラメーターについて、GTM 変数を作成します。

例：cta_click イベントには 4 つの変数が必要です。

// Variable 1: CTA Location
{
  name: "DLV - CTA Location",
  type: "v",
  parameter: [
    { type: "TEMPLATE", key: "name", value: "cta_location" },
    { type: "INTEGER", key: "dataLayerVersion", value: "2" }
  ]
}

// Variable 2: CTA Type
{
  name: "DLV - CTA Type",
  type: "v",
  parameter: [
    { type: "TEMPLATE", key: "name", value: "cta_type" },
    { type: "INTEGER", key: "dataLayerVersion", value: "2" }
  ]
}

// Variable 3: CTA Text
{
  name: "DLV - CTA Text",
  type: "v",
  parameter: [
    { type: "TEMPLATE", key: "name", value: "cta_text" },
    { type: "INTEGER", key: "dataLayerVersion", value: "2" }
  ]
}

// Variable 4: CTA Destination
{
  name: "DLV - CTA Destination",
  type: "v",
  parameter: [
    { type: "TEMPLATE", key: "name", value: "cta_destination" },
    { type: "INTEGER", key: "dataLayerVersion", value: "2" }
  ]
}

GTM API を使用して作成します。

tagmanager.accounts.containers.workspaces.variables.create({
  parent: `accounts/${accountId}/containers/${containerId}/workspaces/${workspaceId}`,
  requestBody: variableConfig
})

ステップ 3.2：カスタムイベントトリガーの作成

各イベントについて、そのカスタムイベントで発火するトリガーを作成します。

例：cta_click トリガー

{
  name: "CE - CTA Click",
  type: "CUSTOM_EVENT",
  customEventFilter: [
    {
      type: "EQUALS",
      parameter: [
        { type: "TEMPLATE", key: "arg0", value: "{{_event}}" },
        { type: "TEMPLATE", key: "arg1", value: "cta_click" }
      ]
    }
  ]
}

GTM API を使用して作成します。

tagmanager.accounts.containers.workspaces.triggers.create({
  parent: `accounts/${accountId}/containers/${containerId}/workspaces/${workspaceId}`,
  requestBody: triggerConfig
})

ステップ 3.3：GA4 イベントタグの作成

各イベントについて、そのトリガーで発火する GA4 イベントタグを作成します。

例：CTA クリックタグ

{
  name: "GA4 - CTA Click",
  type: "gaawe", // GA4 Event tag type
  parameter: [
    {
      type: "TEMPLATE",
      key: "eventName",
      value: "cta_click"
    },
    {
      type: "LIST",
      key: "eventParameters",
      list: [
        {
          type: "MAP",
          map: [
            { type: "TEMPLATE", key: "name", value: "cta_location" },
            { type: "TEMPLATE", key: "value", value: "{{DLV - CTA Location}}" }
          ]
        },
        {
          type: "MAP",
          map: [
            { type: "TEMPLATE", key: "name", value: "cta_type" },
            { type: "TEMPLATE", key: "value", value: "{{DLV - CTA Type}}" }
          ]
        },
        {
          type: "MAP",
          map: [
            { type: "TEMPLATE", key: "name", value: "cta_text" },
            { type: "TEMPLATE", key: "value", value: "{{DLV - CTA Text}}" }
          ]
        },
        {
          type: "MAP",
          map: [
            { type: "TEMPLATE", key: "name", value: "cta_destination" },
            { type: "TEMPLATE", key: "value", value: "{{DLV - CTA Destination}}" }
          ]
        }
      ]
    },
    {
      type: "TAG_REFERENCE",
      key: "measurementId",
      value: "{{GA4 Configuration Tag}}" // Reference to GA4 config tag
    }
  ],
  firingTriggerId: ["{{CE - CTA Click trigger ID}}"]
}

GTM API を使用して作成します。

tagmanager.accounts.containers.workspaces.tags.create({
  parent: `accounts/${accountId}/containers/${containerId}/workspaces/${workspaceId}`,
  requestBody: tagConfig
})

ステップ 3.4：段階的な更新の処理

作成する前に、既存の変数、トリガー、タグを確認します。

// List existing variables
const existingVariables = await tagmanager.accounts.containers.workspaces.variables.list({
  parent: `accounts/${accountId}/containers/${containerId}/workspaces/${workspaceId}`
})

// Check if "DLV - CTA Location" already exists
const exists = existingVariables.data.variable?.find(v => v.name === "DLV - CTA Location")

if (exists) {
  // Update existing variable
  tagmanager.accounts.containers.workspaces.variables.update({
    path: exists.path,
    requestBody: variableConfig
  })
} else {
  // Create new variable
  tagmanager.accounts.containers.workspaces.variables.create({...})
}

フェーズ 4：コンテナバージョンの作成

すべての変数、トリガー、タグを作成した後、新しいコンテナバージョンを作成します。

const version = await tagmanager.accounts.containers.workspaces.create_version({
  path: `accounts/${accountId}/containers/${containerId}/workspaces/${workspaceId}`,
  requestBody: {
    name: `GTM Automation - ${new Date().toISOString()}`,
    notes: `Automated implementation via gtm-implementation skill

Events implemented:
- cta_click (12 elements)
- form_submit (3 elements)
- navigation_click (8 elements)

Variables created: 12
Triggers created: 3
Tags created: 3`
  }
})

console.log(`✓ Container version created: ${version.data.containerVersionId}`)
console.log(`→ Preview in GTM: ${version.data.containerVersion.tagManagerUrl}`)

フェーズ 5：サマリーレポート

実装内容の包括的なサマリーを作成します。

=== GTM Implementation Complete ===

--- Code Changes ---
Files modified: 8

app/page.tsx:
  ✓ Added CTA click tracking (3 buttons)
  ✓ Added form submit tracking (1 form)

components/Navbar.tsx:
  ✓ Added navigation click tracking (5 links)

components/Footer.tsx:
  ✓ Added navigation click tracking (3 links)
  ✓ Added form submit tracking (1 newsletter form)

... (4 more files)

--- DataLayer Events Implemented ---
✓ cta_click (12 elements tracked)
✓ form_submit (3 elements tracked)
✓ navigation_click (8 elements tracked)

Total events: 23

--- GTM Container Configuration ---
Account: 1234567890
Container: GTM-ABC1234
Workspace: [dynamically resolved name] (ID: [resolved ID])

Created via API:
  ✓ 12 Data Layer Variables
  ✓ 3 Custom Event Triggers
  ✓ 3 GA4 Event Tags

Container version created: 42
Preview URL: https://tagmanager.google.com/#/versions/accounts/123/containers/456/versions/42

--- Next Steps ---
1. Test tracking in GTM Preview mode
   → Invoke gtm-testing skill for guided testing

2. Review container version in GTM:
   → Open GTM → Versions → Version 42
   → Check variables, triggers, tags

3. Publish when ready:
   → GTM → Submit → Publish

Ready to test tracking? Invoke gtm-testing skill.

重要なガイドライン

コード実装のベストプラクティス

1. 既存の機能を維持する

• 既存の onClick ハンドラーを絶対に削除しない
• トラッキング後に元のハンドラーを呼び出す
• 必要に応じてラッパー関数を使用する

2. 型安全性（TypeScript）

// Add proper typing
onClick={(e: React.MouseEvent<HTMLButtonElement>) => {
  // Track
  window.dataLayer?.push({...})
  // Original handler
  originalHandler(e)
}}

3. フレームワーク固有のパターン

Next.js App Router：

• onClick を含むファイルに 'use client' ディレクティブを追加する
• 'next/navigation' の useRouter を使用する

React：

• フックを使った関数コンポーネントを使用する
• 既存の状態管理を維持する

Vue：

• @click 構文を使用する
• リアクティビティを維持する

4. 冗長なトラッキングを避ける

• 要素にすでに dataLayer.push がある場合は、それを更新する（重複させない）
• 新しいトラッキングコードを追加する前に、既存のコードを確認する

GTM API のベストプラクティス

1. 命名規則

• 変数：「DLV - {Parameter Name}」（DLV = Data Layer Variable）
• トリガー：「CE - {Event Name}」（CE = Custom Event）
• タグ：「GA4 - {Event Name}」

2. エラー処理

try {
  await tagmanager.accounts.containers.workspaces.variables.create({...})
} catch (error) {
  if (error.code === 409) {
    // Variable already exists - update instead
  } else if (error.code === 403) {
    // Permission denied
  } else {
    throw error
  }
}

3. 一括操作

• まずすべての変数を作成する
• 次に、変数を参照する可能性のあるトリガーを作成する
• 最後に、変数とトリガーの両方を参照するタグを作成する

4. ワークスペースは常に動的に解決する ハードコードされた、またはキャッシュされた workspaceId は使用しないでください。操作の前に、次を呼び出します。

const workspaces = await tagmanager.accounts.containers.workspaces.list({
  parent: `accounts/${accountId}/containers/${containerId}`
})
const workspaceId = workspaces.data.workspace[0].workspaceId

GTM は公開のたびにワークスペースを削除して再作成するため、保存された ID は古くなります。

パラメーター抽出の工夫

パラメーターは、次のように適切に抽出してください。

ID 属性から：

// id="cta_hero_get_started"
const [category, location, ...action] = id.split('_')
// category: "cta", location: "hero", action: ["get", "started"]

クラス名から：

// className="btn btn-primary"
const isPrimary = className.includes('primary')
const type = isPrimary ? 'primary' : 'secondary'

コンテンツから：

// <button>Get Started</button>
const text = element.innerText // "Get Started"

href／遷移先から：

// <Link href="/pricing">
const destination = href // "/pricing"

// onClick={() => router.push('/signup')}
// Parse from handler → destination: "/signup"

スクリプト

scripts/gtm-api-client.js

変数／トリガー／タグを作成するための GTM API のコアラッパー（gtm-setup-auto.js のロジックから抽出）

scripts/create-variables.js

重複検出を備えた変数作成ロジック

scripts/create-triggers.js

カスタムイベントのトリガー作成ロジック

scripts/create-tags.js

パラメータマッピングを備えた GA4 イベントタグの作成

scripts/implement-datalayer.js

トラッキング計画を分析し、Edit ツールを使用してコード内に dataLayer.push() を実装

参考資料

references/datalayer-patterns.md

フレームワーク固有の dataLayer 実装パターン：

• Next.js App Router（'use client' ディレクティブ）
• Next.js Pages Router
• React（フック、クラスコンポーネント）
• Vue（Composition API、Options API）
• Vanilla JavaScript

references/gtm-ui-guide.md

API が失敗した場合に備えた、GTM UI の手動操作手順

references/event-taxonomies.md

一般的なイベント命名パターン（object_action と action_object）

アセット

assets/templates/saas.json

SaaS 製品のトラッキング用に事前構築された GTM 設定：

• trial_start、feature_usage、upgrade_click
• account_created、plan_selected

assets/templates/ecommerce.json

E コマースのトラッキング用に事前構築された GTM 設定：

• product_view、add_to_cart、checkout_start
• purchase_complete、product_search

関連ファイル

• template.md - フレームワーク固有の dataLayer push コードパターンと GTM API ペイロードのテンプレート
• examples/sample.md - コード変更前後の例とコンソール出力を示す、実装例の出力

assets/templates/lead-generation.json

リード獲得のトラッキング用に事前構築された GTM 設定：

• form_start、form_submit、content_download
• demo_request、newsletter_signup

実行チェックリスト

• トラッキング計画を読み込んだ、またはイベントを指定した
• GTM API の認証情報を検証した
• フレームワークを検出した
• 対象要素を特定した
• コードに DataLayer イベントを実装した
• GTM API で変数を作成した
• GTM API でトリガーを作成した
• GTM API でタグを作成した
• コンテナのバージョンを作成した
• 実装の概要を生成した
• テスト手順を提示した

よくある質問

Q：トラッキングプランがない場合はどうすればよいですか？ A：まず gtm-strategy スキルを実行してプランを作成するか、イベントを手動で指定してください。こちらで実装します。

Q：GTM API を使わずにトラッキングを実装できますか？ A：はい。コードに dataLayer イベントを実装し、GTM UI での手動設定手順をお伝えします。

Q：既存の GTM 設定は上書きされますか？ A：いいえ。既存の変数、トリガー、タグを確認して更新します。新しい設定は追加され、置き換えられることはありません。

Q：特定のイベントだけトラッキングを実装できますか？ A：はい。実装するイベントを指定してください（例：「cta_click のトラッキングだけを実装する」）。

Q：使用しているフレームワークがサポートされていない場合はどうなりますか？ A：dataLayer.push パターンは、あらゆる JavaScript 環境で動作します。Vanilla JS による実装を提供します。

Q：GTM で公開した後、ワークスペース ID が変わりました。スキルは動作しなくなりますか？ A：いいえ。スキルは常に API 経由で利用可能なワークスペースを一覧表示し、ID に関係なく最初に見つかったものを使用します。公開後に gtm-config.json を更新する必要はありません。