get_engagement_metrics
Retrieve engagement metrics like engagement rate and average engagement time from Google Analytics 4 to analyze user interaction patterns and behavior.
Instructions
エンゲージメント関連の詳細指標（エンゲージメント率、平均エンゲージメント時間など）を取得します。
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| propertyId | No | GA4プロパティID | |
| period | Yes | 集計期間 |
Implementation Reference
- The core async handler function that executes the tool logic: fetches GA4 report data for engagement metrics like engagementRate, userEngagementDuration, etc., computes derived metrics, and formats the output.
export async function getEngagementMetrics( input: GetEngagementMetricsInput ): Promise<GetEngagementMetricsOutput> { const propertyId = getPropertyId(input.propertyId); const property = formatPropertyPath(propertyId); const dateRange = periodToDateRange(input.period); const response = await executeReport({ property, dateRanges: [dateRange], metrics: [ { name: "engagementRate" }, { name: "userEngagementDuration" }, { name: "engagedSessions" }, { name: "totalUsers" }, { name: "eventCount" }, { name: "sessions" }, ], }); const metricValues = response.totals?.[0]?.metricValues || []; const getValue = (index: number): number => { const value = metricValues[index]?.value; return value ? parseFloat(value) : 0; }; const engagementRate = getValue(0); const userEngagementDuration = getValue(1); const engagedSessions = getValue(2); const totalUsers = getValue(3); const eventCount = getValue(4); const sessions = getValue(5); // エンゲージセッション/ユーザー const engagedSessionsPerUser = totalUsers > 0 ? roundToDecimal(engagedSessions / totalUsers) : 0; // イベント/セッション const eventsPerSession = sessions > 0 ? roundToDecimal(eventCount / sessions) : 0; // 平均エンゲージメント時間 const avgEngagementTime = totalUsers > 0 ? formatDuration(userEngagementDuration / totalUsers) : "0秒"; return { engagementRate: formatPercentageFromDecimal(engagementRate), avgEngagementTime, engagedSessionsPerUser, eventsPerSession, // スクロール深度は別途イベントベースの設定が必要なため省略 }; } - src/types.ts:389-407 (schema)TypeScript interfaces defining the input (GetEngagementMetricsInput extending PropertyId with period) and output (GetEngagementMetricsOutput) schemas for the tool, including related ScrollDepth type.
// get_engagement_metrics export interface GetEngagementMetricsInput extends PropertyId { period: ShortPeriod; } export interface ScrollDepth { reached25: string; reached50: string; reached75: string; reached100: string; } export interface GetEngagementMetricsOutput { engagementRate: string; avgEngagementTime: string; engagedSessionsPerUser: number; eventsPerSession: number; scrollDepth?: ScrollDepth; } - src/server.ts:523-539 (registration)MCP tool registration entry in the tools array, defining name, description, and inputSchema for 'get_engagement_metrics'.
{ name: "get_engagement_metrics", description: "エンゲージメント関連の詳細指標（エンゲージメント率、平均エンゲージメント時間など）を取得します。", inputSchema: { type: "object" as const, properties: { propertyId: { type: "string", description: "GA4プロパティID" }, period: { type: "string", enum: ["7days", "28days", "30days"], description: "集計期間", }, }, required: ["period"], }, }, - src/server.ts:738-742 (registration)Dispatch case in the handleToolCall switch statement that invokes the getEngagementMetrics handler with parsed arguments.
case "get_engagement_metrics": return await getEngagementMetrics({ propertyId: args.propertyId as string | undefined, period: args.period as "7days" | "28days" | "30days", }); - src/tools/analytics/index.ts:14-14 (helper)Re-export of the getEngagementMetrics handler from its implementation file, allowing import from the analytics index.
export { getEngagementMetrics } from "./getEngagementMetrics.js";