mediainsight-ad-traffic-universal

by nonorongrong-design

Install this Skill

curl -fsSL -o mediainsight-ad-traffic-universal.zip https://skill.seembox.com/api/v1/skills/mediainsight-ad-traffic-universal/download && unzip mediainsight-ad-traffic-universal.zip

Download mediainsight-ad-traffic-universal.zip

SKILL.md About

---
name: mediainsight-ad-traffic-universal
description: 查询广告投放流量分布与趋势的数据分析技能。支持按行业、地域、媒体（OTT/移动端）、目标受众等多维度分析广告曝光数据，适用于媒体策略评估、竞品投放监测、行业广告趋势研究等场景。
---

# MediaInsight 广告流量通用技能

## 快速体验

从 **skill 根目录** 执行以下命令可直接体验。
整个 skill 目录可单独打包分享，不依赖仓库其他 Python 模块。

脚本内置了一个公开演示 Token。
这个 Token 权限受限，只能看到有限的行业、广告主、品牌、媒体、地域与数据集。

新建任务默认值：

- 行业默认：`美妆个护类`
- 广告主默认：`明略集团`
- 品牌默认：`明略科技`
- 媒体默认：当前 Token 可见的全部**媒体大类**（即 `type=1` 顶层媒体类目），不是全部具体媒体

默认输出可以理解为：

- `美妆个护类` 行业
- 在当前默认 Token 可见的全部**媒介类型 / 媒体大类**上
- 查看广告流量分布

如果用户希望：

- 查看其他行业
- 细化到具体媒体而不是媒体大类
- 使用更完整的权限范围

则需要使用自己的账号 Token，或单独申请具备对应权限的账号。

```bash
python3 ./scripts/submit_ad_task.py \
  --task-name '演示：近1月广告流量分布' \
  --region-name 北京市 \
  --region-name 上海市 \
  --region-name 广州市 \
  --region-name 深圳市 \
  --months-back 1
```

> 如需使用自己的权限视图，可显式传入 `--jwt` 或 `--jwt-file` 覆盖默认演示 Token。

## 适用场景

当用户需要分析**广告流量**分布或趋势，并提供以下信息时，使用此技能：

- **MediaInsight JWT Token**：用于身份验证，从中提取用户凭据。
- **业务约束条件**：包括行业、广告主、品牌、目标受众（TA）、地域范围、媒体范围等。
- 如果用户没有指定行业，默认使用 `美妆个护类`。该行业在当前默认 Token 下的实际 ID 为 `000000130000000000001960`。
- 如果用户没有指定媒体，默认选择当前 Token 可见的全部**媒体大类**。这不是单个固定 ID，而是当前 Token 可见的 `type=1` 顶层媒体类目集合；当前默认 Token 下共 25 个。
- 因此默认 Token 的典型输出，不是“全行业、全媒体明细”，而是“美妆个护行业在所有可见媒介类型上的广告流量”。

## 核心入口

调用本目录下的脚本：

```bash
./scripts/submit_ad_task.py
```

下载已完成任务结果时，调用：

```bash
./scripts/download_ad_task_report.py --biz-id 104433 --extract-dir ./downloads/task-104433
```

注意：
任务创建成功后，报告文件生成通常还需要额外时间。
实际测试中，文件生成过程可能耗时约 10 分钟，建议至少等待 10 分钟后再执行下载。
如果过早下载，脚本会返回 `report file is not ready for download`。

## 执行流程

1. 解码 JWT Payload，从 `sub` 字段提取 `username` 和 `password`。
2. 使用提取的凭据登录 MediaInsight。
3. 读取该用户权限范围内的实时字典：
   - 数据集、行业、广告主、品牌、地域、目标受众（TA）、媒体、投放类型、广告点位类型。
4. 仅在该 Token 可见的选项范围内解析用户输入的名称为 ID。
5. 将"全部媒体"展开为该 Token 可见的**全量**媒体 ID 集合（而非部分子集）。
   如果用户未指定媒体，也未要求 all media，则默认使用当前 Token 可见的全部**媒体大类**（type=1）。
6. 计算本次任务消耗的积分数。
7. 提交任务。
8. 任务完成后，如需取回结果文件，按 `bizId` 或内部 `taskId` 下载报告 ZIP，并可解压得到 CSV。
   报告文件生成可能耗时约 10 分钟，下载前应先等待文件生成完成。

## 操作规则

1. **禁止硬编码**：不得跨用户硬编码广告主、品牌、媒体、地域或行业 ID，所有 ID 必须从当前 Token 的字典中动态解析。
2. **权限边界**：若请求的名称在当前 Token 的字典中不存在，立即停止，向用户说明该项超出当前账号权限范围。
3. **媒体展开规则**："全部媒体"必须展开为该 Token 可见的完整具体媒体列表，不得只取少量精选子集。
4. **名称匹配策略**：优先精确匹配；仅当精确匹配无结果且存在唯一部分匹配时，才使用模糊匹配。
5. **可审计性**：如需保留审计记录或保证任务可复现，将解析后的 Payload 写入文件（使用 `--payload-out` 参数）。

## 标准调用示例

```bash
python3 ./scripts/submit_ad_task.py \
  --task-name '近2月美妆个护媒体大类流量分布' \
  --industry-name '美妆个护类' \
  --gender female \
  --age-range 20-49 \
  --region-name 北京市 \
  --region-name 上海市 \
  --region-name 广州市 \
  --region-name 深圳市 \
  --months-back 2 \
  --payload-out /tmp/mediainsight-task.json
```

## 常用参数变体

| 场景 | 参数 |
|------|------|
| 使用默认行业 | 可省略 `--industry-name`，默认 `美妆个护类` |
| 使用默认媒体大类 | 可省略 `--media-name` 和 `--all-media`，脚本会自动选择当前 Token 可见的全部 `type=1` 媒体大类 |
| 仅查询单月数据 | `--months-back 1` |
| 指定特定数据集 | `--dataset 202603` |
| 指定具体媒体（替代全媒体） | `--media-name 爱奇艺 --media-name 腾讯新闻` |
| 指定开放年龄段 | `--age-range 20+` 或 `--age-range 20岁及以上` |
| 查询全部人群 | `--gender all --age-range all` |
| 仅解析不提交（调试模式） | `--dry-run` |

## 年龄参数规则

`--age-range` 不要使用 `20-99` 这类近似写法。
请直接使用产品语义对应的年龄表达，脚本会自动映射到真实 TA 年龄桶。

- `20-49`：表示 20-24、25-29、30-34、35-39、40-44、45-49
- `20+`：表示 20 岁及以上，会覆盖到 `60岁及以上`
- `20岁及以上`：等价于 `20+`
- `all`：表示全部年龄段

如果用户说“男 20+”，应使用：

```bash
--gender male --age-range 20+
```

不要改写成：

```bash
--gender male --age-range 20-99
```

## 预期输出

脚本输出一个 JSON 对象，包含以下字段：

| 字段 | 说明 |
|------|------|
| `login` | 登录状态 |
| `session_file` | 会话文件路径 |
| `resolvedPayload` | 解析后的完整任务参数 |
| `coin` | 本次任务消耗的积分数 |
| `create` | 任务创建结果（`--dry-run` 模式下不包含此字段） |

注意：
`resolvedPayload.reportArgsAd.mediaList` 在三种情况下含义不同：

- 省略媒体参数：默认写入当前 Token 可见的全部**媒体大类** ID（type=1）
- `--all-media`：写入当前 Token 可见的全部具体媒体 ID（type=3）
- `--media-name ...`：写入用户指定名称解析出的媒体/媒体类目 ID

结果下载提醒：

- 任务创建成功不等于结果文件立刻可下载
- 报告文件生成过程可能耗时约 10 分钟
- 建议等待约 10 分钟后，再调用 `download_ad_task_report.py`

## 异常处理

| 异常现象 | 原因判断 |
|----------|----------|
| 登录失败 | JWT 无效或已过期 |
| 名称解析失败 | 该名称超出当前账号的权限范围 |
| 积分计算成功但任务提交失败 | 提交链路本身有效，失败原因在任务侧，非技能问题 |

_meta.json Metadata

{
  "ownerId": "kn7aeneh00khv5yv92bqyvbekd827dc5",
  "publishedAt": 1777538699611,
  "slug": "mediainsight-ad-traffic-universal",
  "version": "1.0.0"
}