get_device_breakdown
Retrieve device breakdown data from Google Analytics 4, showing access distribution across PCs, mobiles, and tablets with OS and browser details.
Instructions
デバイス別（PC/モバイル/タブレット）のアクセス内訳を取得します。OS別、ブラウザ別の情報も含まれます。
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| propertyId | No | GA4プロパティID | |
| period | Yes | 集計期間 |
Implementation Reference
- The primary handler function that executes GA4 reports to retrieve and process device category, OS, and browser breakdown data, including calculations for percentages, bounce rates, and session durations.export async function getDeviceBreakdown( input: GetDeviceBreakdownInput ): Promise<GetDeviceBreakdownOutput> { const propertyId = getPropertyId(input.propertyId); const property = formatPropertyPath(propertyId); const dateRange = periodToDateRange(input.period); // デバイスカテゴリ別のデータ取得 const deviceResponse = await executeReport({ property, dateRanges: [dateRange], dimensions: [{ name: "deviceCategory" }], metrics: [ { name: "totalUsers" }, { name: "sessions" }, { name: "bounceRate" }, { name: "averageSessionDuration" }, ], orderBys: [{ metric: { metricName: "totalUsers" }, desc: true }], }); // 合計ユーザー数を取得 const totalUsers = deviceResponse.totals?.[0]?.metricValues?.[0]?.value ? parseFloat(deviceResponse.totals[0].metricValues[0].value) : 0; const devices: DeviceData[] = []; for (const row of deviceResponse.rows || []) { const dimensionValues = row.dimensionValues || []; const metricValues = row.metricValues || []; const getValue = (index: number): number => { const value = metricValues[index]?.value; return value ? parseFloat(value) : 0; }; const users = Math.round(getValue(0)); const deviceCategory = dimensionValues[0]?.value || "unknown"; devices.push({ deviceCategory: deviceCategory as "desktop" | "mobile" | "tablet", users, sessions: Math.round(getValue(1)), percentage: calculatePercentage(users, totalUsers), bounceRate: formatPercentageFromDecimal(getValue(2)), avgSessionDuration: formatDuration(getValue(3)), }); } // OS別のデータ取得 const osResponse = await executeReport({ property, dateRanges: [dateRange], dimensions: [{ name: "operatingSystem" }], metrics: [{ name: "totalUsers" }], orderBys: [{ metric: { metricName: "totalUsers" }, desc: true }], limit: 10, }); const operatingSystems: OSData[] = []; for (const row of osResponse.rows || []) { const dimensionValues = row.dimensionValues || []; const metricValues = row.metricValues || []; const users = metricValues[0]?.value ? Math.round(parseFloat(metricValues[0].value)) : 0; operatingSystems.push({ name: dimensionValues[0]?.value || "(不明)", users, percentage: calculatePercentage(users, totalUsers), }); } // ブラウザ別のデータ取得 const browserResponse = await executeReport({ property, dateRanges: [dateRange], dimensions: [{ name: "browser" }], metrics: [{ name: "totalUsers" }], orderBys: [{ metric: { metricName: "totalUsers" }, desc: true }], limit: 10, }); const browsers: BrowserData[] = []; for (const row of browserResponse.rows || []) { const dimensionValues = row.dimensionValues || []; const metricValues = row.metricValues || []; const users = metricValues[0]?.value ? Math.round(parseFloat(metricValues[0].value)) : 0; browsers.push({ name: dimensionValues[0]?.value || "(不明)", users, percentage: calculatePercentage(users, totalUsers), }); } return { devices, operatingSystems, browsers, }; }
- src/types.ts:173-202 (schema)TypeScript type definitions for input and output schemas of the get_device_breakdown tool, including detailed structures for device, OS, and browser data.export interface GetDeviceBreakdownInput extends PropertyId { period: ShortPeriod; } export interface DeviceData { deviceCategory: "desktop" | "mobile" | "tablet"; users: number; sessions: number; percentage: string; bounceRate: string; avgSessionDuration: string; } export interface OSData { name: string; users: number; percentage: string; } export interface BrowserData { name: string; users: number; percentage: string; } export interface GetDeviceBreakdownOutput { devices: DeviceData[]; operatingSystems?: OSData[]; browsers?: BrowserData[]; }
- src/server.ts:270-285 (registration)Tool registration entry in the MCP server's tools array, defining name, description, and input schema for get_device_breakdown.name: "get_device_breakdown", description: "デバイス別（PC/モバイル/タブレット）のアクセス内訳を取得します。OS別、ブラウザ別の情報も含まれます。", 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:657-661 (registration)Dispatch logic in the handleToolCall switch statement that invokes the getDeviceBreakdown handler.case "get_device_breakdown": return await getDeviceBreakdown({ propertyId: args.propertyId as string | undefined, period: args.period as "7days" | "28days" | "30days", });
- src/tools/analytics/index.ts:4-4 (helper)Re-export of the getDeviceBreakdown function for convenient import in server.ts.export { getDeviceBreakdown } from "./getDeviceBreakdown.js";