友盟小程序推广渠道/活动/场景效果分析技能

> umeng-cli 是友盟提供的命令行程序，所有操作通过执行 umeng-cli call 命令完成。

分析友盟小程序（U-MiniProgram）的获客来源与推广效果，覆盖：

• 获客来源排行（渠道 / 活动 / H5 场景 / 其他场景）
• 指定渠道 / 活动 / 场景值的明细统计与趋势分析
• 推广资产清单查询（取推广链接 URL 或展示用）

共 5 个接口（命名空间 com.umeng.umini，全部为只读查询）：

> ⚠️ 本 Skill 全部接口为只读查询，无写入风险；推广链接的创建由 umeng-cli-uapp-campaign 覆盖。

> 埋点上报： AI Agent 在阅读本 Skill 文档后，请执行以下命令进行调用埋点上报：

> ```bash

> umeng-cli trace '{"skill_name":"umeng-cli-uapp-mini-channel"}'

> ```

>

> Appkey 维度打点： 当本轮任务中出现 Appkey（小程序 dataSourceId）的输入操作时，在拿到该 Appkey 之后、发起首个业务 API 调用之前，再追加执行一次带 appkey 的打点：

> ```bash

> umeng-cli trace '{"skill_name":"umeng-cli-uapp-mini-channel", "appkey":"<输入的Appkey>"}'

> ```

> 同一 Appkey 在同一会话中只打一次；若用户切换到新的 Appkey，需对新的 Appkey 再打一次。

⚠️ 适用范围限制（强制）

本 Skill 仅适用于小程序 / H5 / 小游戏类应用：

当用户对 Android / iOS App 询问"渠道/活动效果"时，应明确告知：「本 Skill 仅限小程序 / H5 / 小游戏；App 渠道请用 umeng-cli-uapp-channel-version」。

前置条件：安装 umeng-cli

本 Skill 的所有调用都依赖 umeng-cli 命令行工具。使用本 Skill 前，请先确保已在本机安装。

检查是否已安装

umeng-cli --version

若提示 command not found 或类似错误，按下述方式安装。

安装方式

# 方式一：通过 npm 安装（推荐，自动安装 CLI + 内置 Skills）
npm install -g @umengfe/umeng-cli

# 方式二：通过官方安装脚本（仅安装 CLI 二进制 + Skills）
curl -fsSL https://raw.githubusercontent.com/umeng/umeng-cli/main/scripts/install.sh | sh

安装完成后再次运行 umeng-cli --version 验证。

> 更多安装说明、卸载、账号管理等参考 umeng-cli SKILL 或项目主页 https://github.com/umeng/umeng-cli

适用场景与触发词

• 「各推广渠道昨天带来了多少用户？」→ 排行
• 「XX 活动最近 7 天的效果趋势」→ 活动趋势
• 「某场景值（如 wx_1011 扫码）的数据」→ 场景明细
• 「H5 的场景来源排行」→ sourceType=platform
• 关键词：获客来源、推广渠道、推广活动、场景分析、渠道排行、活动效果、场景值、渠道趋势、活动趋势、Top N 渠道

鉴权方式

• authType: umeng-aksk（友盟 OpenAPI AK/SK 签名，HMAC-SHA1）
• baseUrl: https://gateway.open.umeng.com/openapi
• endpoint 路径规则: param2/1/com.umeng.umini/<接口名>
• AK/SK 由 umeng-cli login 自动获取并加密缓存，无需手动配置 apiKey / apiSecurity

登录状态检查

umeng-cli whoami

登录要求

当接口返回未登录或登录态过期时，需要执行 umeng-cli login --no-qr 进行登录。

AI Agent 执行登录的正确方式：

> umeng-cli login --no-qr 会在输出登录链接后阻塞等待用户在浏览器中完成登录，因此 AI Agent 应该以后台模式（is_background: true）运行此命令，这样可以立即拿到输出中的登录链接并展示给用户，无需等待命令结束。命令会在用户完成登录后自动退出并保存凭证。

如果终端不支持显示二维码（如 AI Agent 终端、SSH 远程终端等），可以使用 --no-qr 参数，仅输出可点击的登录链接：

umeng-cli login --no-qr

# 输出:
# 🔄 正在生成登录链接...
# ✅ 登录链接生成成功
#
# 🔗 请点击或复制以下链接完成登录：
#
#   👉 点击此处登录（OSC 8 可点击链接）
#   [点击登录](https://passport.umeng.com/login?redirectURL=...)
#   https://passport.umeng.com/login?redirectURL=...
#
# ⏳ 等待登录...
# ✅ 授权成功！
# ✅ 登录完成！

为什么必须提供 dataSourceId（appkey）

本 Skill 5 个接口都必须传入 dataSourceId（即小程序的 AppKey），因为统计作用域是"单个小程序"而不是"账号"。

若用户未提供 appkey：

1. 优先引导使用 umeng-cli-uapp-assets 查询小程序列表，取得 dataSourceId：

```bash

umeng-cli call '{"name":"umeng.umini.getAppList","api":{"method":"GET","baseUrl":"https://gateway.open.umeng.com/openapi","endpoint":"param2/1/com.umeng.umini/umeng.umini.getAppList","authType":"umeng-aksk"}}' '{"pageIndex":1,"pageSize":100}'

```

1. 备选引导用户从友盟官网 web.umeng.com → U-MiniProgram → 应用列表 → 复制 AppKey 获取。

🔴 关键字段告警：channel / campaign 参数必须用 getCustomerSourceOverview.id

调用接口 2（getChannelOverview）与接口 3（getCampaignOverview）时，必填的 channel / campaign 参数需要渠道/活动的内部 ID（26 位）。获取方式分两档：

> 实战经验：旧脚本曾踩坑——用 getSceneInfoList.code 直接喂给 getChannelOverview.channel 会导致 0 数据返回。正确做法是用 getCustomerSourceOverview 做"列表+取 id" 的一站式查询，见 W3 工作流。

>

> getSceneInfoList 仅适用于需要完整推广链接 URL 的展示场景（其 url 字段不可替代）。

5 个接口速查表

公共枚举（抽到顶部，避免每个接口重复）

• sourceType（仅接口 1、5）：
• 接口 1（getCustomerSourceOverview）：campaign（活动）/ channel（渠道）/ platform（H5 场景）/ scene（其他场景）
• 接口 5（getSceneInfoList）：campaign / channel
• timeUnit（接口 1–4）：5min / hour / day / 7day / 30day（接口 1 仅支持 day,7day,30day）
• indicators（接口 2–4，逗号分隔）：newUser / activeUser / launch（H5 不支持）/ visitTimes / onceDuration（H5 不支持）
• orderBy（接口 1）：newUser / activeUser / launch / visitTimes / onceDuration / createDateTime
• direction（接口 1）：asc / desc（默认 desc）

接口 1：umeng.umini.getCustomerSourceOverview — 获客来源排行

参数

调用示例

# 渠道排行（默认，昨天）
umeng-cli call '{"name":"umeng.umini.getCustomerSourceOverview","api":{"method":"GET","baseUrl":"https://gateway.open.umeng.com/openapi","endpoint":"param2/1/com.umeng.umini/umeng.umini.getCustomerSourceOverview","authType":"umeng-aksk"}}' '{"dataSourceId":"1dfe1b2f3597245664499a91","sourceType":"channel","fromDate":"2026-04-27","toDate":"2026-04-27","timeUnit":"day"}'

# 活动排行（按活跃用户降序）
umeng-cli call '{"name":"umeng.umini.getCustomerSourceOverview",...}' '{"dataSourceId":"1dfe...","sourceType":"campaign","fromDate":"2026-04-27","toDate":"2026-04-27","timeUnit":"day","orderBy":"activeUser"}'

# H5 场景排行
umeng-cli call '{"name":"umeng.umini.getCustomerSourceOverview",...}' '{"dataSourceId":"1dfe...","sourceType":"platform","fromDate":"2026-04-27","toDate":"2026-04-27","timeUnit":"day"}'

返回字段（data[] 数组）

接口 2：umeng.umini.getChannelOverview — 指定渠道明细/趋势

参数

调用示例

# 某渠道过去 7 天活跃用户趋势
umeng-cli call '{"name":"umeng.umini.getChannelOverview","api":{"method":"GET","baseUrl":"https://gateway.open.umeng.com/openapi","endpoint":"param2/1/com.umeng.umini/umeng.umini.getChannelOverview","authType":"umeng-aksk"}}' '{"dataSourceId":"1dfe1b2f3597245664499a91","channel":"5e8c6dea978eea071c37c68201","fromDate":"2026-04-21","toDate":"2026-04-27","timeUnit":"day","indicators":"activeUser,newUser,visitTimes"}'

返回字段（data.data[]）

> 数据按 dateTime 降序排列（最新日期在前）。做趋势分析时，data[-1] 为初期值、data[0] 为末期值。

接口 3：umeng.umini.getCampaignOverview — 指定活动明细/趋势

参数

调用示例

# 某活动过去 30 天新增用户趋势
umeng-cli call '{"name":"umeng.umini.getCampaignOverview","api":{"method":"GET","baseUrl":"https://gateway.open.umeng.com/openapi","endpoint":"param2/1/com.umeng.umini/umeng.umini.getCampaignOverview","authType":"umeng-aksk"}}' '{"dataSourceId":"1dfe1b2f3597245664499a91","campaign":"5e8c6dea978eea071c37c68202","fromDate":"2026-03-29","toDate":"2026-04-27","timeUnit":"day","indicators":"newUser"}'

返回字段结构与接口 2 一致（refererIndicatorDTO[]）。

接口 4：umeng.umini.getSceneOverview — 指定场景值明细/趋势（⚠️ H5 不支持）

参数

调用示例

# 微信扫二维码场景过去 7 天数据
umeng-cli call '{"name":"umeng.umini.getSceneOverview","api":{"method":"GET","baseUrl":"https://gateway.open.umeng.com/openapi","endpoint":"param2/1/com.umeng.umini/umeng.umini.getSceneOverview","authType":"umeng-aksk"}}' '{"dataSourceId":"1dfe1b2f3597245664499a91","scene":"wx_1011","fromDate":"2026-04-21","toDate":"2026-04-27","timeUnit":"day","indicators":"newUser,activeUser,visitTimes"}'

> ⚠️ H5 整体不支持本接口：若应用是 html_5 平台，应改用接口 1 的 sourceType=platform 查询 H5 场景来源。

返回字段结构与接口 2 一致。

接口 5：umeng.umini.getSceneInfoList — 推广活动/渠道清单（含 URL）

参数

调用示例

# 活动清单（含完整 url）
umeng-cli call '{"name":"umeng.umini.getSceneInfoList","api":{"method":"GET","baseUrl":"https://gateway.open.umeng.com/openapi","endpoint":"param2/1/com.umeng.umini/umeng.umini.getSceneInfoList","authType":"umeng-aksk"}}' '{"dataSourceId":"1dfe1b2f3597245664499a91","sourceType":"campaign"}'

返回字段（data[]）

> 本接口的唯一高价值字段是 url（展示推广链接用）；取 ID 请用接口 1。

典型问法与内部意图映射

工作流

W1：获客来源 Top N 排行（最常用）

目标：一次返回「昨天」或「最近 N 天」的渠道/活动/场景排行。

# 渠道排行昨天 Top 10
umeng-cli call '{"name":"umeng.umini.getCustomerSourceOverview",...}' '{"dataSourceId":"...","sourceType":"channel","fromDate":"2026-04-27","toDate":"2026-04-27","timeUnit":"day","orderBy":"newUser","direction":"desc"}'

输出处理：按 data[] 前 N 个条目展示「名称 / 新增 / 活跃 / 打开次数」，指出 Top 1 的关键数据。

W2：指定渠道/活动/场景的明细与趋势

目标：对已知 ID 的渠道/活动，或已知场景值编码，查看时间序列数据。

# 示例：某渠道过去 7 天
umeng-cli call '{"name":"umeng.umini.getChannelOverview",...}' '{"dataSourceId":"...","channel":"<从W3取到的id>","fromDate":"2026-04-21","toDate":"2026-04-27","timeUnit":"day","indicators":"newUser,activeUser,visitTimes"}'

趋势解读：数据降序排列 → data[0]=末期值，data[-1]=初期值；(末-初)/初 计算涨跌幅。

W3：先排行取 id，再查明细（必走）

目标：用户给出渠道/活动中文名称（非 ID）时的标准流程，避开 getSceneInfoList.code 不可用陷阱。

步骤：

1. 调用接口 1 getCustomerSourceOverview（fromDate=toDate=昨天，sourceType=channel 或 campaign）。
2. 在返回 data[] 中按 name 模糊匹配用户提到的名称，取得 id 字段。
3. 将该 id 作为 channel / campaign 参数调用接口 2 / 3 做趋势分析。

反例（不要这样做）：

# ❌ 错误：用接口 5 返回的 code 当作 channel 参数 → 返回空数据
umeng-cli call '{"name":"umeng.umini.getSceneInfoList",...}' → data[].code = "cp_5f8a3b"
umeng-cli call '{"name":"umeng.umini.getChannelOverview",...}' '{"channel":"cp_5f8a3b",...}'  # 0 数据

正例：

# ✅ 正确：用接口 1 返回的 id
umeng-cli call '{"name":"umeng.umini.getCustomerSourceOverview",...}' → data[].id = "5e8c6dea978eea071c37c68201"
umeng-cli call '{"name":"umeng.umini.getChannelOverview",...}' '{"channel":"5e8c6dea978eea071c37c68201",...}'  # ✅ 有数据

W4：H5 场景来源对比（H5 专属）

H5 应用（html_5）不能调用接口 4 getSceneOverview，改用接口 1 + sourceType=platform：

umeng-cli call '{"name":"umeng.umini.getCustomerSourceOverview",...}' '{"dataSourceId":"...","sourceType":"platform","fromDate":"2026-04-27","toDate":"2026-04-27","timeUnit":"day"}'

W5：取推广链接 URL（接口 5 唯一必要场景）

仅当需要向用户展示完整推广链接 URL 时才调用接口 5：

umeng-cli call '{"name":"umeng.umini.getSceneInfoList",...}' '{"dataSourceId":"...","sourceType":"campaign"}'
# 返回 data[].url 是完整 URL

注意：接口 5 的 code 不可用于接口 2/3（见「关键字段告警」小节）。

W6：Android/iOS App 退回

• 若用户是 Android/iOS App 询问"渠道/活动效果" → 直接回复"本 Skill 仅限小程序 / H5 / 小游戏；App 渠道请用 umeng-cli-uapp-channel-version"。

字段别名与旧参数对照表

本 Skill 直达友盟 OpenAPI 参数名，旧 scripts/mini_channel.py 的 CLI 抽象层参数对应关系如下：

边界与异常处理

与其他 Skill 的边界

历史产物说明

• 旧实现 skills/uapp-mini-channel/ 目录 + scripts/mini_channel.py（Python SDK + apiKey/apiSecurity 落盘配置）保留兼容，不删除。
• 旧打包 skills/uapp-mini-channel-1.1.0.zip 保留兼容。
• 本 Skill 与旧 uapp-mini-channel 能力完全等价（零能力扩展）：覆盖相同的 5 个接口，仅做调用形态（CLI 化）与鉴权（umeng-aksk）的升级，并额外提供 getSceneInfoList.code 不可用陷阱的显式告警（新收益）。

快速自检清单（AI 使用本 Skill 前自检）

• [ ] 已确认用户小程序（非 App），已取得 dataSourceId
• [ ] 查询指定渠道/活动时，已通过接口 1（getCustomerSourceOverview）取 id 字段，未混用接口 5 的 code
• [ ] H5 应用未调用接口 4 getSceneOverview；已改用接口 1 sourceType=platform
• [ ] H5 应用 indicators 已避开 launch / onceDuration（或已明确告知字段 H5 不支持）
• [ ] sourceType / timeUnit / indicators 枚举值全部在白名单内
• [ ] 趋势分析已理解数据按 dateTime 降序排列（data[0]=末期、data[-1]=初期）