友盟 U-App 留存率查询技能

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

查询友盟 U-App（移动统计）的新增/活跃用户留存率，覆盖两类核心需求：

• 留存趋势：某 App 在时间范围内每日新增/活跃用户的次日、3日、7日、14日、30日留存率
• 维度对比：按版本或渠道过滤单维度留存；多版本/多渠道对比由客户端循环调用

共 1 个只读查询接口（umeng.uapp.getRetentions）。版本列表 / 渠道列表的枚举能力由 umeng-cli-uapp-channel-version 提供，本 Skill 不重复收纳。

> 埋点上报： AI Agent 在阅读本 Skill 文档后，请执行以下命令进行调用埋点上报：
> bash > umeng-cli trace '{"skill_name":"umeng-cli-uapp-retention"}' >
>
> Appkey 维度打点： 当本轮任务中出现 Appkey 的输入操作时，在拿到该 Appkey 之后、发起首个业务 API 调用之前，再追加执行一次带 appkey 的打点：
> bash > umeng-cli trace '{"skill_name":"umeng-cli-uapp-retention", "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 某时间段的次日/3日/7日/14日/30日留存率
• 用户询问某版本或某渠道的留存表现
• 用户请求多版本或多渠道的留存对比
• 用户询问活跃用户留存（非默认的新增用户留存）
• 关键词：留存、留存率、次日留存、7日留存、30日留存、留存趋势、版本留存、渠道留存、新增用户留存、活跃用户留存

鉴权方式

• 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 的 1 个接口以 appkey 作为应用维度标识。

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

通用调用格式

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

• 本 Skill 的接口为 GET 方法
• endpoint 路径遵循统一格式 param2/1/com.umeng.uapp/<接口名>
• 所有请求均需 appkey

核心概念

retentionRate 数组索引表（本 Skill 文档核心）

umeng.uapp.getRetentions 的响应 retentionInfo[].retentionRate 是一个定长数组，每个元素分别对应不同的留存窗口（从安装/活跃之日向后的若干天）。索引映射如下：

> ⚠️ 索引不是接口参数：想看哪个留存窗口，是客户端后处理（对 retentionRate[i] 取值），不是通过请求参数过滤。一次调用返回所有 5 个窗口的留存值。

提取示例（jq / LLM 侧）：

# 取每日的次日留存
jq '.retentionInfo[] | {date, d1: .retentionRate[0]}'

# 取每日的 7 日留存
jq '.retentionInfo[] | {date, d7: .retentionRate[2]}'

# 同时拉出 1/7/30 日
jq '.retentionInfo[] | {date, d1: .retentionRate[0], d7: .retentionRate[2], d30: .retentionRate[4]}'

type = newUser vs activeUser

> ⚠️ totalInstallUser 语义恒定：无论 type 为 newUser 还是 activeUser，totalInstallUser 字段始终为「当日安装/新增用户数」。若要分析"活跃基数"，请使用 umeng-cli-uapp-core-index 的 getActiveUsers 接口。

接口路由表

与本 skill 相邻能力的边界

操作

获取 App 留存率 (getRetentions)

获取指定 App 在时间范围内的新增/活跃用户留存率，一次返回次日/3日/7日/14日/30日 5 个窗口的留存值。

参数说明：

调用示例：

# 基础：过去 7 天的新增用户留存（默认 daily 聚合）
umeng-cli call '{
  "name": "umeng.uapp.getRetentions",
  "api": {
    "method": "GET",
    "baseUrl": "https://gateway.open.umeng.com/openapi",
    "endpoint": "param2/1/com.umeng.uapp/umeng.uapp.getRetentions",
    "authType": "umeng-aksk"
  }
}' '{"appkey":"你的appkey","startDate":"2026-04-21","endDate":"2026-04-27"}'

# 活跃用户留存
umeng-cli call '{"name":"umeng.uapp.getRetentions","api":{"method":"GET","baseUrl":"https://gateway.open.umeng.com/openapi","endpoint":"param2/1/com.umeng.uapp/umeng.uapp.getRetentions","authType":"umeng-aksk"}}' '{"appkey":"你的appkey","startDate":"2026-04-21","endDate":"2026-04-27","type":"activeUser"}'

# 按版本过滤（版本号为纯数字 / 点号时无需编码）
umeng-cli call '{"name":"umeng.uapp.getRetentions","api":{"method":"GET","baseUrl":"https://gateway.open.umeng.com/openapi","endpoint":"param2/1/com.umeng.uapp/umeng.uapp.getRetentions","authType":"umeng-aksk"}}' '{"appkey":"你的appkey","startDate":"2026-04-21","endDate":"2026-04-27","version":"2.0.11001"}'

# 按渠道过滤（"App Store" 含空格，必须 urlEncode）
umeng-cli call '{"name":"umeng.uapp.getRetentions","api":{"method":"GET","baseUrl":"https://gateway.open.umeng.com/openapi","endpoint":"param2/1/com.umeng.uapp/umeng.uapp.getRetentions","authType":"umeng-aksk"}}' '{"appkey":"你的appkey","startDate":"2026-04-21","endDate":"2026-04-27","channel":"App%20Store"}'

# 按周聚合
umeng-cli call '{"name":"umeng.uapp.getRetentions","api":{"method":"GET","baseUrl":"https://gateway.open.umeng.com/openapi","endpoint":"param2/1/com.umeng.uapp/umeng.uapp.getRetentions","authType":"umeng-aksk"}}' '{"appkey":"你的appkey","startDate":"2026-02-01","endDate":"2026-04-27","periodType":"weekly"}'

# 中文渠道（华为）
umeng-cli call '{"name":"umeng.uapp.getRetentions","api":{"method":"GET","baseUrl":"https://gateway.open.umeng.com/openapi","endpoint":"param2/1/com.umeng.uapp/umeng.uapp.getRetentions","authType":"umeng-aksk"}}' '{"appkey":"你的appkey","startDate":"2026-04-21","endDate":"2026-04-27","channel":"%E5%8D%8E%E4%B8%BA"}'

返回格式：

{
  "retentionInfo": [
    {
      "date": "2026-04-21",
      "totalInstallUser": 132,
      "retentionRate": [0.3561, 0.2727, 0.1462, 0.0914, 0.0619]
    },
    {
      "date": "2026-04-22",
      "totalInstallUser": 145,
      "retentionRate": [0.3890, 0.2870, 0.1580, 0.0960, 0.0680]
    }
  ]
}

返回字段说明：

> 💡 读数建议：LLM 在向用户呈现留存率时，将小数 0.3561 换算为 35.61% 更易理解；当数组某项为 null / 空时，说明该窗口尚未到期（见下文「边界条件」）。

公共约束

日期格式与范围换算

• startDate / endDate 统一使用 yyyy-MM-dd
• 本 Skill 不提供 --range yesterday/last_7_days/... 语法糖：客户端自行按当前日期换算，常用映射如下：

periodType 聚合

> 与 umeng-cli-uapp-event 的 7 个接口「全部不支持 periodType」形成对比，本接口原生支持 daily/weekly/monthly。

分页

• 本 Skill 接口不支持分页，一次调用即返回完整时间段的 retentionInfo[]
• 大时间窗口查询直接传 startDate/endDate 即可

channel / version 过滤

• 均仅限单个取值；不支持传入多个用逗号/数组
• 多版本、多渠道对比 → 客户端循环多次调用（见「典型工作流」）
• 想枚举可用版本/渠道 → 使用 umeng-cli-uapp-channel-version 的 getVersionData / getChannelData

urlEncode 规则

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

• channel：含空格 / 中文 / 特殊字符
• version：一般纯数字 + 点号无需编码；但含字母组合或特殊后缀（如 2.0-beta）时建议编码

示例：

retentionRate 空值与"今日"规则

• 接口文档明示：「不包含今日」——留存率的分子需要"安装日之后第 N 天"实际发生，若 N 天尚未过去，对应索引位可能为 null / 0
• 例如今天是 2026-04-27，查询 date=2026-04-25 的留存：
• retentionRate[0]（次日，对应 2026-04-26）：有值
• retentionRate[1]（3日，对应 2026-04-28）：还未到期，通常为 null 或 0
• LLM 在摘要时应避免把 0 误读为"留存率 0%"，需判断窗口是否已到期

返回数据为空的常见原因

• 时间范围过新（含今日）：留存数据需要相应留存天数后才能生成
• version / channel 拼写错误或大小写不匹配
• version / channel 含空格/中文但未做 urlEncode
• appkey 所属应用在该时间段内无新增/活跃用户

典型工作流

工作流 1：基础留存趋势（含索引抽取）

需求："过去 30 天的次日留存怎么样？"
1. 客户端计算 startDate = today - 30, endDate = today - 1
2. getRetentions(appkey, startDate, endDate)  ← 一次拿到 5 个窗口
3. 客户端对 retentionInfo[] 逐项取 retentionRate[0]（次日）
4. 汇总：日均次日留存率、最高/最低点、整体趋势
5. 可选：同一数组取 retentionRate[2]（7日）/ [4]（30日）并行展示

工作流 2：多留存窗口对比（同时间段 1/7/30 日）

需求："过去 30 天的 1日、7日、30日留存对比曲线"
1. getRetentions(appkey, last_30_days)  ← 仍是 1 次调用
2. 客户端对每个 retentionInfo[i]：
   - d1 = retentionRate[0]
   - d7 = retentionRate[2]
   - d30 = retentionRate[4]
3. 输出 3 条时间序列（同一 X 轴，3 条 Y 曲线）
4. 摘要：三窗口的均值与下降幅度（如 d1 35% → d7 14% → d30 6%）
5. 注意：越后期的窗口在末期天数上越可能 null（尚未到期）

工作流 3：版本留存对比（客户端并行循环）

需求："3.2 和 3.1 版本的次日留存对比"
1. （可选）先用 umeng-cli-uapp-channel-version 的 getVersionData 确认版本存在
2. 对每个版本 v in ["3.2", "3.1"]：
   - getRetentions(appkey, last_7_days, version=v)
3. 客户端汇总：
   - 对齐 retentionInfo[].date
   - 提取各自 retentionRate[0]
4. 输出对比：两条次日留存曲线；均值差异、峰值差异
5. 提醒：每个版本的 totalInstallUser 可能差异大，须在报告中标注基数

工作流 4：渠道留存对比（客户端并行循环）

需求："GooglePlay 和 AppStore 的 7日留存对比"
1. （可选）先用 umeng-cli-uapp-channel-version 的 getChannelData 确认渠道存在
2. 对每个渠道 c in ["GooglePlay", "App Store"]：
   - urlEncode(c) → "GooglePlay" / "App%20Store"
   - getRetentions(appkey, last_7_days, channel=<encoded>)
3. 对齐 date，提取 retentionRate[2]（7日）
4. 输出双渠道 7 日留存对比 + 基数（totalInstallUser）
5. 多渠道（≥3）场景同理，循环调用 N 次并合并

边界条件与错误处理

• 未说 appkey：先询问；若用户不知道，引导至友盟后台查询或用 uapp-assets Skill
• 未说 App 名：先询问，不要猜测；App 名无法匹配时提示「可用 uapp-assets 查询应用列表」
• appkey 无效：响应非成功，提示「找不到该应用，请确认 appkey 是否正确或是否已开通 U-App 统计」
• 查询今天/昨天留存：说明留存数据需要相应留存天数后才能生成；次日留存至少要到"第二天才能计算"，建议 last_7_days 或更早的起始日，并在摘要中提示"末期天数的中长窗口尚未到期"
• retentionRate 某项为 0 / null：区分两种情况：
• 该日留存窗口尚未到期（如今天查 30 日留存）→ 告知用户「尚未到期，暂无数据」
• 该日确实留存为 0 → 按字面呈现
• 版本/渠道拼写错误：响应返回空 retentionInfo[]；建议通过 umeng-cli-uapp-channel-version 查询可用列表
• type=activeUser 时 totalInstallUser 字段：仍是"当日安装用户数"，不是"当日活跃用户数"；若用户需要活跃用户留存的分母基数，请用 umeng-cli-uapp-core-index 的 getActiveUsers 另取
• 大时间范围 + periodType=daily：一次返回可能上百条记录；客户端建议分段摘要而非全量堆叠
• 多版本/多渠道对比传了单参数：本接口不支持 versions/channels 复数形式，也不支持逗号分隔；必须客户端循环
• 未登录 / 登录态过期：执行 umeng-cli login --no-qr（AI Agent 以后台模式运行并将链接展示给用户）

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

旧 skill 参数等价对照

旧 uapp-retention 的 CLI 参数与新接口的等价关系：

注意事项

• 本 Skill 仅覆盖 1 个只读查询接口 umeng.uapp.getRetentions；不涉及任何写入或事件管理
• 接口为 GET 方法；appkey 到友盟官网 https://www.umeng.com/ 应用管理后台查询
• 核心概念：留存窗口（次日/3日/7日/14日/30日）对应 retentionRate[] 数组索引 [0/1/2/3/4]，不是接口参数
• type 仅两个取值：newUser（默认）/ activeUser；其他字符串会被接口拒绝或返回默认
• periodType 支持 daily/weekly/monthly：与 umeng-cli-uapp-event 的 7 个接口「全部不支持 periodType」形成差异
• channel / version 仅限单个：多维度对比由客户端循环调用实现
• urlEncode：channel 含空格/中文必须编码；version 含特殊字符时建议编码
• totalInstallUser 语义恒定：无论 type=newUser 或 activeUser，均为"当日安装用户数"（非活跃基数）
• "不含今日"与未到期窗口：查询含今日或临近日期时，后段留存窗口可能为 null / 0（尚未到期），LLM 摘要时需区分"尚未到期"与"真实为 0"
• 版本 / 渠道枚举：去 umeng-cli-uapp-channel-version 用 getVersionData / getChannelData（本 Skill 不重复收纳）
• 响应体无 page / totalPage：本接口不支持分页，单次调用返回完整区间

快速参考

> 完整 uapp namespace 其他接口（如 getActiveUsers / getNewUsers / getChannelData 等）请参考 umeng-cli/reference/openapi/uapp.md。
> 版本 / 渠道列表枚举请使用 umeng-cli-uapp-channel-version；核心指标查询请使用 umeng-cli-uapp-core-index；自定义事件查询请使用 umeng-cli-uapp-event。