使用文档 — Ads Automator

1. 首次配置

1.1 Google Ads API 凭证

所有功能依赖 Google Ads API，需要先配置以下 5 项凭证：

Developer Token — Google Ads 后台 → 工具 → 设置 → API Center → 申请
OAuth2 Client ID / Secret — Google Cloud Console → APIs & Services → Credentials
Refresh Token — 运行 OAuth 授权流程获取（设置页有脚本参考）
Customer ID — Google Ads 后台 → 账户设置 → 客户号（如 123-456-7890）

1.2 保存配置

左侧导航 → API 设置 → 填完上面的凭证 → 点「保存配置」

支持多账号：先保存一份配置，输入名称点「保存账号」→ 切到新账号再填另一份 → 再保存。

1.3 AI 文案生成（可选）

在 API 设置 页面底部填入 DeepSeek API Key，创建广告时可自动生成标题和描述。

2. 仪表盘

系统入口页面，展示：

今日数据 — 展示次数、点击、花费、CPC、CTR
Campaign 状态 — 子账号数、广告系列数、已启用/暂停数量、广告组、关键词
系统状态 — SDK 连接状态、活跃 Profile、上次拉取时间
快速操作 — 一键跳转创建广告、列表、数据、设置
最近日志 — 系统操作记录

手动刷新页面获取最新数据。

3. 创建广告

3.1 手动模式

① 点击开关切换到「手动模式」
② 点「拉取列表」获取子账号列表，选一个
③ 填写：名称 / 日预算 / CPC 上限 / 地理位置 / 语言
④ 填关键词（每行一个，支持广泛/词组/完全匹配）
⑤ 填标题（每行一个，最多12条，每条≤30字）
⑥ 填描述（每行一个，最多4条，每条≤90字）
⑦ 填写最终到达网址
⑧ 可选跟踪模板 → 点「创建广告系列（暂停）」

关键词匹配：无符号=广泛匹配，"关键词"=词组匹配，[关键词]=完全匹配

3.2 AI 自动模式

① 保持「AI 生成模式」开启
② 选子账号 → 填关键词 → 填最终到达网址
③ 可选：调整预算、CPC、地区、语言
④ 点「创建广告系列（暂停）」 → 系统自动调用 DeepSeek 生成12条标题+4条描述

自动模式会自动生成广告系列名称（品牌+日期）、否定关键词、文案。

3.3 创建流程说明

创建完成后，广告系列状态为 PAUSED（暂停），需要去 Google Ads 后台手动启用并充值预算。

4. 广告系列列表

三层折叠树展示：MCC → 子账号 → 广告系列

4.1 导入已有广告系列

点「导入已有广告系列」从 Google Ads API 拉取已创建的 Campaign 到本地管理。

4.2 编辑广告系列

每个 Campaign 右侧有按钮 → 可编辑：

预算 / CPC / 跟踪模板 / 最终到达网址
标题、描述、关键词（增删）

4.3 跟踪模板

点按钮 → 设置跟踪模板（支持 ValueTrack 参数）→ 保存到 Google Ads

跟踪模板示例：{lpurl}?ref=xxx&affiliateid=xxx

4.4 暂停/开启

点击 Campaign 右侧的「暂停」/「开启」按钮，在本地数据库切换状态（不影响 Google Ads）。

4.5 其他操作

删除子账号 — 子账号行右侧 🗑 图标，删除该账号下所有本地记录
隐藏暂停 — 开关过滤掉状态为 PAUSED 的 Campaign
折叠/展开 — 点「全部折叠」收起整个树
编辑 MCC 名称 — 点顶部 MCC 名称或旁边 ✏ 图标

5. 数据监控

5.1 拉取最新数据

先选天数（1~7天），点「拉取最新数据」从 Google Ads API 获取实时数据。有数据的日期会在日历上绿色高亮。

如果当天数据不完整（同一天还没结束），Google Ads API 可能返回空。选7天或30天即可。

5.2 按日期查看

点「日期按钮」弹出日历 → 点击有高亮的日期 → 自动加载该日数据。

5.3 补充历史数据

点「补数据」按钮 → 选起止日期 → 系统逐天拉取 Google Ads API 并将结果存入数据库 → 日历自动高亮。

适合用来补充整月数据，比如选 2026-05-01 ~ 2026-05-21 拉完整个5月。

5.4 查看数据

数据以三层折叠树展示：MCC → 子账号 → Campaign 明细表格（展示/点击/花费/CTR/CPC/转化）。

隐藏暂停 — 开关过滤 PAUSED 的 Campaign
AI 分析 — 点 Campaign 行右侧按钮，用 DeepSeek 分析并给出优化建议

6. API 设置

6.1 凭证管理

填写 Google Ads API 的 5 项凭证（Developer Token / Client ID / Secret / Refresh Token / Customer ID）。

6.2 多账号管理

① 先填好一套凭证
② 在「多账号管理」下输入名称如「邮箱A」→ 点「保存账号」
③ 切换表单中的凭证为第二套 → 输入名称如「邮箱B」→ 点「保存账号」
④ 点击账号列表中的 ✓ 按钮切换活跃账号

6.3 AI Key

页面底部可配置 DeepSeek API Key，用于 AI 文案生成和 AI 数据分析。

6.4 主题与强调色

左侧底部有颜色选择器：

强调色 — 7 种颜色（蓝/紫/绿/青/橙/金/红）
背景 — 4 种主题（暗黑/午夜/墨绿/亮白）

7. 操作日志

记录所有系统操作，包括：

Campaign 创建 / 编辑 / 暂停
数据拉取 / 补数据
API 配置更新
Profile 切换
系统启动 / 关闭
AI 文案生成 / 分析
返利监控检测 / 链接替换
广告自动检查（AdCheck）

8. 返利监控

8.1 功能概述

自动监控 GMX 邮箱中的返利邮件，统计 ShopBack 等联盟平台的返利通知，到达预设数量后自动替换 Google Ads 跟踪链接。
无需手动操作，全自动运行。

8.2 邮箱配置

① 进入 返利监控 页面
② 每个广告系列有 5 个槽位（Slot #1~#5），每个槽位配置一个 GMX 邮箱
③ 填写：邮箱 / 密码 / 跟踪链接（联盟链接的 tracking param） / 触发数（默认2）
④ 点「保存」按钮

触发数指收到几封返利邮件后自动替换跟踪链接，通常设为 2。

8.3 跟踪链接格式

只需填写 tracking parameters 部分（如 ?refid=xxx&drag_vars=xxx），系统自动补上 {lpurl} 前缀。

示例：?refid=23418&drag_vars=1877865582_16417

8.4 池子分配模式（Pool）

系统使用 池子分配机制：只从未使用过的槽位（url_replaced=0）中挑选下一个，用过的不会重复循环。
5 个槽位全部用完后，系统停止并等待补充新邮箱。

8.5 启动/暂停监控

每个广告系列右侧有「启动」/「暂停」按钮。启动后后台线程每 5 分钟自动扫一次邮箱，遇到新返利邮件自动 +1 计数，达标自动替换链接。

8.6 手动 +1

如果邮箱收到了返利邮件但自动监控没有检测到（如 IMAP 临时断连），可以点槽位右侧的 +1 按钮手动记录一笔。
达到触发数后自动替换链接并循环到下一个槽位。

8.7 IMAP 连接检查

页面顶部有 「检查 IMAP 连接」 按钮，点一下测试 GMX IMAP 是否正常。
🟢 绿色 = 连接成功（显示邮箱前缀和邮件总数）
🔴 红色 = 连接失败（显示错误信息，检查梯子/网络）

8.8 ShopBack 邮件计数

点 「刷新 ShopBack 计数」 按钮，系统通过子进程方式扫描每个邮箱中标题含 "Cashback" / "erfasst" 的邮件数量。
结果直接显示在邮箱输入框右侧：

🛒 0 — 无 ShopBack 邮件
🛒 1 — 1 封（未达标）
🛒 2 — 2 封 ✅ 绿色底色（达标可替换）
❌ 超时 — IMAP 连接失败（自动重试一次）

扫描约需 20~30 秒，使用子进程方式避免 uvicorn 内部 SSL 问题。

8.10 返利邮件匹配规则

① 在页面底部「返利邮件匹配规则」区域点「添加」
② 配置：名称 / 发件人域名（如 shopback.de）/ 标题关键词（如 Cashback wurde erfasst）
③ 选择提取方式（如「正文第一个链接文本」适用于 ShopBack）
④ 保存规则

目前预置规则：

ShopBack — 发件域 shopback.de，关键词 "Cashback wurde erfasst"，提取正文第一个链接文本

8.11 检测记录

页面底部显示最近 30 条返利检测记录，包括检测时间、广告系列、邮箱、商户名。

8.12 页面自动刷新

返利监控页面每 5 分钟自动刷新一次，保持数据与后台监控同步。

9. 广告排队系统

9.1 功能概述

广告排队系统用于批量管理测试商家广告。支持新增商家配置、从现有 Campaign 导入广告系列、批量测试、以及直接发布 Google Ads 广告。
页面会自动统计：排队中、测试中、已通过、已暂停数量。

9.2 新增商家

① 点「新增商家」按钮
② 填写：商家名称 / 品牌名 / 关键词 / 日预算 / CPC 上限
③ 可配置多个落地页进行 A/B 测试
④ 保存后自动进入排队列表

9.3 导入已有 Campaign

① 点「导入系列」按钮 → 弹出选择框
② 可搜索过滤广告系列，勾选要导入的项
③ 点「导入选中」→ 已存在的 Campaign 被导入到排队系统
④ 目标状态可选普通排队或「一万欧」目标

9.4 测试流程

排队中的广告系列可进入「测试中」状态，系统自动验证广告能否正常展示。
测试通过后标记为「已通过」，可手动发布到 Google Ads。

9.5 同步 ADS 广告列表

点「同步 ADS 广告列表」按钮，从 Google Ads API 拉取最新的 Campaign 列表，同步到排队系统。

9.6 数据导出

在 广告系列列表 页面，每个 Campaign 可导出包含广告组、关键词、状态等详细信息的 JSON 报告。
点按钮即可导出。

10. 广告自动检查

10.1 功能说明

每次拉取数据时（fetch-campaign-data），系统自动检查所有 ENABLED 广告系列下的广告组和广告状态：

广告组（Ad Group）是否启用
广告（Ad）是否启用
发现暂停的广告 → 自动启用

10.2 查看日志

检查结果记录在操作日志中，搜 AdCheck 查看：

正常： 无 AdCheck 日志
自动修复：
[INFO] [AdCheck] [账号] [广告系列] / [广告组]: 广告 xxx 已自动启用
修复失败：
[WARN] [AdCheck] [账号] [广告系列] / [广告组]: 广告 xxx 启用失败: 错误信息

11. 出价策略

11.1 默认出价

创建广告时默认使用 Target Spend（尽可能争取更多点击），系统自动优化出价以在预算内获得最多点击。
对应 Google Ads API 中的 bidding_strategy_type = 9（TARGET_SPEND）。

11.2 修改出价上限

在 广告系列列表 页面可编辑每个 Campaign：

CPC 出价 — 每次点击最高出价上限（Max CPC bid limit）
设为 0.05 即单次点击最高不超过 $0.05
保存后同步到 Google Ads

CPC 出价上限是约束条件，实际出价可能低于上限。建议配合 Target Spend 策略使用。

11.3 批量调整出价策略

可对多个 ENABLED Campaign 统一设置 Target Spend（尽可能争取更多点击） 出价策略。
在 广告系列列表 页面对 Campaign 勾选后批量操作即可。

13. 常见问题

Q: 配置显示"未填写"但实际已填？

刷新页面即可。如果持续显示，检查是否切换到正确的 Profile（左侧下拉框）。

Q: 创建广告失败，提示 API 错误？

检查 Developer Token 是否在 Google Ads API Center 已审批通过（Explorer 级别只能测试，需要提交流量审核）。

Q: 数据监控拉取不到数据？

选7天或30天再试。如果还是空，确认 Campaign 在 Google Ads 后台有展示/点击数据。

Q: 多账号如何切换？

可在 API 设置页点账号列表的 ✓ 按钮，也可在左侧顶部的下拉框一键切换。

Q: 支持哪些地区/语言？

创建广告时可选 35 个国家/地区、24 种语言，也可在跟踪模板中使用 ValueTrack 参数。

Q: 数据保留多久？

自动保留 90 天，日期下拉框显示最近 30 天。