ga4-analytics

GA4 アナリティクスツールキット

セットアップ

依存関係をインストールします。

cd scripts && npm install

プロジェクトのルートに .env ファイルを作成して、認証情報を設定します。

GA4_PROPERTY_ID=123456789
[email protected]
GA4_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
SEARCH_CONSOLE_SITE_URL=https://your-domain.com
GA4_DEFAULT_DATE_RANGE=30d

前提条件：Analytics Data API、Search Console API、Indexing API が有効になっている Google Cloud プロジェクトが必要です。また、GA4 プロパティと Search Console にアクセスできるサービスアカウントが必要です。

クイックスタート

ユーザーの発言	呼び出す関数
「過去 30 日間のサイトトラフィックを表示して」	siteOverview("30d")
「検索クエリの上位は？」	searchConsoleOverview("30d")
「今、サイトにいるのは誰？」	liveSnapshot()
「これらの URL を再インデックスして」	reindexUrls(["https://example.com/page1", ...])
「今月と先月を比較して」	compareDateRanges({startDate: "30daysAgo", endDate: "today"}, {startDate: "60daysAgo", endDate: "31daysAgo"})
「最も多くのトラフィックを獲得しているページは？」	contentPerformance("30d")

scripts/src/index.ts からインポートして関数を実行します。

import { siteOverview, searchConsoleOverview } from './scripts/src/index.js';

const overview = await siteOverview('30d');

または、tsx で直接実行します。

npx tsx scripts/src/index.ts

ワークフローパターン

すべての分析は、次の 3 つのフェーズで行います。

1. 分析

API 関数を実行します。各呼び出しで Google API にアクセスし、構造化データを返します。

2. 自動保存

すべての結果は、タイムスタンプ付きの JSON ファイルとして results/{category}/ に自動保存されます。ファイル名のパターン：YYYYMMDD_HHMMSS__operation__extra_info.json

3. 要約

分析後、保存された JSON ファイルを読み込み、データテーブル、傾向、推奨事項を含む Markdown の要約を results/summaries/ に作成します。

高水準関数

GA4 アナリティクス

関数	目的	取得するデータ
siteOverview(dateRange?)	サイトの包括的なスナップショット	ページビュー、トラフィックソース、ユーザー属性、イベント
trafficAnalysis(dateRange?)	トラフィックの詳細分析	ソース、ソース／メディア別セッション、新規ユーザーとリピーター
contentPerformance(dateRange?)	上位ページの分析	ページビュー、ランディングページ、離脱ページ
userBehavior(dateRange?)	エンゲージメントパターン	ユーザー属性、イベント、日別エンゲージメント指標
compareDateRanges(range1, range2)	期間の比較	2 つの日付範囲の指標を並べて比較
liveSnapshot()	リアルタイムデータ	アクティブユーザー、現在のページ、現在のイベント

Search Console

関数	目的	取得するデータ
searchConsoleOverview(dateRange?)	SEO のスナップショット	上位クエリ、ページ、デバイス別・国別の内訳
keywordAnalysis(dateRange?)	キーワードの詳細分析	デバイス別の内訳を含むクエリ
seoPagePerformance(dateRange?)	ページの SEO 指標	クリック数上位のページ、国別の内訳

インデックス登録

関数	目的
reindexUrls(urls)	複数の URL の再インデックスをリクエスト
checkIndexStatus(urls)	URL がインデックス登録されているか確認

ユーティリティ

関数	目的
getAvailableFields()	利用可能な GA4 のディメンションと指標をすべて一覧表示

個別の API 関数

詳細に制御するには、API モジュールから特定の関数をインポートします。パラメーター、型、使用例を含む 30 以上の API 関数の完全な一覧は、references/api-reference.md を参照してください。

日付範囲

すべての関数は、柔軟な日付範囲形式を受け付けます。

形式	例	説明
省略形	"7d", "30d", "90d"	今日からさかのぼった日数
明示形式	{startDate: "2024-01-01", endDate: "2024-01-31"}	指定した日付
GA4 相対形式	{startDate: "30daysAgo", endDate: "today"}	GA4 の相対形式

デフォルトは "30d" です（.env の GA4_DEFAULT_DATE_RANGE で設定できます）。

結果の保存

結果は次の構成で results/ に自動保存されます。

results/
├── reports/          # GA4 standard reports
├── realtime/         # Real-time snapshots
├── searchconsole/    # Search Console data
├── indexing/         # Indexing API results
└── summaries/        # Human-readable markdown summaries

結果の管理

import { listResults, loadResult, getLatestResult } from './scripts/src/index.js';

// List recent results
const files = listResults('reports', 10);

// Load a specific result
const data = loadResult(files[0]);

// Get most recent result for an operation
const latest = getLatestResult('reports', 'site_overview');

よく使われるディメンションと指標

ディメンション

pagePath、pageTitle、sessionSource、sessionMedium、country、deviceCategory、browser、date、eventName、landingPage、newVsReturning

指標

screenPageViews、activeUsers、sessions、newUsers、bounceRate、averageSessionDuration、engagementRate、conversions、totalRevenue、eventCount

ヒント

1. 日付範囲を指定する — 「過去 7 日間」と「過去 90 日間」では、デフォルトの 30 日間とは異なるインサイトが得られます
2. 要約を依頼する — データを取得した後、表とインサイトを含む Markdown の要約を依頼します
3. 期間を比較する — compareDateRanges() を使って傾向を把握します（今月と先月）
4. リアルタイムデータを確認する — liveSnapshot() で現在サイトを訪問しているユーザーを確認できます
5. GA4 と Search Console を組み合わせる — トラフィックデータと検索クエリデータを組み合わせることで、全体像を把握できます