get_new_vs_returning
Analyze new versus returning user behavior in GA4 by comparing session counts and engagement duration to understand audience retention patterns.
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 specified metrics, processes the 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/types.ts:371-387 (schema)TypeScript interfaces defining the input (GetNewVsReturningInput extending PropertyId with period: ShortPeriod) and output (GetNewVsReturningOutput with newUsers and returningUsers of type UserTypeData) for the tool.// get_new_vs_returning 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; }
- src/server.ts:506-522 (registration)Tool registration in the tools array, including name 'get_new_vs_returning', description, and inputSchema matching the types.{ 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)Dispatch handler in the switch statement that calls the getNewVsReturning function 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/tools/analytics/index.ts:13-13 (helper)Re-export of the getNewVsReturning handler from its module for use in server.ts.export { getNewVsReturning } from "./getNewVsReturning.js";