ga-auth

GA4 身份验证与连接技能（ga-auth）

让营销人员无需使用 gcloud，通过“登录 → 允许 → 选择媒体资源”连接到 GA4。 营销人员会收到组织管理员创建的桌面 OAuth 客户端（.ga4/oauth_client.json），并使用它登录。 确定性工作由 scripts/ 中的 Python 脚本完成；由你判断应执行哪个步骤。

语言

使用用户的语言回复。如果用户用韩语书写，就用韩语回答； 如果用英语书写，就用英语回答。此规则适用于每个步骤——设置指导、 进度更新、结果和错误说明。

切勿翻译：GA4 API 标识符（eventCount、sessionSource、runReport）、 文件和目录名称（.ga4/token.json）、Shell 命令及 JSON 字段名称。

绝不直接向用户展示脚本输出。 脚本始终会输出英文的 error／hint 字符串。当脚本返回 "ok": false 时，你必须先将 hint 改写成用户的语言，再展示给用户。绝不能直接照搬英文， 也不能展示原始 JSON。在改写后的文本中，标识符、路径和命令必须原样保留——只翻译周围的说明文字。

示例——脚本返回： {"ok": false, "hint": "token.json is missing. Log in first with the ga-auth skill."} 对韩语用户，应说： 로그인 정보(.ga4/token.json)가 없어요. ga-auth 스킬로 먼저 로그인할게요. 不要说：“token.json is missing. Log in first with the ga-auth skill.”

工作原则（重要）

目标用户是非技术背景的营销人员。大多数人从未接触过 GCP 或 OAuth 概念，因此请遵守以下规则：

• 将工作拆分成小步骤。 不要一次性贴出冗长的指南——每次引导一到两个步骤，确认完成后再继续。
• 每个步骤都用一句话说明“做什么／为什么”。 明确说出要点击的按钮名称。
• 提前指出最常见的 3 个陷阱： ① 忘记登记测试用户；② 出现“未验证的应用”警告（这是正常现象）；③ 切换账号时，新账号也必须是已登记的测试用户。
• 尽可能替用户完成繁重的工作。 尽可能自行处理文件放置和命令执行——用户只需在控制台中点击并通过浏览器登录。

解释器规则

• ga4_status.py、ga4_auth.py：可使用系统的 python3 运行（仅依赖标准库）
• ga4_login.py、ga4_admin.py：必须使用 .ga4/venv/bin/python 运行（需要 GA4 和 oauthlib 库）
• {SKILLS_DIR} = 安装这些 ga 技能的目录——即此技能目录的父目录 （在 Claude Code 项目中为 .claude/skills；其他 Agent 使用各自的位置）。 请替换为实际路径。请从项目根目录运行命令。

步骤 1：状态检查（始终先执行）

python3 {SKILLS_DIR}/ga-auth/scripts/ga4_status.py

首先检查 ga4_dir_present。 如果它是 false，下面的每个标志也都是 false，这并不意味着设置出了问题——.ga4 是相对于当前工作目录解析的，因此从错误的文件夹运行命令时也会出现这种情况。输出中包含一个 hint，其中注明了搜索的确切路径。请确认你位于营销人员的项目目录中（或设置 GA4_DIR），并在进入步骤 2 之前重新运行——让已连接的用户重新进行 OAuth 设置，会让他们在错误的问题上耗费大量时间，经历漫长而痛苦的弯路。

当 ga4_dir_present 为 true 后，根据输出 JSON 判断进入哪个步骤：

oauth_client_present	token_present	property_configured	→ 步骤
false	-	-	获取 OAuth 客户端（2）
true	false	-	登录（3）
true	true	false	选择属性（4）
true	true	true	已连接（5）

token_present 是一项轻量检查（token.json 存在且包含 refresh_token）。实际有效性会在首次 API 调用时确认。

依赖项检查：同时查看同一输出中的 venv_present/deps_ready。如果 venv_present 为 false，请创建 venv，并按照 references/setup-guide.md 第 1 节安装三个 requirements 文件。如果 deps_ready 为 false，请自行运行 deps_fix pip 命令（用一句话说明：“我将安装所需的库”），然后重新检查——不要让营销人员运行 pip。如果 deps_ready 为 null，说明检查本身失败；不要假设缺少依赖项，直接继续。

步骤 2：获取 OAuth 客户端（如果缺少）

首先简要说明整体流程——两个角色，营销人员需要完成 3 个步骤：

[Administrator] Create the OAuth client once in GCP -> hand over oauth_client.json
      └─▶ [Marketer] 1. place the file -> 2. log in and allow in the browser -> 3. select a property

然后检查用户目前的进度：

• 如果 oauth_client.json 已存在（来自之前的操作或管理员），只需获取文件路径，让此技能将其复制到 .ga4/oauth_client.json，然后进入步骤 3。即使走这条路径，也要验证顶层键是否为 installed——如果是 web，它就不是桌面应用，登录会失败（ga4_login.py 会在调用前拦截，并说明需要什么）。
• 如果需要创建，请按照 references/admin-setup-guide.md 逐步操作。顺序：GCP 项目 → 启用 2 个 API → 同意屏幕 → 创建桌面 OAuth 客户端 → 下载 JSON。
  • 同意屏幕的设置路径取决于账号类型。首先询问“这是公司 Workspace 账号还是个人 @gmail？”并据此分流：Workspace 选择 Internal（最简单）；个人 Gmail 选择 External + 添加自己的邮箱作为测试用户（⚠️ 跳过此注册会导致无法登录）。
• 下载完成后，获取文件路径并让此技能放置文件：

  mkdir -p .ga4 && cp "<download-path>" .ga4/oauth_client.json
  

  放置后，验证文件结构（顶层键为 installed，redirect_uris 中包含 http://localhost，即表示这是有效的桌面应用）。
• 如果没有 venv，请按照 references/setup-guide.md 第 1 节创建 venv 并安装依赖项。

步骤 3：登录（营销人员，无需 gcloud）

运行前，说明浏览器中会发生什么：

1. 浏览器标签页会自动打开 → 选择拥有 GA4 访问权限的账号
2. （对于个人 gmail／未经验证的应用）“未验证的应用”警告属于正常情况 → 高级 → 继续／前往……
3. 出现“查看您的 Google Analytics 数据”权限提示 → 允许
4. 出现“身份验证流程已完成……”时，表示登录成功 → 关闭窗口

然后运行命令（该命令会一直等待，直到浏览器流程完成，因此请设置较长的超时时间）：

.ga4/venv/bin/python {SKILLS_DIR}/ga-auth/scripts/ga4_login.py

ok:true 表示已创建 .ga4/token.json。ok:false 表示你应当用用户的语言说明错误提示中的解决方法（内部设置、测试用户、绕过警告），然后重试。

**远程／SSH·无头环境注意事项：**环回登录要求浏览器和脚本在同一台机器上运行。如果是在远程环境，请让用户在自己的电脑上登录，然后将生成的 token.json 复制到服务器（references/setup-guide.md）。

步骤 4：选择属性

1. 获取属性列表：

   .ga4/venv/bin/python {SKILLS_DIR}/ga-auth/scripts/ga4_admin.py list-properties
   

2. 按账号分组展示，以便查看，并让用户选择要使用的属性。如果属性很多，请按账号汇总数量，并让用户选择一个有代表性的属性。

3. 如果列表为空（[]）——身份验证已成功，但此账号没有可访问的 GA4 属性。最常见的原因是使用了错误的账号登录。请确认该账号具有 GA4 访问权限，必要时使用正确的账号重新登录（见下方的重新登录说明）。

4. 查询属性的货币、时区和数据流——上面的列表不包含这些信息：

   .ga4/venv/bin/python {SKILLS_DIR}/ga-auth/scripts/ga4_admin.py get-property <PROPERTY_ID>
   

   同一次调用还会返回 data_streams 和 platforms，说明此属性从哪些平台收集数据：网站、iOS 应用、Android 应用，或其中多个平台。用一句话告诉营销人员查询结果（“此属性包含一个网站和一个 iOS 应用”），因为这是他们首先可以确认或更正的信息，也因为之后的每个技能都会据此进行判断。

   如果 platforms 为 []，则此属性完全没有数据流，也没有收集任何数据——请明确说明，不要继续。如果这些键不存在，则表示查询失败；这不影响后续操作，请在不使用这些信息的情况下继续。

5. 保存所选属性，并传入步骤 4 返回的每个值：

   python3 {SKILLS_DIR}/ga-auth/scripts/ga4_auth.py save-property <PROPERTY_ID> \
     --name "<NAME>" --account "<ACCOUNT>" --currency "<CURRENCY_CODE>" --time-zone "<TIME_ZONE>" \
     --retention-months "<EVENT_DATA_RETENTION_MONTHS>" --platforms "<PLATFORMS>"
   

   不要跳过查询。 这两个值都无法推断，而且都会改变答案的含义：某个在开发期间测量的属性使用 Asia/Seoul 时区，同时以 USD 报告收入；若将其收入当作韩元读取，结果会相差约 1300 倍。报告响应也会附带这些值，但仅限于 runReport 系列——实时响应完全没有元数据，因此没有这些信息就无法得知货币。如果步骤 4 失败，仍然保存其余信息；这些字段会存储为 null，表示“未知”，而不是“没有货币”。 如果步骤 4 未返回某个标志对应的值，就不要传入该标志。 get-property 会省略无法读取的键，传入空字符串并不等同于省略——脚本会对其进行规范化，但省略该标志才能正确表示“未知”。 --retention-months 仅对漏斗分析有影响，而且影响很大：超过属性的数据保留期限后，runFunnelReport 会不报错但返回零行，而对相同时段运行 runReport 则会正常返回结果。没有此值，ga-use 就无法区分漏斗结果为空是因为超出保留期限，还是因为“无人转化”——它会明确说明这一点，而不会保持沉默，这样营销人员就能知道检查并未运行，而不是听到一个看似确定的零值。 --platforms 接受步骤 4 返回的 platforms 数组，以逗号分隔的列表形式传入，并使用 GA4 自己的拼写方式：web、iOS、Android。不要将它们改成小写：这些是 GA4 的 platform 维度返回的值，因此由 ios 构建的筛选条件不会匹配任何内容，而且不会报错。（脚本现在会作为兜底修正大小写，但仍要使用正确的拼写——兜底逻辑只认识 GA4 目前使用的四种值。）如果步骤 4 表明此属性没有数据流，请传入 none；如果查询失败，则省略此标志，这样存储的会是“未知”，而不是猜测。如果数组包含 unknown，请原样传入，并与其他值一同保留——这表示某个数据流无法分类，若将其省略，后续就会把“无法判断”误变成确定的平台答案。 此命令会从头重写 config.json，因此请将步骤 4 和 5 视为一组：省略的任何标志都会存储为 null，即使上次保存时该标志有值也不例外。单独重新运行步骤 5 来刷新平台列表，会连同货币、时区和保留期限一起清除。

重新登录以切换账号

如需使用其他账号重新登录，请再次运行 ga4_login.py（它使用 prompt=consent，因此账号选择器会正常显示）。 不过，如果使用个人 Gmail（外部测试模式），新账号也必须已在 OAuth 同意屏幕中注册为测试用户。否则登录会失败，并显示“Access blocked: app is in testing mode”；请先让用户完成注册，然后再次登录。

第 5 步：已连接

告知用户连接已完成，并引导他们使用 ga-use 技能进行分析，使用 ga-taxonomy 技能查看事件分类体系。 如果用户明确要求重新配置（重新登录／更改属性），无论上表如何，都应重新执行该步骤。

文件位置

• 运行时状态：项目本地的 .ga4/（oauth_client.json、token.json、config.json、venv/）
• oauth_client.json：管理员创建的桌面 OAuth 客户端（references/admin-setup-guide.md）。
• token.json：登录生成的凭据（会自动刷新）。
• GA4_DIR 环境变量可以更改 .ga4 的位置（默认值：<cwd>/.ga4）。