Google Analytics

核心功能

Google Analytics Skill 是由 Maton 提供的官方 API 网关服务，为 GA4（Google Analytics 4）提供托管 OAuth 认证的双 API 访问能力：

1. Admin API（管理端）

• 账户管理：查询账户列表、获取账户摘要
• 资产管理：创建/查询属性（Property）、设置时区与货币
• 数据流配置：管理 Web/App 数据流、自定义维度
• 转化事件：配置转化追踪事件

2. Data API（数据端）

• 标准报告：支持日期范围、维度、指标的自由组合查询
• 实时报告：获取当前活跃用户数据
• 批量报告：单次请求多组数据对比
• 元数据查询：动态发现可用维度与指标

显著优点

| 优势 | 说明 |

|------|------|

| **零运维 OAuth** | 托管认证流程，无需自行处理 token 刷新与存储 |

| **双 API 分离** | Admin/Data 独立连接，权限粒度更细 |

| **原生 API 透传** | 直接映射 Google 官方 API，无功能裁剪 |

| **多语言示例** | 提供 Python、JavaScript、curl 完整代码 |

潜在局限

1. 仅支持 GA4：Universal Analytics 已废弃，无法兼容历史 UA 属性
2. 依赖第三方网关：所有流量经 Maton 中转，存在单点依赖
3. 速率限制：10 req/sec 的硬性限速，大规模数据抽取受限
4. 连接分离成本：Admin 与 Data API 需分别建立 OAuth 连接，配置复杂度较高

适合人群

• 需要程序化访问 GA4 数据的分析师与开发者
• 希望避免 OAuth 实现成本的中小团队
• 构建内部数据面板、自动化报告系统的工程师

常规风险

• 密钥泄露：MATON_API_KEY 需妥善保管，硬编码可导致未授权访问
• 权限扩散：OAuth 授权范围需最小化原则，避免过度授权 Google 账户
• 数据隐私：网站流量数据经第三方网关，需评估合规性要求
• 服务连续性：Maton 网关可用性直接影响业务系统稳定性

核心用法

本 Skill 提供 Google Analytics 双 API 集成能力，通过 Maton 托管网关实现托管式 OAuth 认证：

• Admin API：管理 GA4 账户、媒体资源（Properties）、数据流（Data Streams）、自定义维度及转化事件
• Data API：执行标准报表查询（runReport）、实时报表（runRealtimeReport）及批量报表（batchRunReports）

用户需先在 ctrl.maton.ai 创建两类独立连接（google-analytics-admin / google-analytics-data），完成 OAuth 授权后，通过 MATON_API_KEY 调用网关端点。

典型工作流

1. 调用 accountSummaries 获取可访问的账户与媒体资源列表
2. 使用 runReport 查询维度（如 country、pagePath）与指标（如 activeUsers、conversions）
3. 通过 Admin API 动态创建自定义维度或配置转化事件

---

显著优点

| 优势 | 说明 |

|------|------|

托管 OAuth | 无需自行处理 Google OAuth 2.0 流程，Maton 自动注入 Token |
双 API 覆盖 | 同时支持管理配置（Admin）与数据查询（Data），满足运营+分析需求 |
灵活查询 | 支持相对日期（30daysAgo）、多维度组合、排序及限流 |
实时数据 | 通过 runRealtimeReport 获取当前活跃用户等实时指标 |
多语言示例 | 提供 Python、JavaScript、Bash 完整代码片段 |

---

潜在缺点与局限性

• GA4 限定：不支持已弃用的 Universal Analytics（UA）
• 依赖第三方网关：所有请求需经过 Maton 服务（gateway.maton.ai），存在供应商锁定风险
• 双重连接管理：Admin API 与 Data API 需分别创建 OAuth 连接，增加配置复杂度
• 速率限制：10 req/sec 每账户（Google Analytics API 限制）
• 环境变量依赖：必须在运行环境安全配置 MATON_API_KEY，存在密钥泄露风险

---

适合人群

• 数据分析师/工程师：需将 GA4 数据自动化抽取至内部 BI 或数据仓库
• 增长运营团队：需批量配置跟踪属性、自定义维度或监控转化事件
• SaaS 产品经理：需在应用内嵌入网站流量分析或用户行为报表
• 具备基础 API 调用能力的开发者：熟悉 HTTP 请求与 JSON 数据处理

---

常规风险

| 风险类型 | 说明 | 缓解建议 |

|----------|------|----------|

密钥泄露 | MATON_API_KEY 若硬编码或提交至版本控制，可能导致未授权数据访问 | 使用环境变量或密钥管理服务，启用 Git 预提交扫描 |
OAuth 权限过度 | 授权时需确认 Maton 请求的 Google Analytics 权限范围，避免授予不必要权限 | 定期审查 Google 账户的第三方应用授权 |
数据传输合规 | 通过 Maton 网关传输分析数据，需确认其数据处理条款符合 GDPR/CCPA 要求 | 审查 Maton 隐私政策，必要时签署 DPA |
API 变更 | Google Analytics API 版本迭代可能导致端点或字段变动 | 关注 Google Analytics Dev 更新日志，预留迁移时间 |
单点故障 | Maton 网关服务中断将阻断所有数据访问 | 实现指数退避重试逻辑，监控网关可用性状态码 |

---

> 注意：本 Skill 为纯文档型（T-MD 分类），不含可执行代码，所有 API 调用均通过用户控制的环境变量发起，安全性取决于用户侧的密钥管理实践。