get_new_vs_returning
Compare new and returning user sessions and engagement time in Google Analytics 4 to analyze audience behavior patterns and retention.
Instructions
新規ユーザーとリピーターの比較分析を行います。それぞれのセッション数や滞在時間を確認できます。
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| propertyId | No | GA4プロパティID | |
| period | Yes | 集計期間 |
Implementation Reference
- The core handler function that fetches GA4 report data for new vs returning users using dimensions 'newVsReturning' and specific metrics, processes rows to compute counts, percentages, sessions, avg duration, and bounce rates for new and returning users.
export async function getNewVsReturning( input: GetNewVsReturningInput ): Promise<GetNewVsReturningOutput> { const propertyId = getPropertyId(input.propertyId); const property = formatPropertyPath(propertyId); const dateRange = periodToDateRange(input.period); const response = await executeReport({ property, dateRanges: [dateRange], dimensions: [{ name: "newVsReturning" }], metrics: [ { name: "totalUsers" }, { name: "sessions" }, { name: "averageSessionDuration" }, { name: "bounceRate" }, ], }); // 合計ユーザー数を取得 const totalUsers = response.totals?.[0]?.metricValues?.[0]?.value ? parseFloat(response.totals[0].metricValues[0].value) : 0; // デフォルト値 const defaultUserData: UserTypeData = { count: 0, percentage: "0%", sessions: 0, avgSessionDuration: "0秒", bounceRate: "0%", }; let newUsers: UserTypeData = { ...defaultUserData }; let returningUsers: UserTypeData = { ...defaultUserData }; for (const row of response.rows || []) { const userType = row.dimensionValues?.[0]?.value || ""; const metricValues = row.metricValues || []; const getValue = (index: number): number => { const value = metricValues[index]?.value; return value ? parseFloat(value) : 0; }; const count = Math.round(getValue(0)); const userData: UserTypeData = { count, percentage: calculatePercentage(count, totalUsers), sessions: Math.round(getValue(1)), avgSessionDuration: formatDuration(getValue(2)), bounceRate: formatPercentageFromDecimal(getValue(3)), }; if (userType === "new") { newUsers = userData; } else if (userType === "returning") { returningUsers = userData; } } return { newUsers, returningUsers, }; } - src/server.ts:506-521 (registration)Tool registration in the MCP server, defining the tool name, description, and input schema (propertyId optional, period required).
{ name: "get_new_vs_returning", 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:732-736 (registration)The switch case in handleToolCall that invokes the getNewVsReturning handler with parsed arguments.
case "get_new_vs_returning": return await getNewVsReturning({ propertyId: args.propertyId as string | undefined, period: args.period as "7days" | "28days" | "30days", }); - src/types.ts:372-387 (schema)TypeScript interfaces defining the input (extends PropertyId with period), UserTypeData structure, and output (newUsers and returningUsers).
export interface GetNewVsReturningInput extends PropertyId { period: ShortPeriod; } export interface UserTypeData { count: number; percentage: string; sessions: number; avgSessionDuration: string; bounceRate: string; } export interface GetNewVsReturningOutput { newUsers: UserTypeData; returningUsers: UserTypeData; }