Skill: squall0925/umeng-push-helper (version 1.0.0)

--- name: umeng-push-helper description: 友盟推送后台管理助手（只读查询）。帮助获取应用列表、查询推送数据等。**使用前需用户提供 Cookie**：请访问 https://upush.umeng.com 登录后，在浏览器开发者工具的 Network 标签中复制 Cookie 并提供给系统。Use when working with Umeng push notifications or when user mentions 友盟推送. --- # 友盟推送助手 (Umeng Push Helper) ## 功能概述 本技能提供以下核心功能： 1. **获取应用列表** - 获取账号下所有应用的列表 2. **查询应用数据** - 查询指定应用的消息概览、诊断摘要和诊断报告（三个接口） 3. **获取推送周报** - 获取指定应用的推送数据周报 4. **推送轨迹查询** - 根据 appkey、device_token 和 msg_id 分三步查询推送的完整轨迹 5. **开关统计查询** - 查询应用的开关趋势数据，包括新增关闭设备数、新增打开设备数、DAU、关闭设备数、日关闭率 6. **关闭归因分析** - 分析用户关闭推送的原因，包括用户偏好、推送频次、通知内容、设备维度四个维度的深度分析 7. **概况统计查询** - 查询应用的概况统计数据，包括应用概况、推送转换数据、厂商通道额度（仅安卓），支持 HTML 可视化报告 8. **获取消息列表** - 查询指定应用的消息列表，支持分页和日期范围筛选，显示推送的完整统计数据 ## ⚠️ 安全限制 - 禁止调用的接口 **重要**：出于安全考虑，本技能**严格禁止**调用以下敏感接口： | 序号 | 禁止调用的接口 | 用途 | 风险等级 | |------|--------------|------|---------| | 1 | `https://upush.umeng.com/hsf/push/sendMsg` | 发送推送消息 | 🔴 高危 | | 2 | `https://upush.umeng.com/hsf/setting/updateApp` | 修改应用配置 | 🔴 高危 | | 3 | `https://upush.umeng.com/hsf/setting/updateChannelInfo` | 修改渠道信息 | 🔴 高危 | | 4 | `https://upush.umeng.com/hsf/setting/saveReceipt` | 保存回执配置 | 🟡 中危 | **违反后果**： - ❌ 如果用户请求调用上述接口，必须明确拒绝 - ❌ 不得提供任何绕过限制的方法或建议 - ✅ 应告知用户这些操作需要通过友盟官方后台手动执行 **允许调用的接口**（只读操作）： **基础信息查询**： - ✅ `https://upush.umeng.com/hsf/home/listAll` - 获取应用列表 - ✅ `https://upush.umeng.com/hsf/home/allAppAndGroup` - 获取所有应用和分组 - ✅ `https://upush.umeng.com/hsf/home/isFlowPackageUser` - 检查是否为流量包用户 - ✅ `https://upush.umeng.com/hsf/home/getUserProInfo` - 获取用户专业版信息 - ✅ `https://upush.umeng.com/hsf/setting/appInfo` - 获取应用详细信息 - ✅ `https://upush.umeng.com/hsf/setting/getChannelInfo` - 获取渠道配置信息 - ✅ `https://upush.umeng.com/hsf/setting/showLbs` - 检查 LBS 设置 - ✅ `https://upush.umeng.com/hsf/setting/getBenefits` - 获取权益信息 **概览页面查询**： - ✅ `https://upush.umeng.com/hsf/overview/getAppCnt` - 获取应用数量统计 - ✅ `https://upush.umeng.com/hsf/overview/getTransformData` - 获取转化数据 - ✅ `https://upush.umeng.com/hsf/overview/queryThirdQuota` - 查询第三方指标 - ✅ `https://upush.umeng.com/hsf/overview/getAppTrend` - 获取应用趋势数据 - ✅ `https://upush.umeng.com/hsf/overview/getUserCnt` - 获取用户数量统计 **推送相关查询**： - ✅ `https://upush.umeng.com/hsf/push/messageOverview` - 消息概览 - ✅ `https://upush.umeng.com/hsf/push/diagnosisSummery` - 诊断摘要 - ✅ `https://upush.umeng.com/hsf/push/diagnosisReport` - 诊断报告 - ✅ `https://upush.umeng.com/hsf/push/getToolLifeCycle` - 查询消息生命周期 - ✅ `https://upush.umeng.com/hsf/push/getToolRequestContent` - 查询推送请求内容 - ✅ `https://upush.umeng.com/hsf/push/getMsgList` - 获取推送消息列表（支持分页和筛选） - ✅ `https://upush.umeng.com/hsf/push/getMsgInfo` - 查询单条消息基本信息 - ✅ `https://upush.umeng.com/hsf/push/getMsgData` - 查询单条消息统计数据 - ✅ `https://upush.umeng.com/hsf/push/getPushExpStatData` - 查询推送失败分析数据 - ✅ `https://upush.umeng.com/hsf/push/getMsgStatChannelData` - 查询分通道送达统计 - ✅ `https://upush.umeng.com/hsf/tool/canExportMsg` - 检查是否可以导出消息 **设备相关查询**： - ✅ `https://upush.umeng.com/hsf/setting/getDeviceInfo` - 查询设备信息 - ✅ `https://upush.umeng.com/hsf/setting/deviceMessage` - 查询设备消息列表 - ✅ `https://upush.umeng.com/hsf/setting/getChannelInfo` - 查询厂商通道集成状态 **数据统计查询**： - ✅ `https://upush.umeng.com/hsf/dataStatistic/getCloseTrend` - 获取开关趋势数据 **概况统计查询**： - ✅ `https://upush.umeng.com/hsf/overview/getAppCnt` - 获取应用数量统计 - ✅ `https://upush.umeng.com/hsf/overview/getTransformData` - 获取转化数据 - ✅ `https://upush.umeng.com/hsf/overview/queryThirdQuota` - 查询第三方指标（厂商额度） **关闭归因分析**： - ✅ `https://upush.umeng.com/hsf/dataStatistic/userPreferenceAnalyzer` - 用户偏好分析 - ✅ `https://upush.umeng.com/hsf/dataStatistic/pushFrequencyAnalyzer` - 推送频次分析 - ✅ `https://upush.umeng.com/hsf/dataStatistic/pushMessageAnalyzer` - 通知内容分析 - ✅ `https://upush.umeng.com/hsf/dataStatistic/deviceDimensionAnalyzer` - 设备维度分析 ## Cookie 管理 ### ⚠️ 重要说明 **本技能不再支持自动从浏览器获取 Cookie，必须由用户手动提供 Cookie 值。** ### 方法一：直接通过对话提供 Cookie（推荐） 用户可以在对话中直接提供 Cookie，系统会自动验证并保存。 **示例格式：** ``` 我的友盟 Cookie 是：ctoken=xxx; other_cookies... ``` **处理流程：** 1. 系统接收用户提供的 Cookie 2. 自动验证 Cookie 是否包含必需的 `ctoken` 字段 3. 验证通过则保存到 `~/.qoderwork/skills/umeng-push-helper/cookie.txt` 4. 显示验证结果和保存路径 ### 方法二：使用命令行工具保存 Cookie 如果用户已经复制了 Cookie 值，可以使用以下命令保存： ```bash python scripts/manage_cookie.py save "用户提供的 cookie 值" ``` 该命令会： - 自动验证 Cookie 是否包含必需的 `ctoken` 字段 - 提取并验证 `ctoken` 长度（必须 >= 10） - 验证通过则保存到本地文件 - 显示详细的验证结果 ### 指导用户如何获取 Cookie 如果用户不知道如何获取 Cookie，请提供以下详细步骤： #### 步骤 1：登录友盟后台 1. 打开浏览器访问：https://upush.umeng.com/apps/list 2. 输入账号密码完成登录 #### 步骤 2：打开开发者工具 1. 按 **F12** 键（或右键点击页面 -> 检查） 2. 切换到 **Network**（网络）标签 #### 步骤 3：触发接口请求 1. 刷新页面（F5） 2. 或在左侧菜单点击任意功能（如"推送记录"） 3. 在 Network 标签的左侧列表中找到 XHR 请求（如 `listAll`、`appInfo`、`getMsgList` 等） #### 步骤 4：复制 Cookie 1. 点击任意 XHR 请求 2. 在右侧面板中找到 **Request Headers**（请求头）部分 3. 找到 **Cookie** 字段 4. 复制完整的 Cookie 值（是一整行很长的字符串，包含多个以分号分隔的键值对） #### 步骤 5：提供 Cookie 将复制的 Cookie 值通过以下方式之一提供给系统： - **方式 A**：在对话中直接发送："我的 Cookie 是：[粘贴的值]" - **方式 B**：使用命令行保存：`python scripts/manage_cookie.py save "[粘贴的值]"` ### Cookie 验证要求 系统会验证 Cookie 是否包含以下必需字段： - ✅ `ctoken` - CSRF 令牌（长度必须 >= 10） **注意**：不再强制要求 `umplus_uc_loginid` 字段。 ### 使用 Cookie **首次保存后，后续使用无需重复提供！** 系统会自动从 `~/.qoderwork/skills/umeng-push-helper/cookie.txt` 读取 Cookie 并携带在请求头中。 **Cookie 有效期**： - Cookie 通常在数小时到数天内有效 - 如果 API 返回认证错误，说明 Cookie 已过期 - 需要重新登录并获取新的 Cookie ### 查看和管理 Cookie ```bash # 检查是否已保存 Cookie python scripts/manage_cookie.py check # 加载已保存的 Cookie（查看完整值） python scripts/manage_cookie.py load # 验证 Cookie 是否仍然有效 python scripts/manage_cookie.py validate "<cookie_value>" # 提取 ctoken（用于调试） python scripts/manage_cookie.py extract-ctoken "<cookie_value>" ``` ## 功能一：获取应用列表 ### API 信息 - **URL**: `https://upush.umeng.com/hsf/home/listAll` - **Method**: POST - **Content-Type**: `application/json` ### 请求参数 ```json { "appkey": "", "platform": "all", "page": 1, // 页码，默认为 1，用户可查看下一页时 +1 "perPage": 15, // 每页固定 15 条记录 "hasPush": 0, "appName": "", "yearQuotaSts": 0 } ``` ### 请求头 ``` Content-Type: application/json;charset=UTF-8 Cookie: <从 cookie.txt 读取> x-csrf-token: <从 Cookie 中提取的 ctoken 值> ``` **重要说明**：系统会自动从 Cookie 中提取 `ctoken` 的值并添加到 `x-csrf-token` 请求头中，无需手动操作。 ### 响应解析与数据解读 从响应数据中提取 `data.appList` 数组，该数组包含应用信息。对每个应用提取以下字段： - `appkey` - 应用的唯一标识 - `appName` - 应用名称 - `platform` - 平台类型（android/iOS/harmony） - `dau` - 日活跃用户数 **数据解读示例**： ``` ================================================================================ 账号下共有 739 个应用，共分 50 页，当前处于第 1 页 ================================================================================ 序号 appkey 应用名称 平台 DAU -------------------------------------------------------------------------------- 1 EXAMPLE_APPKEY_001 嗣曼 PUSH 测试应用 android 2 2 EXAMPLE_APPKEY_002 ROLA 内测版 harmony 0 3 EXAMPLE_APPKEY_003 雨桐 -0529 harmony 0 ... ================================================================================ 本页显示 15 个应用（第 1-15 个） 下一页：python scripts/get_app_list.py --page 2 上一页：python scripts/get_app_list.py --page 1 ================================================================================ ``` ### 分页使用说明 **默认行为**： - 首次调用时 `page` 默认为 1 - 每页固定显示 15 条记录 - 当用户希望查看下一页时，将 `page` 参数 +1 **命令行使用示例**： ```bash # 显示第 1 页（默认） python scripts/get_app_list.py # 显示第 2 页 python scripts/get_app_list.py 2 # 显示第 3 页 python scripts/get_app_list.py --page 3 # 查看最后一页 python scripts/get_app_list.py --page 50 ``` **输出信息包含**： - ✅ 账号下应用总数（从返回结果的 `data.total` 字段解析） - ✅ 总页数（从返回结果的 `data.totalPage` 字段解析） - ✅ 当前页码（从返回结果的 `data.currPage` 字段解析） - ✅ 本页显示的应用数量和范围 - ✅ 上一页/下一页导航提示 **列表字段说明**： - **序号**：当前应用在所有应用中的排序位置 - **appkey**：应用的唯一标识符 - **应用名称**：应用的展示名称 - **平台**：应用所属平台（android/iOS/harmony） - **DAU**：日活跃用户数 ## 功能二：查询应用数据（三个接口） ### 前置条件 用户需要指定一个 `appkey` 参数 ### 使用流程 1. 确认用户已提供 `appkey` 2. 如果未提供，先调用"获取应用列表"功能让用户选择 3. 使用选定的 `appkey` 依次调用以下三个接口 ### 接口 1：消息概览 (messageOverview) **API 信息**: - **URL**: `https://upush.umeng.com/hsf/push/messageOverview` - **Method**: POST - **参数**: `{"appkey": "<用户输入的 appkey>", "dateType": "7d"}` **响应解析**: 从 `data.list` 数组中提取每个项目的 `name` 和 `value` 字段，以列表形式展示。 ### 接口 2：诊断摘要 (diagnosisSummery) **API 信息**: - **URL**: `https://upush.umeng.com/hsf/push/diagnosisSummery` - **Method**: POST - **参数**: `{"appkey": "<用户输入的 appkey>", "dateType": "7d"}` **响应解析**: 直接展示 `data` 字段的内容。 ### 接口 3：诊断报告 (diagnosisReport) **API 信息**: - **URL**: `https://upush.umeng.com/hsf/push/diagnosisReport` - **Method**: POST - **参数**: `{"appkey": "<用户输入的 appkey>", "dateType": "7d"}` **响应解析**: 提取 `data` 值，并进行简单分析： - 如果包含 `score` 字段，显示健康得分 - 如果包含 `issues` 或 `problems` 字段，列出发现的问题 - 如果包含 `suggestions` 或 `recommendations` 字段，列出建议 ### 请求头（三个接口通用） ``` Content-Type: application/json;charset=UTF-8 Cookie: <从 cookie.txt 读取> x-csrf-token: <从 Cookie 中提取的 ctoken 值> ``` **重要说明**：系统会自动从 Cookie 中提取 `ctoken` 的值并添加到 `x-csrf-token` 请求头中，无需手动操作。 ### 示例命令 ```bash python scripts/query_app_data.py EXAMPLE_APPKEY_004 ``` ## 功能四：推送轨迹查询（消息排查工具） ### 🎯 功能概述 **主要用途**：当用户反馈收不到推送消息时，通过提供 `appkey`、`device_token` 和 `msg_id`，自动分三步排查问题原因。 **适用场景**： - 📱 用户反馈收不到推送消息 - ✅ 推送后台显示成功但用户未收到 - 🔍 需要排查推送失败的具体原因 - 📊 分析消息的发送、到达、点击状态 ### 前置条件 用户需要提供以下三个参数： | 参数 | 说明 | 如何获取 | |------|------|----------| | **appkey** | 应用的唯一标识 | 运行 `python scripts/get_app_list.py` 查看应用列表 | | **device_token** | 设备的推送 token | 从客户端日志、数据库或友盟后台的设备管理中获取 | | **msg_id** | 消息 ID（22 位） | 从友盟后台的推送记录中点击具体某条推送查看详情 | ### 使用流程 系统会依次执行以下四个步骤，并提供**智能诊断建议**： #### 步骤 1：查询消息生命周期 **API 信息**: - **URL**: `https://upush.umeng.com/hsf/push/getToolLifeCycle` - **Method**: POST - **参数**: ```json { "appkey": "<应用 key>", "deviceToken": "<设备 token>", "msgId": "<消息 ID>" } ``` **返回信息**: - ✅ 消息发送时间 - 判断推送是否已发出 - ✅ 消息到达时间 - 判断设备是否收到 - ✅ 消息点击时间 - 判断用户是否点击 - ⚠️ 如果缺少某个时间点，会提示可能的问题 **诊断逻辑**: ``` ❌ 无发送时间 → 推送任务未执行或被取消 ✅ 有发送时间，❌ 无到达时间 → 网络问题、通道延迟、设备异常 ✅ 有到达时间，❌ 无点击时间 → 正常现象（用户未点击） ``` #### 步骤 2：查询设备信息（含厂商 Token 检查）⭐ **API 信息**: - **URL**: `https://upush.umeng.com/hsf/setting/getDeviceInfo` - **Method**: POST - **参数**: ```json { "appkey": "<应用 key>", "deviceToken": "<设备 token>" } ``` **返回信息**: - 设备型号 - 确认设备类型 - 操作系统版本 - 判断系统兼容性问题 - 应用版本 - 检查 SDK 版本 - 推送通道 - 验证通道配置是否正确 - **thirdTokens** - 厂商推送 Token 字典（仅安卓设备，新增重点检查项⭐） **诊断逻辑**: ``` ❌ 无法获取设备信息 → device_token 不正确或设备从未注册 ⚠️ 推送通道为 unknown → 设备推送配置异常 ✅ 信息完整 → 设备状态正常 ``` **🔍 thirdTokens 字段检查（新增功能）**： 当检测到设备为安卓设备时，会自动检查 `thirdTokens` 字段： 1. **thirdTokens 为空** ❌ ``` ❌❌❌ 严重问题：未获取到任何厂商 Token ❌❌❌ 【问题分析】 - thirdTokens 字段为空，说明设备未成功注册任何厂商推送通道 - 当设备离线时，推送将无法通过厂商通道下发 - 这是导致消息无法送达的重要原因！ 【可能原因】 1. 客户端未集成对应厂商的推送 SDK 2. 厂商推送配置不正确（如 AppKey、AppSecret 配置错误） 3. 客户端初始化时未正确调用厂商通道注册方法 4. 设备不支持该厂商推送（如模拟器、定制 ROM） 【解决方案】 1. 检查客户端代码，确认已集成对应厂商的推送 SDK 2. 在友盟后台配置正确的厂商推送凭证 路径：友盟后台 → 应用配置 → 推送渠道 → 配置对应厂商 3. 引导用户重启应用，重新注册推送 4. 检查客户端日志，查看厂商通道初始化是否成功 ``` 2. **thirdTokens 包含有效值** ✅ ``` ✅ thirdTokens 字段包含内容: ✅ 华为：abc123def456... (有效) ✅ 小米：xyz789ghi012... (有效) ⚠️ OPPO: 空值或无效 ✅ 设备已成功注册厂商推送通道 💡 如果仍无法收到消息，请检查： 1. 厂商后台配置的证书/凭证是否正确 2. 推送内容是否符合厂商规范 3. 设备通知权限是否开启 ``` 3. **thirdTokens 全为无效值** ⚠️ ``` ⚠️ 警告：虽然有 thirdTokens 字段，但所有厂商 token 均为空或无效 💡 这可能导致离线推送失败 ``` #### 步骤 3：查询推送请求内容 **API 信息**: - **URL**: `https://upush.umeng.com/hsf/push/getToolRequestContent` - **Method**: POST - **参数**: ```json { "appkey": "<应用 key>", "msgId": "<消息 ID>" } ``` **返回信息**: - 推送标题和内容 - 推送类型（单播/广播/组播等） - 推送发送时间 - 目标受众信息 **诊断逻辑**: ``` ❌ 无法获取推送内容 → msg_id 不正确或记录已删除 ✅ 内容完整 → 推送配置正常 ``` #### 步骤 4：查询当天消息列表（分页获取所有记录） **API 信息**: - **URL**: `https://upush.umeng.com/hsf/setting/deviceMessage` - **Method**: POST - **参数**: ```json { "appkey": "<应用 key>", "deviceToken": "<设备 token>", "startDate": "<从 msg_id 中提取的日期>", "endDate": "<从 msg_id 中提取的日期>", "page": 1, "pageSize": 50 } ``` **返回信息**: - 当天该设备收到的所有推送消息列表 - 包含字段：msgId、digest（标题）、startTime、status、channel 等 **分页逻辑**: ``` 1. 先查询第 1 页（pageSize=50），获取总记录数 total 2. 如果 total > 50，计算总页数 = (total + 49) / 50 3. 依次查询第 2 页、第 3 页...直到所有页面获取完成 4. 合并所有页面的消息记录 5. 找到目标 msg_id 在列表中的位置 6. 显示目标消息及之后的所有消息（按发送时间降序） ``` **输出格式**: ``` 序号 消息 ID 标题 发送时间 状态 通道 ---------------------------------------------------------------------------------------------------- 🎯1 uaop149177503491390601 点赞 2026-04-01 17:15:13 送达失败 oppo 2 uaqeph2177503481348101 评论 2026-04-01 17:13:33 已忽略 友盟 3 uafzrt6177502881316001 评论 2026-04-01 15:33:33 送达成功 友盟 ``` **说明**: - 🎯 标记为目标消息 - 显示目标消息及之前发送的消息（因为列表按时间降序排列） - 帮助分析推送频率、限流策略等问题 ### 📋 命令行使用示例 ```bash # 基本用法 python scripts/query_push_trace.py <appkey> <device_token> <msg_id> # 示例 1：排查用户反馈的推送问题 python scripts/query_push_trace.py EXAMPLE_APPKEY_001 abc123xyz 1234567890abcdef # 示例 2：使用真实的参数 python scripts/query_push_trace.py EXAMPLE_APPKEY_002 V1_abc123def456 1a2b3c4d5e6f7g8h9i0j1k ``` ### 💡 输出格式示例 ``` ================================================================================ 🔍 友盟推送消息排查 ================================================================================ 应用 Key : EXAMPLE_APPKEY_001 设备 [REDACTED_SECRET] 消息 ID : 1234567890abcdef ================================================================================ 开始排查消息未收到的原因... ================================================================================ ================================================================================ 步骤 1：查询消息生命周期 ================================================================================ 接口：https://upush.umeng.com/hsf/push/getToolLifeCycle 请求参数: { "appkey": "EXAMPLE_APPKEY_001", "deviceToken": "abc123xyz", "msgId": "1234567890abcdef" } 返回结果: { "sendTime": "2024-01-01 10:00:00", "arriveTime": null, "clickTime": null } 【消息状态分析】 ✅ 消息已发送：2024-01-01 10:00:00 ⚠️ 消息已发送但未到达 - 可能原因： - 设备网络问题 - 推送通道延迟 - 设备已关机或卸载应用 ... (步骤 2 和步骤 3) ... ================================================================================ 📊 排查结果汇总与诊断建议 ================================================================================ 发现以下问题： ⚠️ 4. 消息已发送但未到达 - 检查设备网络状态、推送通道配置 建议按以上顺序逐一排查 ================================================================================ 排查完成 ================================================================================ ``` ### 🔧 请求头（三个接口通用） ``` Content-Type: application/json;charset=UTF-8 Cookie: <从 cookie.txt 读取> x-csrf-token: <从 Cookie 中提取的 ctoken 值> ``` **重要说明**：系统会自动从 Cookie 中提取 `ctoken` 的值并添加到 `x-csrf-token` 请求头中，无需手动操作。 ### 🛠️ 常见排查场景与建议 #### 场景 1：消息未发送 ``` 症状：无 sendTime 可能原因: - 推送任务被取消 - 定时推送时间未到 - 推送配额已用完 建议：检查推送任务状态和配额使用情况 ``` #### 场景 2：消息已发送但未到达 ``` 症状：有 sendTime，无 arriveTime 可能原因: - 设备网络异常（离线/弱网） - 推送通道侧延迟或失败 - 设备已关机或卸载应用 - 设备通知权限被关闭 建议： 1. 确认设备在线状态 2. 检查推送通道配置 3. 引导用户检查通知权限 ``` #### 场景 3：消息已到达但用户未点击 ``` 症状：有 sendTime 和 arriveTime，无 clickTime 说明：这是正常现象，不属于技术问题 建议：优化推送内容和时机，提升点击率 ``` #### 场景 4：设备信息查询失败 ``` 症状：getDeviceInfo 返回错误 可能原因: - device_token 不正确或已失效 - 设备从未注册过推送 - 设备已被删除 建议：重新获取正确的 device_token ``` ### ⚠️ 错误处理 - **Cookie 无效或过期**：提示用户重新登录并获取新的 Cookie - **参数格式错误**：显示正确的用法和参数获取方法 - **API 返回错误**：显示具体的错误信息和可能的原因 - **网络错误**：提示检查网络连接 ### 📝 最佳实践 1. **优先检查 msg_id**：确保从推送记录中获取的是正确的消息 ID 2. **验证 device_token**：确保 token 是该设备当前有效的标识 3. **结合日志分析**：如有条件，同时查看客户端日志和服务端日志 4. **多次测试**：对同一设备发送多条推送，排除偶发因素 ### 前置条件 用户需要指定一个 `appkey` 参数 ### 使用流程 1. 确认用户已提供 `appkey` 2. 如果未提供，先调用"获取应用列表"功能让用户选择 3. 使用选定的 `appkey` 调用周报 API（具体 API 端点待用户提供或补充） ## 错误处理 ### Cookie 无效或过期 **症状**：API 返回 401、403 或其他认证错误 **处理步骤**： 1. **告知用户**：Cookie 可能已过期或无效 2. **指导用户重新获取**： - 访问 https://upush.umeng.com 重新登录 - 按 F12 打开开发者工具 -> Network 标签 - 刷新页面，点击任意 XHR 请求 - 复制 Request Headers 中的 Cookie 值 3. **更新 Cookie**： - 在对话中提供新的 Cookie："我的新 Cookie 是：[新值]" - 或使用命令行：`python scripts/manage_cookie.py save "[新值]"` 4. **重试请求**：使用新 Cookie 重新执行操作 ### API 调用失败 **排查步骤**： 1. 检查网络连接是否正常 2. 验证 Cookie 是否正确（包含必需的 ctoken） 3. 检查请求参数格式是否符合要求 4. 查看具体的错误响应信息 5. 向用户展示详细的错误原因和解决建议 ### ⚠️ 禁止接口调用请求 **当用户请求调用禁止的接口时**： 必须明确拒绝并回复： ``` 抱歉，出于安全考虑，本技能禁止调用以下类型的接口： ❌ 发送推送消息 (sendMsg) ❌ 修改应用配置 (updateApp) ❌ 修改渠道信息 (updateChannelInfo) ❌ 保存回执配置 (saveReceipt) 这些操作涉及账号安全和数据修改，需要您登录友盟官方后台 (https://upush.umeng.com) 手动执行。 本技能仅支持查询类操作（只读），如： ✅ 获取应用列表 ✅ 查询推送数据 ✅ 查看诊断报告 ``` **处理原则**： - 态度坚定但礼貌 - 不提供任何绕过方法 - 引导用户使用官方后台 - 说明安全原因 ## 安全注意事项 - Cookie 包含敏感认证信息，仅保存在本地 - 不要将 Cookie 分享到聊天或日志中 - 建议用户定期更新 Cookie ## 相关文件 ### 核心文件 - `cookie.txt` - 存储用户登录 Cookie - `SKILL.md` - 技能定义文档 ### 脚本工具 - `scripts/manage_cookie.py` - Cookie 管理工具（保存、加载、验证、提取 ctoken） - `scripts/get_app_list.py` - 获取应用列表 - `scripts/query_app_data.py` - 查询应用数据（三个接口） - `scripts/query_push_trace.py` - 推送轨迹查询（消息排查工具） - `scripts/query_switch_statistics.py` - 开关统计查询 - `scripts/query_close_attribution.py` - 关闭归因分析（新增功能）⭐ - `scripts/query_overview_stats.py` - 概况统计查询（新增功能）⭐ - `scripts/query_msg_list.py` - 获取消息列表（新增功能）⭐ - `scripts/query_msg_detail.py` - 单条消息详情查询（新增功能）⭐ - `scripts/switch_chart_template.html` - 开关统计 HTML 图表模板 - `scripts/close_attribution_template.html` - 关闭归因 HTML 图表模板 - `scripts/overview_stats_template.html` - 概况统计 HTML 图表模板 - `scripts/api_request.py` - API 请求封装 ## 功能六：关闭归因分析（新增） ### 🎯 功能概述 **主要用途**：深度分析用户关闭推送功能的原因，从四个维度提供详细的归因数据，帮助优化推送策略。 **适用场景**： - 🔍 分析用户为什么关闭推送 - 📊 了解不同推送频次的效果 - 📝 优化通知内容和类型 - 📲 针对不同设备制定策略 ### 四个分析维度 #### 1️⃣ 用户偏好分析 **接口**: `POST https://upush.umeng.com/hsf/dataStatistic/userPreferenceAnalyzer` **功能**: 分析用户关闭推送的偏好原因分布 **参数**: ```json { "appkey": "<应用 key>", "datetype": "7d" // 支持：1d(昨日), 7d(近 7 日) } ``` **展示形式**: - 文本条形图：显示各原因的关闭数量和占比 #### 2️⃣ 推送频次分析 **接口**: `POST https://upush.umeng.com/hsf/dataStatistic/pushFrequencyAnalyzer` **功能**: 分析推送频次与用户关闭的关系 **参数**: 同用户偏好分析 **展示形式**: - 文本条形图：显示不同频次区间的关闭情况 #### 3️⃣ 通知内容分析 **接口**: `POST https://upush.umeng.com/hsf/dataStatistic/pushMessageAnalyzer` **功能**: 分析每条推送消息的关闭情况，提供详细的消息内容和效果数据 **参数**: 同用户偏好分析 **展示字段**: - 任务描述 (description) - 推送的消息描述 - 目标人群 (target) - 推送的目标用户群体 - 发送时间 (pushTime) - 消息发送的具体时间 - 通知标题 (title) - 推送通知的标题 - 通知内容 (text) - 推送通知的正文内容 - 消息点击数 (clickNum) - 该消息被点击的次数 - 关闭通知数 (closeNum) - 用户收到后关闭通知的次数 - 正负效果比 (effectRatio) - 点击与关闭的效果比率 - 消息 ID (msgId) - 消息的唯一标识 **展示形式**: - 文本表格：详细列出每条消息的完整信息和效果数据 #### 4️⃣ 设备维度分析 **接口**: `POST https://upush.umeng.com/hsf/dataStatistic/deviceDimensionAnalyzer` **功能**: 分析不同设备类型的关闭分布 **参数**: 同用户偏好分析 **展示形式**: - 文本条形图：显示各设备类型的关闭情况 ### 📋 使用方法 #### 命令行方式 ```bash # 查询近 7 日数据（默认） python scripts/query_close_attribution.py EXAMPLE_APPKEY_005 # 查询昨日数据 python scripts/query_close_attribution.py EXAMPLE_APPKEY_005 1d # 查询近 7 日数据 python scripts/query_close_attribution.py EXAMPLE_APPKEY_005 7d ``` #### 对话方式 告诉助手： - "分析 EXAMPLE_APPKEY_005 的关闭归因" - "查看应用的关闭归因分析" - "查询昨日关闭归因数据" ### 💡 输出示例 ``` ================================================================================ 🔍 友盟推送 - 关闭归因分析 ================================================================================ 应用 Key : EXAMPLE_APPKEY_005 时间范围 : 近 7 日 ================================================================================ 👤 正在查询 用户偏好分析... ✅ 用户偏好分析 查询成功 ================================================================================ 👤 用户偏好分析 (近 7 日) ================================================================================ 【用户关闭原因偏好分布】 -------------------------------------------------------------------------------- 1. 推送太频繁 12,345 45.67% |████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░| 2. 内容不相关 8,234 30.45% |███████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░| 3. 打扰休息 4,567 16.89% |████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░| ... 📱 推送频次分析... 📝 通知内容分析... 📲 设备维度分析... 🎨 正在生成可视化图表报告... ✅ 图表报告已生成：/path/to/report.html ``` ### 📊 数据解读 **用户偏好分析**： - 识别主要的关闭原因 - 针对性优化推送策略 - 减少用户流失 **推送频次分析**： - 找到最佳推送频次区间 - 避免过度推送引起反感 - 平衡触达率和用户体验 **通知内容分析**： - 了解哪些类型的内容更受欢迎 - 优化推送内容质量 - 提高点击率和点击效果 **设备维度分析**： - 了解不同设备用户的行为差异 - 针对特定设备优化推送策略 - 提升特定平台的推送效果 ### ⚠️ 注意事项 1. **日期限制**：仅支持 `1d`（昨日）和`7d`（近 7 日），不可随意传其他日期 2. **Cookie 要求**：必须携带有效的 Cookie 才能访问接口 3. **数据解读**：结合多个维度综合分析，不要单一维度下结论 4. **隐私保护**：所有数据均为聚合统计，不包含个人隐私信息 ### 📈 优化建议 根据分析结果，可以： 1. 调整推送频次，避免用户反感 2. 优化推送内容，提高相关性 3. 分时段推送，避开休息时间 4. 针对不同设备制定差异化策略 5. A/B 测试不同推送策略的效果 ## 功能七：概况统计查询（新增） ### 🎯 功能概述 **主要用途**：一站式查询应用的核心运营数据，包括应用概况、推送转换漏斗、厂商通道额度（仅安卓），支持生成美观的 HTML 可视化报告。 **适用场景**： - 📊 快速了解应用整体运营状况 - 🔄 分析推送消息的转化漏斗 - 🏭 监控厂商通道额度使用情况 - 📈 生成可视化数据报告 ### 三个查询接口 #### 1️⃣ 应用概况 **接口**: `POST https://upush.umeng.com/hsf/overview/getAppCnt` **功能**: 获取应用的总体运营数据 **参数**: ```json { "appkey": "<应用 key>" } ``` **返回指标**: - `totalDevices` - 总设备数 - `todayActive` - 今日活跃设备数 - `todayPush` - 今日推送数量 - `todayArrive` - 今日送达数量 - `todayShow` - 今日展示数量 - `todayClick` - 今日点击数量 **各阶段比率计算**: - 送达率 = todayArrive / todayPush × 100% - 展示率 = todayShow / todayArrive × 100% - 点击率 = todayClick / todayShow × 100% #### 2️⃣ 推送转换数据 **接口**: `POST https://upush.umeng.com/hsf/overview/getTransformData` **功能**: 获取推送消息的转换漏斗数据 **参数**: ```json { "appkey": "<应用 key>", "msgType": "notification", // 或 "message" "dateType": "1d" // 支持："1d", "3d", "7d" } ``` **参数说明**: - `msgType`: - `notification` - 通知栏消息（默认） - `message` - 消息 - `dateType`: - `1d` - 昨日（默认） - `3d` - 近 3 日 - `7d` - 近 7 日 **返回指标**: - `pushCnt` - 推送数量 - `arriveCnt` - 到达数量 - `showCnt` - 展示数量 - `clickCnt` - 点击数量 #### 3️⃣ 厂商通道额度（仅安卓） **接口**: `POST https://upush.umeng.com/hsf/overview/queryThirdQuota` **功能**: 查询各大手机厂商的推送通道额度使用情况 **参数**: ```json { "appkey": "<应用 key>" } ``` **支持的厂商**: - 华为 (huawei) - 小米 (xiaomi) - OPPO (oppo) - VIVO (vivo) - 荣耀 (honor) - 魅族 (meizu) **返回指标**（每个厂商）: - `total` - 总额度 - `remaining` - 剩余额度 - `used` = total - remaining（已使用额度） - `usage_rate` = used / total × 100%（使用率） ### 📋 使用方法 #### 命令行方式 ```bash # 查询昨日数据（默认） python scripts/query_overview_stats.py EXAMPLE_APPKEY_005 # 查询并生成 HTML 可视化报告 python scripts/query_overview_stats.py EXAMPLE_APPKEY_005 --html # 查询近 3 日数据 python scripts/query_overview_stats.py EXAMPLE_APPKEY_005 3d # 查询近 7 日数据并生成报告 python scripts/query_overview_stats.py EXAMPLE_APPKEY_005 7d --html # 查询消息类型的近 3 日数据 python scripts/query_overview_stats.py EXAMPLE_APPKEY_005 3d message # 查询并生成报告（完整参数） python scripts/query_overview_stats.py EXAMPLE_APPKEY_005 7d notification --html ``` #### 对话方式 告诉助手： - "查询 EXAMPLE_APPKEY_005 的概况统计" - "查看应用的概况统计数据" - "生成昨日的数据报告" - "查询近 7 日的推送转换数据" - "帮我生成概况统计的可视化报告" ### 💡 输出示例 #### 终端输出 ``` ================================================================================ 📊 友盟推送 - 概况统计 ================================================================================ 应用 Key : EXAMPLE_APPKEY_005 时间范围 : 昨日 消息类型 : 通知栏消息 ================================================================================ 📊 正在查询 应用概况... ✅ 应用概况 查询成功 ================================================================================ 📊 应用概况统计 ================================================================================ 应用 Key: EXAMPLE_APPKEY_005 -------------------------------------------------------------------------------- 指标 数值 占上一阶段比率 -------------------------------------------------------------------------------- 总设备数 1,408,306 今日活跃设备 125,432 今日推送 50,000 今日送达 48,500 97.00% 今日展示 35,000 72.16% 今日点击 12,000 34.29% -------------------------------------------------------------------------------- 📱 正在查询 推送转换数据... ✅ 推送转换数据 查询成功 ================================================================================ 📱 推送转换数据 (通知栏消息 - 昨日) ================================================================================ 阶段 数量 占上一阶段比率 ------------------------------------------------------------ 推送 50,000 送达 48,500 97.00% 展示 35,000 72.16% 点击 12,000 34.29% ------------------------------------------------------------ 📊 转化漏斗: 推送 ██████████████████████████████████████████████████ 50,000 送达 ███████████████████████████████████████████████░░ 48,500 (97.00%) 展示 ██████████████████████████████████████░░░░░░░░░░░ 35,000 (72.16%) 点击 ███████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 12,000 (34.29%) 🏭 正在查询 厂商通道额度... 💡 提示：仅安卓应用需要查询此项 ✅ 厂商通道额度 查询成功 ================================================================================ 🏭 厂商通道额度统计 ================================================================================ 应用 Key: EXAMPLE_APPKEY_005 -------------------------------------------------------------------------------- 厂商 剩余额度 总额度 使用率 -------------------------------------------------------------------------------- 华为 850,000 1,000,000 15.00% |███████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░| 小米 420,000 500,000 16.00% |████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░| OPPO 180,000 200,000 10.00% |█████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░| VIVO 270,000 300,000 10.00% |█████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░| -------------------------------------------------------------------------------- ================================================================================ ✅ 概况统计查询完成 ================================================================================ 📊 正在生成 HTML 可视化报告... ✅ 图表报告已生成：/path/to/outputs/overview_stats_EXAMPLE_APPKEY_005_20260403_152736.html 🌐 已在浏览器中打开报告 ``` ### 📊 数据解读 **应用概况**： - **总设备数**：反映应用的用户规模 - **今日活跃**：反映应用的日常活跃度 - **推送 - 送达 - 展示 - 点击**：完整的推送转化链路 - **各阶段比率分析**： - 送达率低 → 检查设备在线状态、推送通道配置 - 展示率低 → 检查通知栏折叠、系统限制 - 点击率低 → 优化推送内容和时机 **推送转换**： - **推送数量**：当天的推送任务总量 - **各阶段比率趋势**：对比不同日期类型的变化情况 - **消息类型对比**：通知栏消息 vs 消息的转化差异 **厂商额度**： - **使用率监控**：防止额度用尽影响推送 - **额度分配优化**：根据各厂商用户占比合理分配 - **预警机制**：当使用率超过 80% 时应引起注意 ### 🎨 HTML 可视化报告 **报告特点**： - 📊 **应用概况柱状图**：直观展示各项指标的对比 - 🔄 **推送转换漏斗图**：横向条形图展示转化流程 - 🏭 **厂商额度堆叠柱状图**：显示已使用和剩余额度 - 🎨 **渐变配色**：紫色系主题，美观专业 - 📱 **响应式设计**：适配各种屏幕尺寸 **报告内容**： 1. **应用概况部分** - 6 个指标卡片（总设备数、今日活跃、今日推送、今日送达、今日展示、今日点击） - 柱状图对比各指标 2. **推送转换部分** - 漏斗条形图（推送→送达→展示→点击） - 转换率标注 - 横向柱状图展示转化流程 3. **厂商额度部分** - 各厂商额度卡片 - 堆叠柱状图显示总额度和剩余额度 - 使用率进度条 ### ⚠️ 注意事项 1. **日期限制**：`dateType` 仅支持 `1d`、`3d`、`7d`，不可随意传其他值 2. **消息类型**：`msgType` 仅支持 `notification` 和 `message` 3. **厂商额度**：仅安卓应用有此项数据，iOS 应用查询会返回空 4. **Cookie 要求**：必须携带有效的 Cookie 才能访问接口 5. **HTML 报告**：使用 `--html` 参数会自动在浏览器中打开报告 ### 📈 优化建议 根据概况统计数据，可以： 1. **提升送达率**： - 优化推送通道配置 - 引导用户保持网络畅通 - 使用厂商通道提高到达率 2. **提升展示率**： - 优化推送标题和内容 - 选择合适的推送时段 - 避免被系统折叠 3. **提升点击率**： - A/B 测试不同推送文案 - 个性化推送内容 - 增加推送的吸引力和相关性 4. **厂商额度管理**： - 定期监控各厂商额度使用率 - 根据用户分布调整额度分配 - 提前申请增加高使用率的厂商额度 5. **数据趋势分析**： - 对比不同日期类型（1d/3d/7d）的数据 - 发现数据异常波动及时排查 - 建立数据基线，设定合理目标 ## 功能八：获取消息列表（包含任务粒度和 API 单播统计） ### 🎯 功能概述 **主要用途**：查询指定应用的消息列表，包含两部分数据： 1. **任务粒度的消息列表** - 显示每条推送任务的完整统计数据 2. **API 单播统计记录** - 显示每日 API 单播推送的统计数据 **适用场景**： - 📨 查看应用的历史推送记录 - 📊 分析每条消息的推送效果 - 📡 监控 API 单播推送的每日数据 - 🔍 排查特定消息的发送情况 ### 第一部分：任务粒度的消息列表 #### API 信息 - **URL**: `https://upush.umeng.com/hsf/push/getMsgList` - **Method**: POST - **Content-Type**: `application/json` #### 请求参数 ```json { "appkey": "<应用的唯一标识>", "productionMode": true, // 是否生产模式 "displayType": 0, // 展示类型 "description": "", // 任务描述筛选 "timeSelectorType": 1, // 时间选择器类型 "startTime": "yyyy-MM-dd", // 开始时间 "endTime": "yyyy-MM-dd", // 结束时间 "appGroup": false, // 是否应用组 "pageIndex": 1, // 页码 "pageSize": 15 // 每页条数（固定 15） } ``` #### 显示字段（安卓） 以下字段适用于**安卓应用**的任务粒度消息列表和 API 单播统计列表： **任务粒度消息列表**: - `description` - 任务描述 - `target` - 目标人群 - `createTime` - 创建时间 - `pushTime` - 发送时间 - `totalCount` - 计划发送 - `acceptCount` - 有效设备 - `sentCount` - 实际发送 - `arriveCount` - 消息送达 - `arriveRate` - 送达率 - `showCount` - 消息展示 - `showRate` - 展示率 - `clickCount` - 消息点击 - `clickRate` - 送达点击率（点击数/送达数） - `clickRateOnShow` - 展示点击率（点击数/展示数） - `ignoreCount` - 消息忽略 - `ignoreRate` - 忽略率 **API 单播统计记录**: - `date` - 日期 - `acceptCount` - 有效设备 - `sentCount` - 实际发送 - `arriveCount` - 消息送达 - `arriveRate` - 送达率 - `showCount` - 消息展示 - `showRate` - 展示率 - `clickCount` - 消息点击 - `clickRate` - 送达点击率（点击数/送达数） - `clickRateOnShow` - 展示点击率（点击数/展示数） - `ignoreCount` - 消息忽略 - `ignoreRate` - 忽略率 **注意**：上述字段为安卓应用的展示指标，iOS 应用的展示字段将在后续补充。 ### 第二部分：API 单播统计记录 #### API 信息 - **URL**: `https://upush.umeng.com/hsf/dataStatistic/getApi` - **Method**: POST - **Content-Type**: `application/json` #### 请求参数 ```json { "appkey": "<应用的唯一标识>", "pageIndex": 1, // 页码 "pageSize": 15 // 每页条数（固定 15） } ``` #### 显示字段（安卓） 以下字段适用于**安卓应用**的 API 单播统计列表： - `date` - 日期 - `acceptCount` - 有效设备 - `sentCount` - 实际发送 - `arriveCount` - 消息送达 - `arriveRate` - 送达率 - `showCount` - 消息展示 - `showRate` - 展示率 - `clickCount` - 消息点击 - `clickRate` - 送达点击率（点击数/送达数） - `clickRateOnShow` - 展示点击率（点击数/展示数） - `ignoreCount` - 消息忽略 - `ignoreRate` - 忽略率 **注意**：上述字段为安卓应用的展示指标，iOS 应用的展示字段将在后续补充。 ### 使用方法 ```bash # 查询默认时间范围（近 15 天）的消息列表（包含两部分数据） python scripts/query_msg_list.py EXAMPLE_APPKEY_006 # 查询指定时间范围的消息列表 python scripts/query_msg_list.py EXAMPLE_APPKEY_006 --start 2026-03-20 --end 2026-04-03 # 查询任务列表第 2 页 python scripts/query_msg_list.py EXAMPLE_APPKEY_006 --page 2 # 查询 API 单播统计第 2 页 python scripts/query_msg_list.py EXAMPLE_APPKEY_006 --api-page 2 # 同时查询任务列表和 API 单播统计的不同页 python scripts/query_msg_list.py EXAMPLE_APPKEY_006 --page 2 --api-page 3 # 按任务描述筛选 python scripts/query_msg_list.py EXAMPLE_APPKEY_006 --desc '测试' ``` ### 输出示例 ``` ================================================================================================================================================================ 📨 友盟推送 - 消息列表（任务粒度） ================================================================================================================================================================ 应用 Key : EXAMPLE_APPKEY_006 时间范围 : 2026-01-01 ~ 2026-04-07 ================================================================================================================================================================ 📊 共有 1 条数据，共 1 页，当前第 1 页 ---------------------------------------------------------------------------------------------------------------------------------------------------------------- 序号 | 任务描述 | 目标人群 | 创建时间 | 发送时间 | 计划发送 | 有效设备 | 实际发送 | 消息送达 | 送达率 | 消息展示 | 展示率 | 消息点击 | 送达点击率 | 展示点击率 | 消息忽略 | 忽略率 ---------------------------------------------------------------------------------------------------------------------------------------------------------------- 1 | N/A | 全部用户 | 2026-01-15 10:30:00 | 2026-01-15 10:30:00 | 18,300,244 | 10,275,738 | 10,275,738 | 7,523,500 | 73.22% | 5,222,299 | 69.41% | 6,614 | 0.13% | 0.06% | 4,649 | 0.06% ---------------------------------------------------------------------------------------------------------------------------------------------------------------- 📄 分页信息： 当前页：1 / 1 上一页：已是第一页 下一页：已是最后一页 ================================================================================================================================================================ ============================================================================================================================================ 📡 API 单播统计记录 ============================================================================================================================================ 应用 Key : EXAMPLE_APPKEY_006 ============================================================================================================================================ 📊 共有 30 条数据，共 2 页，当前第 1 页 -------------------------------------------------------------------------------------------------------------------------------------------- 序号 | 日期 | 有效设备 | 实际发送 | 消息送达 | 送达率 | 消息展示 | 展示率 | 消息点击 | 送达点击率 | 展示点击率 | 消息忽略 | 忽略率 -------------------------------------------------------------------------------------------------------------------------------------------- 1 | 2026-04-07 | 15,418,704 | 12,699,523 | 10,462,983 | 82.39% | 10,204,965 | 97.53% | 16,223 | 0.16% | 0.16% | 0 | 0.00% 2 | 2026-04-06 | 22,340,705 | 16,526,564 | 11,354,701 | 68.71% | 10,968,029 | 96.59% | 20,238 | 0.18% | 0.18% | 0 | 0.00% -------------------------------------------------------------------------------------------------------------------------------------------- ``` ## 功能九：单条消息详情查询（新增） ### 🎯 功能概述 **主要用途**：根据 `appkey` 和 `msg_id` 查询单条推送消息的完整详情，包括消息基本信息、推送统计漏斗、失败原因分析、厂商通道集成状态（仅 Android）和分通道送达统计（仅 Android）。 **适用场景**： - 🔍 排查某条具体推送的发送效果 - 📊 查看单条消息的完整统计漏斗 - 🏭 分析消息在各厂商通道的送达分布 - ⚠️ 诊断消息推送失败的原因 ### ⚠️ API 单播检测 **自动识别**：当 `msg_id` 以 `uu`、`ul` 或 `ua` 开头，且倒数第二位是 `0` 时，系统自动判定为 API 单播消息，将提示用户 API 单播不支持查询单条消息明细。 ### 查询流程（5 个接口） #### 接口 1：消息基本信息 (getMsgInfo) **API 信息**: - **URL**: `https://upush.umeng.com/hsf/push/getMsgInfo` - **Method**: POST - **参数**: ```json { "appkey": "<应用 key>", "taskId": "<msg_id>" } ``` **返回信息**: - 任务描述 (description/title) - 推送类型 (type/pushType) - 目标人群 (target) - 生产模式 (productionMode) - 发送时间 (pushTime/sendTime) - 创建时间 (createTime) - 状态 (status) - **channelActivity** - Android 厂商通道活动配置（⚠️ 如果未配置，无法通过厂商通道下发，只能依赖应用活跃时通过在线通道下发） **诊断逻辑**: ``` ✅ channelActivity 有值 → 厂商通道可正常下发 ⚠️ channelActivity 为空 → 无法通过厂商通道下发，只能在线通道 结合 getChannelInfo 检查哪些厂商通道未集成，逐一提示用户 ``` #### 接口 2：推送统计数据 (getMsgData) **API 信息**: - **URL**: `https://upush.umeng.com/hsf/push/getMsgData` - **Method**: POST - **参数**: 同上 **返回信息**（按漏斗展示）: - 计划发送 (totalCount) - 实际发送 (sentCount) - 消息送达 (arriveCount) + 送达率 - 消息展示 (showCount) + 展示率 - 消息点击 (clickCount) + 送达点击率 + 展示点击率 - 消息忽略 (ignoreCount) + 忽略率 #### 接口 3：失败分析 (getPushExpStatData) **API 信息**: - **URL**: `https://upush.umeng.com/hsf/push/getPushExpStatData` - **Method**: POST - **参数**: ```json { "appkey": "<应用 key>", "isTask": true, "msgId": "<msg_id>", "isFree": false, "stage": "all", "channel": "all" } ``` **返回信息**: - 各阶段失败分布（stage、channel、reason、count） - 按数量排序，计算占比 #### 接口 4：厂商通道集成状态 (getChannelInfo) - 仅 Android **API 信息**: - **URL**: `https://upush.umeng.com/hsf/setting/getChannelInfo` - **Method**: POST - **参数**: `{"appkey": "<应用 key>"}` **返回信息**: - 各厂商通道集成状态（华为、小米、OPPO、VIVO、荣耀、魅族） - 未集成的通道会发出警告 #### 接口 5：分通道送达统计 (getMsgStatChannelData) - 仅 Android **API 信息**: - **URL**: `https://upush.umeng.com/hsf/push/getMsgStatChannelData` - **Method**: POST - **参数**: `{"appkey": "<应用 key>", "taskId": "<msg_id>"}` **返回信息**: - 各通道（友盟通道/华为/小米/OPPO/VIVO/荣耀/魅族）的发送、送达、展示、点击数据 - `accs` 通道显示为"友盟通道" ### 📋 使用方法 #### 命令行方式 ```bash # 查询消息详情（终端文本输出） python scripts/query_msg_detail.py EXAMPLE_APPKEY_005 <msg_id> # 查询并生成 HTML 可视化报告 python scripts/query_msg_detail.py EXAMPLE_APPKEY_005 <msg_id> --html # API 单播自动拦截 python scripts/query_msg_detail.py EXAMPLE_APPKEY_005 uuabc123def45678901230 # → ⚠️ 该消息为 API 单播消息，不支持查询单条消息明细 ``` #### 对话方式 告诉助手： - "查询 EXAMPLE_APPKEY_005 的消息详情，msg_id 是 xxx" - "查看某条推送的完整数据" - "分析这条消息的失败原因" ### 💡 输出示例 ``` ================================================================================================================================================================ 📨 友盟推送 - 单条消息详情 ================================================================================================================================================================ 应用 Key : EXAMPLE_APPKEY_005 消息 ID : abcdefg12345678901234 ================================================================================================================================================================ 【消息基本信息】 ---------------------------------------------------------------------------------------------------- 任务描述 : xxx 推送类型 : 广播 目标人群 : 全部用户 生产模式 : 是 发送时间 : 2026-04-08 10:30:00 创建时间 : 2026-04-08 10:29:00 状态 : 发送完成 厂商通道配置 : 已配置 通道详情 : 华为: {...} 小米: {...} ---------------------------------------------------------------------------------------------------- 【推送统计漏斗】 ---------------------------------------------------------------------------------------------------- 阶段 数量 比率 可视化 ---------------------------------------------------------------------------------------------------- 计划发送 7,847,893 100.00% ██████████████████████████████████████████████████ 实际发送 5,188,950 66.12% ██████████████████████████████████████░░░░░░░░░░ 消息送达 4,338,336 83.61% ████████████████████████████████░░░░░░░░░░░░░░░░ 消息展示 3,171,839 73.11% █████████████████████████░░░░░░░░░░░░░░░░░░░░░░░ 消息点击 6,863 0.16% ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 消息忽略 28,945 0.67% ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ---------------------------------------------------------------------------------------------------- 送达点击率（点击/送达）: 0.16% 展示点击率（点击/展示）: 0.22% ---------------------------------------------------------------------------------------------------- 【失败原因分析】 ---------------------------------------------------------------------------------------------------- 序号 | 阶段 | 通道 | 原因 | 数量 | 占比 ---------------------------------------------------------------------------------------------------- 1 | send | huawei | 设备离线 | 123,456 | 45.67% 2 | arrive | xiaomi | 推送限流 | 89,012 | 32.89% ... ---------------------------------------------------------------------------------------------------- 【厂商通道集成状态】 ---------------------------------------------------------------------------------------------------- 序号 | 通道名称 | 集成状态 | 配置状态 | 说明 ---------------------------------------------------------------------------------------------------- 1 | 华为 | 已集成 | 已配置 | 2 | 小米 | 已集成 | 已配置 | 3 | OPPO | 未集成 | 未配置 | ---------------------------------------------------------------------------------------------------- ⚠️ 以下厂商通道未集成，将无法通过对应通道下发推送： - OPPO 【分通道送达统计】 ---------------------------------------------------------------------------------------------------- 序号 | 通道 | 发送 | 送达 | 送达率 | 展示 | 展示率 | 点击 | 送达点击率 ---------------------------------------------------------------------------------------------------- 1 | 友盟通道 | 1,000,000 | 800,000 | 80.00% | 600,000 | 75.00% | 1,000 | 0.13% 2 | 华为 | 2,000,000 | 1,800,000 | 90.00% | 1,500,000 | 83.33% | 3,000 | 0.17% 3 | 小米 | 1,500,000 | 1,200,000 | 80.00% | 900,000 | 75.00% | 2,000 | 0.17% ---------------------------------------------------------------------------------------------------- ``` ### 📊 数据解读 **消息基本信息**： - 确认消息配置是否正确 - 检查 channelActivity 是否配置了厂商通道 **推送统计漏斗**： - 计划发送 → 实际发送：过滤率过高说明设备 token 有效性低 - 实际发送 → 消息送达：送达率低说明通道下发有问题 - 消息送达 → 消息展示：展示率低说明通知栏被折叠或用户未查看 - 消息展示 → 消息点击：点击率低说明推送内容吸引力不足 **失败原因分析**： - 识别主要失败阶段和原因 - 针对性优化推送策略 **厂商通道集成状态**： - 确认哪些通道已集成 - 未集成的通道无法下发离线推送 **分通道送达统计**： - 对比各通道的送达率和点击率 - 优化各通道的推送策略 ### 🎨 HTML 可视化报告 使用 `--html` 参数可生成包含以下图表的报告： - 📋 消息基本信息卡片 - 📊 推送统计漏斗（横向条形图 + 进度条） - 🔍 失败原因分析（饼图 + 表格） - 🔧 厂商通道集成状态（状态卡片，仅 Android） - 📡 分通道送达统计（堆叠柱状图 + 表格，仅 Android） ### ⚠️ 注意事项 1. **API 单播限制**：API 单播消息不支持单条消息详情查询 2. **平台限制**：接口 4 和 5 仅对 Android 应用有效 3. **Cookie 要求**：必须携带有效的 Cookie 才能访问接口 4. **channelActivity 配置**：Android 应用必须正确配置 channelActivity，否则厂商通道无法使用 ### 📈 优化建议 根据查询结果，可以： 1. 优化 channelActivity 配置，确保厂商通道可正常下发 2. 集成未开通的厂商通道，提升离线推送到达率 3. 针对高失败率的阶段进行针对性优化 4. 对比各通道的送达率，调整推送策略 5. 优化推送内容，提升点击率


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)