diff --git a/SKILL.md b/SKILL.md index 8e4bc76..192f2bf 100644 --- a/SKILL.md +++ b/SKILL.md @@ -43,6 +43,10 @@ The helper recomputes ratios from aggregate numerators and denominators: Return `null`/`N/A` when a denominator is zero. Never average row-level ratios. +## Example + +For a synthetic end-to-end example, read [examples/README.md](examples/README.md). It includes a sample `creative_breakdown` response, deterministic product aggregation, and a rendered Script Daily Report in HTML and PNG. Use it to understand the workflow and artifact shape only; never reuse its example scripts or metrics in a live report. + ## Interpretation - Treat TikTok orders and GMV as platform-attribution evidence, not causal incrementality. diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..77cdba7 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,27 @@ +# Synthetic Script Daily Report example + +This example shows the complete artifact shape without using a real account, credentials, customer names, or live campaign data. + +## Files + +- `query.json` — synthetic `creative_breakdown` response. It deliberately includes one product-card row so the helper's video-only exclusion is observable. +- `report-data.json` — deterministic output from the aggregation helper with `--top 2`. +- `script-daily-report.html` — self-contained example report with exactly three cross-product scripts. +- `script-daily-report.png` — rendered primary deliverable. + +## Reproduce the aggregation + +From the repository root: + +```bash +python3 scripts/aggregate_video_products.py examples/query.json --top 2 > /tmp/swads-example-output.json +diff -u examples/report-data.json /tmp/swads-example-output.json +``` + +An empty diff confirms that product-card delivery was excluded and the aggregate ratios were recomputed from numerators and denominators. + +## Expected interpretation + +- The demo pot has the stronger CTR and ROAS at useful but still limited scale; preserve its visible specification proof and test controlled variants. +- The demo jug has positive attributed revenue, but the capacity/leak proof version has clicks without orders; strengthen proof and product-page alignment. +- The three example scripts are derived from these synthetic patterns. Live reports must derive new scripts from the requested reporting window and must not copy these scripts by default. diff --git a/examples/query.json b/examples/query.json new file mode 100644 index 0000000..c5ee4ce --- /dev/null +++ b/examples/query.json @@ -0,0 +1,27 @@ +{ + "columns": [ + {"name": "external_creative_id", "type": "string", "role": "dimension"}, + {"name": "external_creative_name", "type": "string", "role": "dimension"}, + {"name": "creative_identity_kind", "type": "string", "role": "dimension"}, + {"name": "creative_creator_name", "type": "string", "role": "dimension"}, + {"name": "creative_product_id", "type": "string", "role": "dimension"}, + {"name": "spend", "type": "number", "role": "metric"}, + {"name": "gross_revenue", "type": "number", "role": "metric"}, + {"name": "orders", "type": "number", "role": "metric"}, + {"name": "product_impressions", "type": "number", "role": "metric"}, + {"name": "product_clicks", "type": "number", "role": "metric"} + ], + "rows": [ + ["video-pot-proof", "304 material + 24cm visible proof", "item", "Demo Shop", "demo-pot-001", 20, 50, 2, 1000, 50], + ["video-pot-usecase", "One pot for soup, noodles, and hotpot", "item", "Demo Shop", "demo-pot-001", 10, 0, 0, 500, 20], + ["video-jug-family", "1.5L jug + four cups for the family", "item", "Demo Shop", "demo-jug-002", 12, 24, 1, 800, 24], + ["video-jug-proof", "Capacity and leak test", "item", "Demo Shop", "demo-jug-002", 8, 0, 0, 400, 16], + ["product_card:demo-pot-001", "", "product_card", "", "demo-pot-001", 100, 240, 8, 9000, 300] + ], + "row_count": 5, + "query_meta": { + "date_from": "2026-08-13", + "date_to": "2026-08-21", + "synthetic": true + } +} diff --git a/examples/report-data.json b/examples/report-data.json new file mode 100644 index 0000000..896df97 --- /dev/null +++ b/examples/report-data.json @@ -0,0 +1,74 @@ +{ + "products": [ + { + "product_id": "demo-pot-001", + "video_count": 2, + "spend": 30.0, + "gross_revenue": 50.0, + "orders": 2.0, + "product_impressions": 1500.0, + "product_clicks": 70.0, + "video_ctr": 0.04666666666666667, + "order_conversion_rate": 0.02857142857142857, + "roas": 1.6666666666666667, + "cost_per_order": 15.0, + "top_videos": [ + { + "external_creative_id": "video-pot-proof", + "external_creative_name": "304 material + 24cm visible proof", + "creative_creator_name": "Demo Shop", + "spend": 20, + "gross_revenue": 50, + "orders": 2, + "product_impressions": 1000, + "product_clicks": 50 + }, + { + "external_creative_id": "video-pot-usecase", + "external_creative_name": "One pot for soup, noodles, and hotpot", + "creative_creator_name": "Demo Shop", + "spend": 10, + "gross_revenue": 0, + "orders": 0, + "product_impressions": 500, + "product_clicks": 20 + } + ] + }, + { + "product_id": "demo-jug-002", + "video_count": 2, + "spend": 20.0, + "gross_revenue": 24.0, + "orders": 1.0, + "product_impressions": 1200.0, + "product_clicks": 40.0, + "video_ctr": 0.03333333333333333, + "order_conversion_rate": 0.025, + "roas": 1.2, + "cost_per_order": 20.0, + "top_videos": [ + { + "external_creative_id": "video-jug-family", + "external_creative_name": "1.5L jug + four cups for the family", + "creative_creator_name": "Demo Shop", + "spend": 12, + "gross_revenue": 24, + "orders": 1, + "product_impressions": 800, + "product_clicks": 24 + }, + { + "external_creative_id": "video-jug-proof", + "external_creative_name": "Capacity and leak test", + "creative_creator_name": "Demo Shop", + "spend": 8, + "gross_revenue": 0, + "orders": 0, + "product_impressions": 400, + "product_clicks": 16 + } + ] + } + ] +} diff --git a/examples/script-daily-report.html b/examples/script-daily-report.html new file mode 100644 index 0000000..19d64a9 --- /dev/null +++ b/examples/script-daily-report.html @@ -0,0 +1,28 @@ + + + + + +SW Ads 脚本日报 · 合成示例 + + +
+
SW ADS · SYNTHETIC EXAMPLE

脚本日报

2026.08.13–08.21 · 两个演示商品 · 所有数据均为合成示例
只读工作流 · 非真实账户数据
+
视频消耗50.00
商品曝光2,700
商品点击110
综合CTR4.07%
归因订单 / ROAS3 / 1.48×
+
示例结论：锅具的规格证明同时带来较高点击与订单；水壶的生活场景带来订单，但容量/防漏证明仍需加强。本示例不代表任何真实账户结果。
+

商品视频对比

+ + + +
商品视频曝光 / 点击CTR订单 / CVR消耗 / ROAS诊断与建议
304不锈钢24cm汤锅
demo-pot-001		21,500 / 704.67%2 / 2.86%30 / 1.67ד304材质＋24cm”可见证明最强；保留承诺，只改变开头与证明顺序。
1.5L水壶＋4杯套装
demo-jug-002		21,200 / 403.33%1 / 2.50%20 / 1.20×家庭场景有订单；容量与防漏版本有点击无订单，需加强可见证明和商品页承接。
+

本周三套通用脚本

+

脚本1｜规格限时证明

依据：锅具规格证明视频贡献2单、CTR 5.00%。
假设：把[核心规格]放在首屏，并立即完成[可见证明]，可提高合格点击。
0–3s
“[时间]内验证[核心规格]。”
3–8s
近景展示刻度、材质或尺寸。
8–14s
完成容量/受热/防漏测试。
14–18s
展示[结果]，CTA“先看规格”。
+

脚本2｜生活场景＋整套价值

依据：水壶家庭场景视频贡献1单、ROAS 2.00×。
假设：先展示多人真实使用，再解释件数和容量，可增强整套价值感。
0–3s
先给出聚会/家庭使用结果。
3–8s
字幕：[容量]＋[件数]。
8–14s
多人或多菜式连续使用。
14–18s
CTA“看看是否适合你家”。
+

脚本3｜购买疑虑逐项验证

依据：水壶证明版本有16次点击但0单，说明兴趣之后仍缺成交证据。
假设：依次回应[核心疑虑]、价格与清洁/耐用问题，可改善点击后转化。
0–3s
评论回复：“真的[核心疑虑]吗？”
3–9s
无剪切完成一次真实测试。
9–14s
展示清洁、容量或耐用细节。
14–19s
给出规格/价格，低压力CTA。
+
+

字段替换

商品[核心规格/痛点][可见证明][结果]
汤锅304材质、24cm、多用途受热、容量、清洗一锅完成日常烹饪
水壶套装1.5L、4杯、家庭使用刻度、倒水、防漏多人饮水更完整
+
示例数据：合成，不对应任何客户或账户。Requires human confirmation：预算、投放状态、发布与商品锚点均未执行。
+
diff --git a/examples/script-daily-report.png b/examples/script-daily-report.png new file mode 100644 index 0000000..0605a67 Binary files /dev/null and b/examples/script-daily-report.png differ