友盟 U-App 渠道/版本分析技能

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

查询友盟 U-App（移动统计）在渠道维度与版本维度的统计数据，覆盖两个场景：

• 单日快照：指定日期的渠道/版本表现排名（活跃/新增/启动/总用户占比等）
• 趋势分析：指定渠道/版本在一段时间内的启动次数、活跃用户、新增用户趋势

共 5 个只读查询接口。

> 埋点上报： AI Agent 在阅读本 Skill 文档后，请执行以下命令进行调用埋点上报：
> bash > umeng-cli trace '{"skill_name":"umeng-cli-uapp-channel-version"}' >
>
> Appkey 维度打点： 当本轮任务中出现 Appkey 的输入操作时，在拿到该 Appkey 之后、发起首个业务 API 调用之前，再追加执行一次带 appkey 的打点：
> bash > umeng-cli trace '{"skill_name":"umeng-cli-uapp-channel-version", "appkey":"<输入的Appkey>"}' >
> 同一 Appkey 在同一会话中只打一次；若用户切换到新的 Appkey，需对新的 Appkey 再打一次。

前置条件：安装 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

适用场景与触发词

• 用户询问各渠道或版本的单日表现对比（Top N、排名）
• 用户询问某个渠道/版本过去 N 天的趋势
• 用户询问新版本上线后用户表现
• 关键词：渠道分析、版本分析、渠道对比、版本对比、哪个渠道、哪个版本、渠道排名、版本表现、渠道趋势、版本趋势、新版本对比

鉴权方式

• authType: umeng-aksk（友盟 OpenAPI AK/SK 签名，HMAC-SHA1）
• baseUrl: https://gateway.open.umeng.com/openapi
• endpoint 路径规则: param2/1/com.umeng.uapp/<接口名>
• 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=...
#
# ⏳ 等待登录...
# ✅ 授权成功！
# ✅ 登录完成！

获取 appkey

所有接口均以 appkey 作为应用维度标识。

获取路径：
1. 直接要求用户提供 appkey
2. 若用户不知道，引导至友盟官网 https://www.umeng.com/ 登录后在应用管理后台复制
3. （进阶）可调用同 namespace 的 umeng.uapp.getAppList 搜索获取

通用调用格式

umeng-cli call '{
  "name": "umeng.uapp.<接口名>",
  "api": {
    "method": "GET",
    "baseUrl": "https://gateway.open.umeng.com/openapi",
    "endpoint": "param2/1/com.umeng.uapp/umeng.uapp.<接口名>",
    "authType": "umeng-aksk"
  }
}' '<参数JSON>'

• 本 Skill 的 5 个接口均为 GET 方法
• endpoint 路径遵循统一格式 param2/1/com.umeng.uapp/<接口名>

接口路由表

单日快照（渠道/版本当日排名）

趋势分析（按时间范围 + 渠道/版本过滤）

> 💡 服务端无排序参数：5 个接口均不支持 sort-by / top，排序与 Top N 由客户端（LLM 侧）在返回数据上完成。

操作

1. 获取渠道维度单日统计数据 (getChannelData)

获取指定 App 按照分发渠道维度的单日统计数据，支持分页。

参数说明：

调用示例：

# 查询 2025-04-27 各渠道前 50 条
umeng-cli call '{
  "name": "umeng.uapp.getChannelData",
  "api": {
    "method": "GET",
    "baseUrl": "https://gateway.open.umeng.com/openapi",
    "endpoint": "param2/1/com.umeng.uapp/umeng.uapp.getChannelData",
    "authType": "umeng-aksk"
  }
}' '{"appkey":"你的appkey","date":"2025-04-27","perPage":50,"page":1}'

返回格式：

{
  "channelInfos": [
    {
      "date": "2025-04-27",
      "channel": "Umeng",
      "id": "xxx",
      "activeUser": 311,
      "newUser": 15,
      "totalUser": 928529,
      "totalUserRate": 0.62,
      "launch": 2579,
      "duration": "xxx"
    }
  ],
  "totalPage": 3,
  "page": 1
}

返回字段说明：

2. 获取版本维度单日统计数据 (getVersionData)

获取指定 App 按照版本维度的单日统计数据。

参数说明：

> ⚠️ 本接口不支持分页参数（page / perPage），官方文档仅定义 appkey 与 date 两个必填。

调用示例：

umeng-cli call '{
  "name": "umeng.uapp.getVersionData",
  "api": {
    "method": "GET",
    "baseUrl": "https://gateway.open.umeng.com/openapi",
    "endpoint": "param2/1/com.umeng.uapp/umeng.uapp.getVersionData",
    "authType": "umeng-aksk"
  }
}' '{"appkey":"你的appkey","date":"2025-04-27"}'

返回格式：

{
  "versionInfos": [
    {
      "date": "2025-04-27",
      "version": "2.0.11001",
      "activeUser": 261,
      "newUser": 2,
      "totalUser": 306487,
      "totalUserRate": 0.18
    }
  ]
}

返回字段说明：

> ⚠️ 版本单日快照无启动次数：VersionInfo 结构中不含 launch / duration 字段（与 ChannelInfo 不同）。如需"按版本看启动趋势"，请改用 getLaunchesByChannelOrVersion + versions 参数。

3. 按渠道/版本获取启动次数趋势 (getLaunchesByChannelOrVersion)

获取指定 App 某个时间范围内按渠道或版本的启动次数。

参数说明：

调用示例：

# 示例 A：全渠道/全版本按日启动趋势
umeng-cli call '{
  "name": "umeng.uapp.getLaunchesByChannelOrVersion",
  "api": {
    "method": "GET",
    "baseUrl": "https://gateway.open.umeng.com/openapi",
    "endpoint": "param2/1/com.umeng.uapp/umeng.uapp.getLaunchesByChannelOrVersion",
    "authType": "umeng-aksk"
  }
}' '{"appkey":"你的appkey","startDate":"2025-04-21","endDate":"2025-04-27","periodType":"daily"}'

# 示例 B：查询 "App Store" 渠道近 7 天启动趋势（渠道名 urlEncode）
umeng-cli call '{
  "name": "umeng.uapp.getLaunchesByChannelOrVersion",
  "api": {
    "method": "GET",
    "baseUrl": "https://gateway.open.umeng.com/openapi",
    "endpoint": "param2/1/com.umeng.uapp/umeng.uapp.getLaunchesByChannelOrVersion",
    "authType": "umeng-aksk"
  }
}' '{"appkey":"你的appkey","startDate":"2025-04-21","endDate":"2025-04-27","periodType":"daily","channels":"App%20Store"}'

返回格式：

{
  "launchInfo": [
    {
      "date": "2025-04-21",
      "value": 2579,
      "dailyValue": [
        {"name": "App Store", "value": 1200}
      ],
      "hourValue": []
    }
  ]
}

返回字段说明：

4. 按渠道/版本获取活跃用户数趋势 (getActiveUsersByChannelOrVersion)

获取指定 App 某个时间范围内按渠道或版本的活跃用户数。

参数说明：

调用示例：

# 查询 "华为" 渠道近 7 天活跃用户趋势
umeng-cli call '{
  "name": "umeng.uapp.getActiveUsersByChannelOrVersion",
  "api": {
    "method": "GET",
    "baseUrl": "https://gateway.open.umeng.com/openapi",
    "endpoint": "param2/1/com.umeng.uapp/umeng.uapp.getActiveUsersByChannelOrVersion",
    "authType": "umeng-aksk"
  }
}' '{"appkey":"你的appkey","startDate":"2025-04-21","endDate":"2025-04-27","periodType":"daily","channels":"%E5%8D%8E%E4%B8%BA"}'

返回格式：

{
  "activeUserInfo": [
    {
      "date": "2025-04-21",
      "value": 0,
      "dailyValue": [
        {"name": "华为", "value": 311}
      ],
      "hourValue": []
    }
  ]
}

返回字段说明：

5. 按渠道/版本获取新增用户数趋势 (getNewUsersByChannelOrVersion)

获取指定 App 某个时间范围内按渠道或版本的新增用户数。

参数说明：

调用示例：

# 查询 3.5 版本近 30 天新增用户趋势
umeng-cli call '{
  "name": "umeng.uapp.getNewUsersByChannelOrVersion",
  "api": {
    "method": "GET",
    "baseUrl": "https://gateway.open.umeng.com/openapi",
    "endpoint": "param2/1/com.umeng.uapp/umeng.uapp.getNewUsersByChannelOrVersion",
    "authType": "umeng-aksk"
  }
}' '{"appkey":"你的appkey","startDate":"2025-03-29","endDate":"2025-04-27","periodType":"daily","versions":"3.5"}'

返回格式：

{
  "newUserInfo": [
    {
      "date": "2025-03-29",
      "value": 0,
      "dailyValue": [
        {"name": "3.5", "value": 15}
      ],
      "hourValue": []
    }
  ]
}

返回字段说明：

公共枚举与约束

periodType 枚举

> 对于三个 ByChannelOrVersion 趋势接口，periodType 官方标注为必填且默认 daily。实际调用中建议显式传入以避免歧义。

日期格式

• date / startDate / endDate 统一使用 yyyy-MM-dd
• "今日"数据请改用 umeng.uapp.getTodayData（不在本 Skill 范围内）

channels / versions 单值限制

• 三个趋势接口的 channels 与 versions 参数每次仅能传一个值
• 如需对比多个渠道/版本，需多次调用后由客户端聚合

urlEncode 规则

• 含空格、中文、特殊字符的渠道名/版本号需做 URL 编码（percent-encoding）
• 例：App Store → App%20Store；华为 → %E5%8D%8E%E4%B8%BA
• 纯英文字母/数字/点号（如 Umeng、3.5、1.0.0）无需编码
• 三个 ByChannelOrVersion 接口统一按此规则处理

分页

• getChannelData 支持 page（默认 1）+ perPage（默认 10，最大 100），响应含 totalPage
• getVersionData 不支持分页
• 三个趋势接口不支持分页

时间范围换算参考

典型工作流

场景 1：单日渠道 Top N 对比

需求："各渠道昨天的新增用户对比？"
1. getChannelData(appkey, date=yesterday, perPage=100)
   → 拿到当日所有渠道的 channelInfos[]
2. 客户端（LLM）按 newUser 字段降序排序
3. 取 Top N（默认 5），输出表格：排名 / 渠道 / 新增 / 活跃 / 启动 / 总用户

场景 2：单日版本表现

需求："各版本活跃用户排名？"
1. getVersionData(appkey, date=yesterday)
   → 拿到所有版本的 versionInfos[]
2. 客户端按 activeUser 降序排序，取 Top N
3. 提醒：版本维度单日快照无启动数；如需启动趋势请走场景 4

场景 3：某渠道近 7 日趋势

需求："华为渠道过去一周的活跃用户怎样？"
1. 计算 startDate = today - 7, endDate = yesterday
2. 渠道名 urlEncode：华为 → %E5%8D%8E%E4%B8%BA
3. getActiveUsersByChannelOrVersion(
     appkey, startDate, endDate, periodType=daily,
     channels="%E5%8D%8E%E4%B8%BA"
   )
4. 读取 activeUserInfo[].dailyValue[0].value（渠道日值），绘制/输出趋势
5. 如需同时看新增：再调 getNewUsersByChannelOrVersion（参数一致）
   如需启动：再调 getLaunchesByChannelOrVersion（参数一致）

场景 4：新版本上线后对比

需求："3.5 版本上线后用户表现如何？"
1. 确认上线日期 → 设置 startDate = 上线日, endDate = yesterday
2. getNewUsersByChannelOrVersion(
     appkey, startDate, endDate, periodType=daily, versions="3.5"
   )
   → 观察新增用户增长曲线
3. getActiveUsersByChannelOrVersion(... versions="3.5") → 观察活跃走势
4. getLaunchesByChannelOrVersion(... versions="3.5") → 观察启动走势
5. 横向对比上一版本（例如 versions="3.4"），评估升级迁移效果

边界条件与错误处理

• 未说 App 名 / appkey：先询问用户 appkey；若用户不知道，引导至友盟后台查询或调用 umeng.uapp.getAppList
• appkey 无效：响应非成功，提示「找不到该应用，请确认 appkey 是否正确或是否已开通 U-App」
• 渠道/版本名不存在：dailyValue 为空数组；建议先不加 channels/versions 查全量，再挑选实际存在的名称
• 返回数据为空：channelInfos / versionInfos 为空数组代表该日期暂无数据，提示「该日期暂无数据，建议换近期日期查询」
• 渠道/版本名含特殊字符忘记 urlEncode：可能返回空结果或签名错误，要求对参数值做 URL 编码
• 服务端无排序参数：5 个接口均不提供 sort-by / top，排序与 Top N 由客户端完成
• channels / versions 传多个值：接口仅接受单个值，多值请分多次调用
• 日期跨度过大：服务端对返回数量有上限，如有限制按官方文档分段查询
• 未登录 / 登录态过期：执行 umeng-cli login --no-qr（AI Agent 以后台模式运行并将链接展示给用户）

典型问法 → 接口/参数映射

注意事项

• 本 Skill 仅限只读查询，不包含 umeng.uapp.createApp / umeng.uapp.event.create 等写入类接口
• 所有接口均为 GET 方法
• appkey 到友盟官网 https://www.umeng.com/ 应用管理后台查询
• total_user（总用户数）指标：仅在"单日快照"场景下由 getChannelData / getVersionData 响应直接提供；无独立的 total_user 趋势接口，如需趋势请拼接多日快照
• 版本维度单日快照无 launch 字段：VersionInfo 结构不含启动数；想看"某版本启动趋势"请走 getLaunchesByChannelOrVersion + versions 参数
• 服务端无排序参数：排序与 Top N 由客户端完成
• channels / versions 仅一个：多个对比需多次调用
• urlEncode：含空格/中文/特殊字符的渠道与版本名需要 URL 编码
• getVersionData 不支持分页（仅 appkey + date）；getChannelData 支持 page/perPage（最大 100）

快速参考

> 完整 uapp namespace 其他接口（如 getDailyData / getYesterdayData / getRetentions / event.* 等）请参考 umeng-cli/reference/openapi/uapp.md。