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 handler function that executes the get_engagement_metrics tool. It fetches raw metrics from GA4 via executeReport, processes them (e.g., calculates per-user/session ratios, formats durations and percentages), and returns structured 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 schema (extends PropertyId with period: ShortPeriod) and output structure for the get_engagement_metrics tool.// 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: defines the tool name, description, and inputSchema (propertyId optional, period required with enum) in the tools array for ListToolsRequest.{ 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 handler in the switch statement within handleToolCall: maps tool call to the getEngagementMetrics function with parsed arguments.case "get_engagement_metrics": return await getEngagementMetrics({ propertyId: args.propertyId as string | undefined, period: args.period as "7days" | "28days" | "30days", });
- src/server.ts:33-35 (registration)Import statement bringing getEngagementMetrics into the server module from the analytics tools index.getEngagementMetrics, getSearchTerms, } from "./tools/analytics/index.js";