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

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

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

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

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

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

获取路径：

直接要求用户提供 appkey
若用户不知道，引导至友盟官网 https://www.umeng.com/ 登录后在应用管理后台复制
（进阶）可调用同 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.list 响应的 name 字段，或用户直接提供 | event.getData / event.getUniqueUsers / event.param.getValueList / event.param.getData / event.param.getValueDurationList（5 个） | | eventId | 事件的内部 ID（字符串） | 必须先调 event.list，读响应的 id 字段 | 仅 event.param.list 一个接口 | | displayName | 事件中文显示名（后台编辑） | event.list 响应的 displayName 字段 | 仅用于客户端过滤匹配，接口请求体不传 |

⚠️ 不要把 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 个）

| 接口 | Endpoint | 功能 | |------|----------|------| | umeng.uapp.event.list | param2/1/com.umeng.uapp/umeng.uapp.event.list | 事件列表（唯一支持分页：page / perPage，可选 version 过滤） | | umeng.uapp.event.getData | param2/1/com.umeng.uapp/umeng.uapp.event.getData | 事件触发次数日趋势 | | umeng.uapp.event.getUniqueUsers | param2/1/com.umeng.uapp/umeng.uapp.event.getUniqueUsers | 事件独立用户数日趋势（按 device 去重） | | umeng.uapp.event.param.list | param2/1/com.umeng.uapp/umeng.uapp.event.param.list | 事件参数列表（必填 eventId） |

参数值级（3 个）

| 接口 | Endpoint | 功能 | |------|----------|------| | umeng.uapp.event.param.getValueList | param2/1/com.umeng.uapp/umeng.uapp.event.param.getValueList | 参数值取值分布（name / count / percent） | | umeng.uapp.event.param.getData | param2/1/com.umeng.uapp/umeng.uapp.event.param.getData | 指定参数值的次数日趋势 | | umeng.uapp.event.param.getValueDurationList | param2/1/com.umeng.uapp/umeng.uapp.event.param.getValueDurationList | 参数值使用时长分布（仅数值型/计算事件） |

关键差异说明

| 特性 | 本 Skill 7 个接口 | |------|-------------------| | 分页 page/perPage | 仅 event.list 支持，其余 6 个均不支持 | | 趋势聚合 periodType（daily/weekly/monthly/7day/30day） | 7 个接口全部不支持（与 umeng-cli-uapp-core-index / umeng-cli-uapp-channel-version 的 By* 趋势接口不同，本 Skill 只按每日粒度返回） | | channel 过滤 | 均不支持（如需渠道维度请用 umeng-cli-uapp-channel-version） | | version 过滤 | 仅 event.list 支持 |

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

操作

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

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

参数说明：

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | appkey | string | 是 | - | 应用 ID | | startDate | string | 是 | - | 起始日期 yyyy-MM-dd | | endDate | string | 是 | - | 截止日期 yyyy-MM-dd | | perPage | integer | 否 | 10 | 每页数量，最大 100 | | page | integer | 否 | 1 | 页码（从 1 开始） | | version | string | 否 | - | 应用版本号（仅一个，含特殊字符需 urlEncode） |

调用示例：

# 拉第一页（默认 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
}

返回字段说明：

| 字段 | 类型 | 说明 | |------|------|------| | eventInfo[].name | string | 事件英文名（即 eventName，用于其余 5 个事件接口） | | eventInfo[].displayName | string | 事件中文显示名（后台编辑，可用于通过中文名反查） | | eventInfo[].count | integer | 时间范围内的累计触发次数 | | eventInfo[].id | string | 事件 ID（即 eventId，event.param.list 的必填参数） | | page | integer | 当前页码 | | totalPage | integer | 总页数 |

💡 "全部事件"语义：若用户要求列出全部事件，读取响应的 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]
    }
  ]
}

返回字段说明：

| 字段 | 类型 | 说明 | |------|------|------| | eventData[].dates[] | string[] | 统计日期数组（按日粒度） | | eventData[].data[] | integer[] | 对应日期的触发次数数组 |

⚠️ 无 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 获得。

参数说明：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | appkey | string | 是 | 应用 ID | | startDate | string | 是 | 起始日期 yyyy-MM-dd | | endDate | string | 是 | 截止日期 yyyy-MM-dd | | eventId | string | 是 | 事件 ID（通过 event.list 响应的 id 字段获取） |

调用示例：

# 先通过 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": "来源渠道"
    }
  ]
}

返回字段说明：

| 字段 | 类型 | 说明 | |------|------|------| | paramInfos[].paramId | string | 参数 ID（当前 namespace 参数值相关接口不要求传，仅识别用） | | paramInfos[].name | string | 参数英文名（即 eventParamName，用于参数值相关 3 个接口） | | paramInfos[].displayName | string | 参数中文显示名 |

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

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

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

参数说明：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | appkey | string | 是 | 应用 ID | | startDate | string | 是 | 起始日期 yyyy-MM-dd | | endDate | string | 是 | 截止日期 yyyy-MM-dd | | eventName | string | 是 | 事件英文名 | | eventParamName | string | 是 | 参数英文名（通过 event.param.list 的 name 获取） |

调用示例：

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}
  ]
}

返回字段说明：

| 字段 | 类型 | 说明 | |------|------|------| | paramInfos[].name | string | 参数取值（即 paramValueName，用于 event.param.getData）；中文值在响应中通常以 percent-encoded 形式返回，需客户端解码后展示 | | paramInfos[].count | integer | 该取值的触发次数 | | paramInfos[].percent | double | 该取值占该参数的比例（0~1） |

💡 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。

参数说明：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | appkey | string | 是 | 应用 ID | | startDate | string | 是 | 起始日期 yyyy-MM-dd | | endDate | string | 是 | 截止日期 yyyy-MM-dd | | eventName | string | 是 | 事件英文名（应为数值型/计算事件） | | eventParamName | string | 是 | 参数英文名 |

调用示例：

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 支持）

| 接口 | 支持分页 | 默认值 | 上限 | |------|:---:|-------|------| | event.list | ✅ | page=1 / perPage=10 | perPage 最大 100 | | 其余 6 个接口 | ❌ | — | — |

无 periodType（本 Skill 专门差异点）

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

| Skill / 接口 | 是否支持 periodType | |------|:---:| | 本 Skill 的 event.getData / event.getUniqueUsers / event.param.getData | ❌（仅按日粒度返回） | | umeng-cli-uapp-core-index 的 getActiveUsers / getNewUsers / getLaunches | ✅ | | umeng-cli-uapp-channel-version 的 *ByChannelOrVersion | ✅ |

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

eventId vs eventName 路由

| 用户说的"事件" | 需要传入 | 获取路径 | |----------------|----------|----------| | 英文事件名（埋点 key） | eventName → 5 个接口 | 用户提供 / event.list.eventInfo[].name | | 中文显示名 | 先映射到英文事件名 | event.list.eventInfo[].displayName 客户端匹配 | | 事件 ID | eventId → 仅 event.param.list | 必须 event.list.eventInfo[].id |

urlEncode 规则

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

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

示例：

| 原值 | 编码后 | |------|--------| | App Store | App%20Store | | 华为 | %E5%8D%8E%E4%B8%BA | | 首页 | %E9%A6%96%E9%A1%B5 | | 示例 | %E7%A4%BA%E4%BE%8B（官方响应示例即此形） |

纯英文字母 / 数字 / 点号（如 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 以后台模式运行并将链接展示给用户）

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

| 典型问法 | 接口 | 关键参数 | |----------|------|----------| | "某 App 有哪些自定义事件？" | event.list | appkey + startDate + endDate | | "事件 xxx 存在吗？" | event.list + 客户端过滤 | 按 name 匹配 | | "显示名为 '开始' 的事件存在吗？" | event.list + 客户端过滤 | 按 displayName 匹配 | | "列出全部事件" | event.list 循环 | perPage=100 + page=1..totalPage | | "过去 7 天 xxx 事件触发了多少次？" | event.getData | 近 7 天 + eventName | | "过去 7 天 xxx 事件有多少独立用户？" | event.getUniqueUsers | 近 7 天 + eventName | | "xxx 事件综合统计" | 并行 event.getData + event.getUniqueUsers | 同上 | | "xxx 事件有哪些参数？" | event.list 取 id → event.param.list | eventId | | "xxx 事件的 yyy 参数取值分布？" | event.param.getValueList | eventName + eventParamName | | "xxx 事件 yyy=login 过去 30 天趋势？" | event.param.getData | eventName + eventParamName + paramValueName | | "数值事件 zzz 的参数值时长分布？" | event.param.getValueDurationList | eventName + eventParamName |

旧 skill 参数等价对照

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

| 旧 CLI 参数组合 | 新接口调用 | |-----------------|------------| | --list-events | event.list，默认 page=1 / perPage=10 | | --list-events --page 2 --per-page 50 | event.list + page=2 + perPage=50 | | --list-events --all | event.list 循环 page=1..totalPage（perPage=100） | | --check-event NAME | event.list + 客户端按 name 匹配 | | --check-display "中文" | event.list + 客户端按 displayName 匹配 | | --query EVENT --metric count | event.getData | | --query EVENT --metric unique_users | event.getUniqueUsers | | --query EVENT --metric all | 并行 event.getData + event.getUniqueUsers | | --list-params EVENT | event.list 取 id → event.param.list | | --query EVENT --param PARAM | event.param.getValueList | | --query EVENT --param PARAM --param-value VALUE | event.param.getData | | --query EVENT --param PARAM --param-metric duration | event.param.getValueDurationList（仅数值型事件） | | --range last_7_days | 客户端计算 startDate / endDate | | --app NAME → appkey 解析 | 用户直接给 appkey，或 umeng.uapp.getAppList 解析 |

注意事项

本 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 排序后截断
今日数据延迟：事件数据一般次日完整，建议查询"昨日及以前"

快速参考

| # | 接口 | Endpoint（相对 baseUrl） | 必填参数 | 可选参数 | 维度 | |---|------|--------------------------|----------|----------|------| | 1 | umeng.uapp.event.list | param2/1/com.umeng.uapp/umeng.uapp.event.list | appkey + startDate + endDate | perPage（≤100） / page / version | 事件清单（唯一支持分页） | | 2 | umeng.uapp.event.getData | param2/1/com.umeng.uapp/umeng.uapp.event.getData | appkey + startDate + endDate + eventName | — | 事件次数日趋势 | | 3 | umeng.uapp.event.getUniqueUsers | param2/1/com.umeng.uapp/umeng.uapp.event.getUniqueUsers | appkey + startDate + endDate + eventName | — | 事件独立用户日趋势 | | 4 | umeng.uapp.event.param.list | param2/1/com.umeng.uapp/umeng.uapp.event.param.list | appkey + startDate + endDate + eventId | — | 事件参数清单 | | 5 | umeng.uapp.event.param.getValueList | param2/1/com.umeng.uapp/umeng.uapp.event.param.getValueList | appkey + startDate + endDate + eventName + eventParamName | — | 参数值分布 | | 6 | umeng.uapp.event.param.getData | param2/1/com.umeng.uapp/umeng.uapp.event.param.getData | appkey + startDate + endDate + eventName + eventParamName + paramValueName | — | 指定参数值日趋势 | | 7 | umeng.uapp.event.param.getValueDurationList | param2/1/com.umeng.uapp/umeng.uapp.event.param.getValueDurationList | appkey + startDate + endDate + eventName + eventParamName | — | 参数值时长分布（数值型事件） |

完整 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。

友盟自定义事件数据查询

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

前置条件：安装 umeng-cli

检查是否已安装

安装方式

适用场景与触发词

鉴权方式

登录状态检查

登录要求

获取 appkey

通用调用格式

关键概念

eventId vs eventName

参数三层结构

接口路由表

事件级（4 个）

参数值级（3 个）

关键差异说明

操作

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

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

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

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

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

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

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

公共枚举与约束

日期格式

分页（仅 event.list 支持）

无 periodType（本 Skill 专门差异点）

eventId vs eventName 路由

urlEncode 规则

返回数据为空的常见原因

典型工作流

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

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

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

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

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

边界条件与错误处理

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

旧 skill 参数等价对照

注意事项

快速参考