友盟 U-App 自定义事件查询技能

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

查询友盟 U-App（移动统计）的自定义事件（埋点）数据，覆盖四大场景：

• 事件清单：列出 App 下所有自定义事件、确认某事件名 / 显示名是否存在
• 事件指标：某事件在时间范围内的触发次数趋势、独立用户数趋势（按 device 去重）
• 参数分析：事件的参数列表、某参数的取值分布、某具体参数值的时间趋势
• 参数时长：数值型（计算）事件某参数值的使用时长分布

共 7 个只读查询接口（严格排除写入型 event.create，后者由 uapp-event-manage 负责）。

> 埋点上报： AI Agent 在阅读本 Skill 文档后，请执行以下命令进行调用埋点上报：
> bash > umeng-cli trace '{"skill_name":"umeng-cli-uapp-event"}' >
>
> Appkey 维度打点： 当本轮任务中出现 Appkey 的输入操作时，在拿到该 Appkey 之后、发起首个业务 API 调用之前，再追加执行一次带 appkey 的打点：
> bash > umeng-cli trace '{"skill_name":"umeng-cli-uapp-event", "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

适用场景与触发词

• 用户询问某 App 有哪些自定义事件 / 埋点
• 用户询问某事件（按事件名 / 中文显示名）是否存在
• 用户询问某事件过去 N 天的触发次数、独立用户数
• 用户询问某事件的参数有哪些、某参数的取值分布 Top 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

本 Skill 的 7 个接口均以 appkey 作为应用维度标识（无账户级接口）。

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

通用调用格式

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

• 本 Skill 的 7 个接口均为 GET 方法
• endpoint 路径遵循统一格式 param2/1/com.umeng.uapp/<接口名>
• 所有接口均需 appkey（没有像 getAllAppData 那样的账户级接口）

关键概念

eventId vs eventName

> ⚠️ 不要把 eventName 传给 event.param.list：该接口的必填参数是 eventId，必须先通过 event.list 把用户给的 eventName / displayName 解析为 id，再调用参数列表接口。

参数三层结构

一个事件下的参数分析遵循三层漏斗：

事件（eventName）
  └── 参数（eventParamName）  ← event.param.list 给出
        └── 参数取值（paramValueName）  ← event.param.getValueList 给出

• event.param.list 输入 eventId，输出参数清单（paramId / name / displayName）
• event.param.getValueList 输入 eventName + eventParamName，输出取值分布（name / count / percent）
• event.param.getData 输入 eventName + eventParamName + paramValueName，输出指定取值的日趋势
• event.param.getValueDurationList 输入 eventName + eventParamName，输出时长分布（仅数值型事件有效）

接口路由表

事件级（4 个）

参数值级（3 个）

关键差异说明

> 💡 排序与 Top N 由客户端完成：本 Skill 所有接口均不提供服务端排序参数；参数取值分布等 Top N 场景由客户端（LLM 侧）在响应数据上排序截断。

操作

1. 获取事件列表 (event.list)

分页获取指定 App 在时间范围内的自定义事件清单，本 Skill 唯一支持 page / perPage 的接口，也可用 version 过滤。

参数说明：

调用示例：

# 拉第一页（默认 perPage=10）
umeng-cli call '{
  "name": "umeng.uapp.event.list",
  "api": {
    "method": "GET",
    "baseUrl": "https://gateway.open.umeng.com/openapi",
    "endpoint": "param2/1/com.umeng.uapp/umeng.uapp.event.list",
    "authType": "umeng-aksk"
  }
}' '{"appkey":"你的appkey","startDate":"2026-04-21","endDate":"2026-04-27"}'

# 每页 100 条，拉第 2 页
umeng-cli call '{"name":"umeng.uapp.event.list","api":{"method":"GET","baseUrl":"https://gateway.open.umeng.com/openapi","endpoint":"param2/1/com.umeng.uapp/umeng.uapp.event.list","authType":"umeng-aksk"}}' '{"appkey":"你的appkey","startDate":"2026-04-21","endDate":"2026-04-27","perPage":100,"page":2}'

# 过滤指定版本
umeng-cli call '{"name":"umeng.uapp.event.list","api":{"method":"GET","baseUrl":"https://gateway.open.umeng.com/openapi","endpoint":"param2/1/com.umeng.uapp/umeng.uapp.event.list","authType":"umeng-aksk"}}' '{"appkey":"你的appkey","startDate":"2026-04-21","endDate":"2026-04-27","version":"1.0.0"}'

返回格式：

{
  "eventInfo": [
    {
      "name": "click_button",
      "displayName": "按钮点击",
      "count": 12800,
      "id": "a1b2c3d4"
    }
  ],
  "page": 1,
  "totalPage": 3
}

返回字段说明：

> 💡 "全部事件"语义：若用户要求列出全部事件，读取响应的 totalPage，循环 page=1..totalPage、每页 perPage=100 拉取后在客户端合并去重。

2. 获取事件触发次数趋势 (event.getData)

获取指定事件在时间范围内的每日触发次数。

参数说明：

调用示例：

umeng-cli call '{
  "name": "umeng.uapp.event.getData",
  "api": {
    "method": "GET",
    "baseUrl": "https://gateway.open.umeng.com/openapi",
    "endpoint": "param2/1/com.umeng.uapp/umeng.uapp.event.getData",
    "authType": "umeng-aksk"
  }
}' '{"appkey":"你的appkey","startDate":"2026-04-21","endDate":"2026-04-27","eventName":"click_button"}'

返回格式：

{
  "eventData": [
    {
      "dates": ["2026-04-21", "2026-04-22", "2026-04-23"],
      "data": [1280, 1360, 1420]
    }
  ]
}

返回字段说明：

> ⚠️ 无 periodType：本接口仅按日返回，不支持 weekly / monthly / 7day / 30day。若用户需要周/月聚合，在客户端对 data[] 求和。

3. 获取事件独立用户数趋势 (event.getUniqueUsers)

获取指定事件在时间范围内的每日独立用户数（按 device 去重）。

参数说明：

调用示例：

umeng-cli call '{
  "name": "umeng.uapp.event.getUniqueUsers",
  "api": {
    "method": "GET",
    "baseUrl": "https://gateway.open.umeng.com/openapi",
    "endpoint": "param2/1/com.umeng.uapp/umeng.uapp.event.getUniqueUsers",
    "authType": "umeng-aksk"
  }
}' '{"appkey":"你的appkey","startDate":"2026-04-21","endDate":"2026-04-27","eventName":"click_button"}'

返回格式：

{
  "uniqueUsers": [
    {
      "dates": ["2026-04-21", "2026-04-22", "2026-04-23"],
      "data": [820, 860, 905]
    }
  ]
}

返回字段说明：结构与 event.getData 一致，外层 key 为 uniqueUsers；语义由"次数"变为"去重设备数"。

> 💡 次数 vs 独立用户：同一用户在一天内多次触发某事件，在 event.getData 中计为多次，在 event.getUniqueUsers 中仅计为 1。要综合看两个指标时，对相同日期区间并行调用二者。

4. 获取事件参数列表 (event.param.list)

获取指定事件的参数清单。必填 eventId（不是 eventName），需要先从 event.list 获得。

参数说明：

调用示例：

# 先通过 event.list 拿到 id，再调本接口
umeng-cli call '{
  "name": "umeng.uapp.event.param.list",
  "api": {
    "method": "GET",
    "baseUrl": "https://gateway.open.umeng.com/openapi",
    "endpoint": "param2/1/com.umeng.uapp/umeng.uapp.event.param.list",
    "authType": "umeng-aksk"
  }
}' '{"appkey":"你的appkey","startDate":"2026-04-21","endDate":"2026-04-27","eventId":"a1b2c3d4"}'

返回格式：

{
  "paramInfos": [
    {
      "paramId": "p001",
      "name": "button_id",
      "displayName": "按钮 ID"
    },
    {
      "paramId": "p002",
      "name": "channel",
      "displayName": "来源渠道"
    }
  ]
}

返回字段说明：

> ⚠️ 常见错误：把用户给的 eventName 直接传到 eventId 参数位置，会导致空结果或错误。务必先走 event.list 换取 id。

5. 获取参数取值分布 (event.param.getValueList)

获取指定事件某个参数的取值分布（每个不同取值的次数与占比）。

参数说明：

调用示例：

umeng-cli call '{
  "name": "umeng.uapp.event.param.getValueList",
  "api": {
    "method": "GET",
    "baseUrl": "https://gateway.open.umeng.com/openapi",
    "endpoint": "param2/1/com.umeng.uapp/umeng.uapp.event.param.getValueList",
    "authType": "umeng-aksk"
  }
}' '{"appkey":"你的appkey","startDate":"2026-04-21","endDate":"2026-04-27","eventName":"click_button","eventParamName":"button_id"}'

返回格式：

{
  "paramInfos": [
    {"name": "login",     "count": 5800, "percent": 0.42},
    {"name": "register",  "count": 3100, "percent": 0.23},
    {"name": "%E9%A6%96%E9%A1%B5", "count": 2400, "percent": 0.18}
  ]
}

返回字段说明：

> 💡 Top N 排序：接口不保证按 count 降序，客户端按 count 或 percent 降序后取 Top N。

6. 获取指定参数值的次数趋势 (event.param.getData)

获取"某事件 + 某参数 + 某取值"这一组合的每日触发次数趋势。

参数说明：

调用示例：

# 英文取值
umeng-cli call '{
  "name": "umeng.uapp.event.param.getData",
  "api": {
    "method": "GET",
    "baseUrl": "https://gateway.open.umeng.com/openapi",
    "endpoint": "param2/1/com.umeng.uapp/umeng.uapp.event.param.getData",
    "authType": "umeng-aksk"
  }
}' '{"appkey":"你的appkey","startDate":"2026-04-21","endDate":"2026-04-27","eventName":"click_button","eventParamName":"button_id","paramValueName":"login"}'

# 含中文/空格的取值需要 urlEncode
umeng-cli call '{"name":"umeng.uapp.event.param.getData","api":{"method":"GET","baseUrl":"https://gateway.open.umeng.com/openapi","endpoint":"param2/1/com.umeng.uapp/umeng.uapp.event.param.getData","authType":"umeng-aksk"}}' '{"appkey":"你的appkey","startDate":"2026-04-21","endDate":"2026-04-27","eventName":"click_button","eventParamName":"button_id","paramValueName":"%E9%A6%96%E9%A1%B5"}'

返回格式：

{
  "paramValueData": [
    {
      "dates": ["2026-04-21", "2026-04-22", "2026-04-23"],
      "data": [520, 580, 640]
    }
  ]
}

返回字段说明：结构与 event.getData 一致，外层 key 为 paramValueData。

7. 获取参数值时长分布 (event.param.getValueDurationList)

获取数值型（计算）事件指定参数的时长分布。仅对数值型事件返回有效数据，计数型事件调用将返回空或 0。

参数说明：

调用示例：

umeng-cli call '{
  "name": "umeng.uapp.event.param.getValueDurationList",
  "api": {
    "method": "GET",
    "baseUrl": "https://gateway.open.umeng.com/openapi",
    "endpoint": "param2/1/com.umeng.uapp/umeng.uapp.event.param.getValueDurationList",
    "authType": "umeng-aksk"
  }
}' '{"appkey":"你的appkey","startDate":"2026-04-21","endDate":"2026-04-27","eventName":"play_video","eventParamName":"video_id"}'

返回格式：

{
  "paramInfos": [
    {"name": "video_001", "count": 1820, "percent": 0.48},
    {"name": "video_002", "count": 1100, "percent": 0.29}
  ]
}

返回字段说明：结构与 event.param.getValueList 一致（ParamValueInfo[]），语义改为"时长"而非"次数"。

> ⚠️ 仅数值型事件有效：若调用后返回空数组或全 0，通常说明该事件是计数型（非计算/数值型），应改用 event.param.getValueList 查询次数分布。

公共枚举与约束

日期格式

• startDate / endDate 统一使用 yyyy-MM-dd
• 今日数据有延迟，建议查询"昨日及以前"
• 事件数据一般次日完整

分页（仅 event.list 支持）

无 periodType（本 Skill 专门差异点）

本 Skill 的 7 个接口全部不支持 periodType。与 umeng-cli-uapp-core-index / umeng-cli-uapp-channel-version 的趋势类接口不同：

> 用户如需"按周"/"按月"聚合事件数据，请在客户端对 data[] 做分组求和。

eventId vs eventName 路由

urlEncode 规则

以下场景需要对值做 URL 编码（percent-encoding）：

• version（含空格/中文/特殊字符时）
• paramValueName（参数取值含空格/中文）
• 部分返回值（如 paramInfos[].name）本身是 percent-encoded，展示前需解码

示例：

纯英文字母 / 数字 / 点号（如 login / 1.0.0 / video_001）无需编码。

返回数据为空的常见原因

• 该事件/参数/取值在时间范围内无上报
• 事件名拼写错误 / 大小写不匹配
• 时间范围含今日（数据延迟）
• event.param.list 传了 eventName 而非 eventId
• event.param.getValueDurationList 用在了计数型事件上

典型工作流

工作流 1：事件存在性检查（按事件名 / 显示名）

需求："事件 click_button 存在吗？" / "显示名为'按钮点击'的事件存在吗？"
1. event.list(appkey, startDate, endDate, perPage=100, page=1)
2. 若 totalPage > 1，循环拉取后续页合并 eventInfo
3. 客户端遍历 eventInfo：
   - 按事件名：匹配 name（支持忽略大小写）
   - 按显示名：匹配 displayName
4. 命中 → 返回 "存在" + 关键字段（name / displayName / count / id）
   未命中 → 返回 "不存在，可用 uapp-event-manage 创建"

工作流 2：事件综合统计（次数 + 独立用户）

需求："事件 click_button 过去 7 天表现如何？"
1. 计算 startDate = today - 7, endDate = yesterday
2. 并行调用：
   - event.getData(appkey, startDate, endDate, eventName=click_button)
   - event.getUniqueUsers(appkey, startDate, endDate, eventName=click_button)
3. 对齐 dates[]，同时展示 next/unique 两条曲线
4. 总结：总触发次数 / 日均独立用户 / 高点低点、人均触发次数（= 总次数 / 独立用户）

工作流 3：事件参数列表（必经 eventId 解析）

需求："事件 click_button 有哪些参数？"
1. event.list(appkey, startDate, endDate, perPage=100)
2. 客户端定位 eventInfo[i].name === "click_button"，取 eventInfo[i].id
3. event.param.list(appkey, startDate, endDate, eventId=<上一步 id>)
4. 列出 paramInfos[]：name / displayName（供后续 eventParamName 使用）

工作流 4：参数取值分布 Top N

需求："事件 click_button 的 button_id 取值 Top 5？"
1. event.param.getValueList(appkey, startDate, endDate, eventName=click_button, eventParamName=button_id)
2. 客户端按 count 降序取前 5
3. 展示 name / count / percent（对 percent-encoded 的 name 先解码）
4. 若用户问"占比最高的取值"，直接返回 Top 1

工作流 5：特定参数值的时间趋势

需求："事件 click_button 的 button_id=login 过去 30 天趋势？"
1. （可选）先走工作流 4 确认 login 是有效取值
2. 计算 startDate / endDate
3. event.param.getData(appkey, startDate, endDate, eventName=click_button, eventParamName=button_id, paramValueName=login)
   - 若 paramValueName 含中文 / 空格先 urlEncode
4. 读取 paramValueData[].dates 与 data，输出日趋势

边界条件与错误处理

• 未说 appkey：先询问用户 appkey；若用户不知道，引导至友盟后台查询或用 umeng.uapp.getAppList
• appkey 无效：响应非成功，提示「找不到该应用，请确认 appkey 是否正确或是否已开通 U-App」
• 未说 App 名：先询问，不要猜测；App 名无法匹配时提示「可用 uapp-assets 查询应用列表」
• 事件名不确定：先用 event.list 查询清单，或用显示名（displayName）客户端反查
• 事件不存在：提示「该事件不存在，可用 uapp-event-manage 创建」（本 Skill 仅查询）
• 返回数据为空：
• 时间范围含今日 → 改为昨日及以前
• 事件拼写 → 在 event.list 中确认 name
• event.param.list 无返回 → 检查是否传成了 eventName（应传 eventId）
• event.param.getValueDurationList 返回空/0：该事件可能是计数型而非数值型（计算）事件，改用 event.param.getValueList
• 中文参数值查询失败：检查 paramValueName 是否做了 urlEncode
• 跨大时间范围事件列表拉取缓慢：分页拉取，perPage=100 配合 page=1..totalPage
• 未登录 / 登录态过期：执行 umeng-cli login --no-qr（AI Agent 以后台模式运行并将链接展示给用户）

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

旧 skill 参数等价对照

旧 uapp-event 的自定义参数与新接口的等价关系：

注意事项

• 本 Skill 仅限只读查询，不包含 umeng.uapp.event.create 等写入接口；事件创建/管理请用 uapp-event-manage
• 所有 7 个接口均为 GET 方法
• appkey 到友盟官网 https://www.umeng.com/ 应用管理后台查询
• eventId vs eventName：event.param.list 必填 eventId，其余 5 个事件/参数接口使用 eventName
• 分页：仅 event.list 支持 page / perPage（最大 100），其余 6 个均不支持
• 无 periodType：本 Skill 全部 7 个接口均不支持 periodType，仅按日粒度返回；周/月聚合由客户端完成
• 独立用户语义：event.getUniqueUsers 按 device 去重，同一用户同日多次触发只计 1 次
• 参数值 urlEncode：paramValueName 含空格/中文必须做 URL 编码；响应中的 paramInfos[].name 亦可能是 percent-encoded，展示前需解码
• 数值事件专属：event.param.getValueDurationList 仅对"计算/数值型事件"返回有效时长，计数型事件返回空/0
• 排序与 Top N：所有分布类接口不提供服务端排序，客户端按 count / percent 排序后截断
• 今日数据延迟：事件数据一般次日完整，建议查询"昨日及以前"

快速参考

> 完整 uapp namespace 其他接口（如 getAllAppData / getDailyData / event.create 等）请参考 umeng-cli/reference/openapi/uapp.md。
> 事件创建 / 管理请使用 uapp-event-manage；核心指标查询请使用 umeng-cli-uapp-core-index；渠道/版本维度请使用 umeng-cli-uapp-channel-version。