00 setup checklist

clicks-timeline 部署清单

一、整体架构
- `clicks-timeline-1.txt` 到 `clicks-timeline-6.txt` 是 6 个 Google Ads Scripts 采集脚本
- 这 6 个脚本都写入同一个 spreadsheet URL
- 但每个脚本只写自己的 shard tab，避免同时 append 到同一张表时撞行
- `clicks-timeline-7.txt` 是 1 个 Apps Script 汇总脚本
- `clicks-timeline-7.txt` 负责把 6 个 shard tab 合并到 1 个总表 tab

二、这 7 个文件分别是什么
- `clicks-timeline-1.txt`：Google Ads Scripts，写 `21_clicks_timeline_shard_00`
- `clicks-timeline-2.txt`：Google Ads Scripts，写 `21_clicks_timeline_shard_01`
- `clicks-timeline-3.txt`：Google Ads Scripts，写 `21_clicks_timeline_shard_02`
- `clicks-timeline-4.txt`：Google Ads Scripts，写 `21_clicks_timeline_shard_03`
- `clicks-timeline-5.txt`：Google Ads Scripts，写 `21_clicks_timeline_shard_04`
- `clicks-timeline-6.txt`：Google Ads Scripts，写 `21_clicks_timeline_shard_05`
- `clicks-timeline-7.txt`：Apps Script，汇总 6 个 shard 到 `21_clicks_timeline_all`

三、目标表格
- Spreadsheet URL：
- https://docs.google.com/spreadsheets/d/1IRVoni0t8VQc2u9G35ajuC28vRyCBiJ3wYULpnipDwI/edit

四、会自动写入的工作表
- shard 明细表：
- `21_clicks_timeline_shard_00`
- `21_clicks_timeline_shard_01`
- `21_clicks_timeline_shard_02`
- `21_clicks_timeline_shard_03`
- `21_clicks_timeline_shard_04`
- `21_clicks_timeline_shard_05`
- 汇总表：
- `21_clicks_timeline_all`
- 运行日志表：
- `00_RUN_LOG_CLICKS_TIMELINE_shard_00`
- `00_RUN_LOG_CLICKS_TIMELINE_shard_01`
- `00_RUN_LOG_CLICKS_TIMELINE_shard_02`
- `00_RUN_LOG_CLICKS_TIMELINE_shard_03`
- `00_RUN_LOG_CLICKS_TIMELINE_shard_04`
- `00_RUN_LOG_CLICKS_TIMELINE_shard_05`
- `00_RUN_LOG_CLICKS_TIMELINE_MERGE`
- 状态表：
- `00_STATUS_CLICKS_TIMELINE_clicks-timeline-shard-00`
- `00_STATUS_CLICKS_TIMELINE_clicks-timeline-shard-01`
- `00_STATUS_CLICKS_TIMELINE_clicks-timeline-shard-02`
- `00_STATUS_CLICKS_TIMELINE_clicks-timeline-shard-03`
- `00_STATUS_CLICKS_TIMELINE_clicks-timeline-shard-04`
- `00_STATUS_CLICKS_TIMELINE_clicks-timeline-shard-05`
- `00_STATUS_CLICKS_TIMELINE_MERGE`

五、正确的部署位置
- `clicks-timeline-1.txt` 到 `clicks-timeline-6.txt`：
- 放到 Google Ads 后台的 `Tools -> Bulk actions -> Scripts`
- `clicks-timeline-7.txt`：
- 不要放到 Google Ads Scripts
- 要放到独立的 Apps Script 项目，地址是 `https://script.google.com`

六、为什么你会看到 “script has no main function”
- 因为你把 `clicks-timeline-7.txt` 粘贴进了 Google Ads Scripts
- Google Ads Scripts 编辑器要求入口函数必须叫 `main()`
- 但 `clicks-timeline-7.txt` 不是 Google Ads Scripts，它是 Apps Script 汇总脚本
- 所以这个报错不是逻辑错，是运行环境放错了

七、怎么建和怎么跑
1. 在 Google Ads Scripts 里新建 6 个脚本项目
2. 分别粘贴 `clicks-timeline-1.txt` 到 `clicks-timeline-6.txt`
3. 每个脚本先点一次 `Preview` 或 `Run` 完成授权
4. 这 6 个脚本都设置成 `Hourly`
5. 如果你的界面允许选具体分钟，再错开到不同分钟
6. 如果你的界面只显示 `Hourly`，那就保持 `Hourly`，不要硬找 10 分钟入口
7. 再去 `https://script.google.com` 新建 1 个 Apps Script 项目
8. 把 `clicks-timeline-7.txt` 粘贴进去
9. 先手动运行一次 `mergeClicksTimelineShards()` 完成授权
10. 再手动运行一次 `installEvery10MinMergeTrigger()`
11. 之后 Apps Script 会自己每 10 分钟汇总一次

八、时间频率怎么理解
- `clicks-timeline-1.txt` 到 `clicks-timeline-6.txt`：采集频率是每小时
- `clicks-timeline-7.txt`：汇总频率是每 10 分钟
- 所以总表 `21_clicks_timeline_all` 会更频繁刷新
- 但底层采集数据本身并不会每 10 分钟新增，因为 Google Ads Scripts 这一层还是按小时采

九、一个重要现实限制
- 如果你现在这个 Google Ads Scripts 界面只有 `Hourly`
- 那就说明这 6 个采集脚本不能被你精确设成 `00/10/20/30/40/50`
- 在这种情况下，6 个 shard 的主要价值是分流数据量、降低超时风险
- 不是把采集频率硬提升到每 10 分钟
- 如果你以后真的要“采集也每 10 分钟一次”，那要改成 Google Ads API + 外部定时器，不能只靠 Google Ads Scripts UI

十、为什么 6 个 shard 仍然有价值
- `clicks-timeline-1.txt` 到 `clicks-timeline-6.txt` 不是重复采集同一份数据
- 它们会按 `campaign / ad group / ad / keyword / search term` 组合做固定哈希分片
- 同一条 search term 只会落到其中 1 个 shard，不会 6 份都写
- 这样做的好处是：
- 单个脚本扫描的数据量更小
- 单个脚本更不容易超时
- 单个脚本更不容易因为行数太多被截断
- 单个 tab 也不会被 6 个脚本同时 append
- 所以即使只能 `Hourly`，这套也不是白搭，核心收益是稳定性和扩展性

十一、飞书通知规则
- `clicks-timeline-1.txt` 到 `clicks-timeline-6.txt` 默认都开启飞书
- 它们的默认规则是：
- 有写入数据并且状态是 `FINISHED` 时会发
- 遇到 `PAUSED_TIMEOUT` 时会发
- 遇到 `PAUSED_MAX_ROWS` 时会发
- 如果这次没有写到新数据，默认不发，因为 `SEND_FEISHU_ON_EMPTY = false`
- `clicks-timeline-7.txt` 默认也开启飞书
- 它的默认规则是：
- merge 成功 `FINISHED` 会发
- merge 失败 `ERROR` 会发
- 因为 `clicks-timeline-7.txt` 是每 10 分钟跑一次，所以它可能会比较吵

十二、飞书配置优先级
- 脚本会优先读取 Script Properties 里的飞书配置
- 读取顺序是：
- `RAC_FEISHU_WEBHOOK_URL`
- `FEISHU_WEBHOOK_URL`
- 如果都没有，才回退到代码里写死的 webhook
- token 也是同样逻辑：
- `RAC_FEISHU_TOKEN`
- `FEISHU_TOKEN`
- 如果都没有，才回退到代码里的 token
- 更稳妥的做法是把 webhook 和 token 放进 Script Properties，不要长期硬编码

十三、如果你现在已经基本都配好了
- `clicks-timeline-1.txt` 到 `clicks-timeline-6.txt` 继续保留在 Google Ads Scripts
- 这 6 个脚本都设成 `Hourly` 就可以
- 不需要因为不能精确卡到 `00/10/20/30/40/50` 就重做
- 你真正需要调整的只有 `clicks-timeline-7.txt`
- 如果它现在被放在 Google Ads Scripts 里，就把它移到 Apps Script
- 然后在 Apps Script 里运行：
- `mergeClicksTimelineShards()`
- `installEvery10MinMergeTrigger()`

十四、最实在的结论
- 现在这套不是“10 分钟级采集”
- 现在这套是“小时级采集 + 10 分钟级汇总”
- 这对大账户、关键词多、search term 多、容易超时的情况是有价值的
- 如果你未来要真正做到 10 分钟级采集，只能上 Google Ads API + 外部定时器

本文档为站内渲染。原始文件本地路径：saas/source/ads/广告-ads-data-script-clicks-timeline-bundle-20260307-00_setup--0448b6.txt（仅本地保留，不入库不部署）