DooTask 友盟 Alias 用户绑定机制:设备注册、多设备规则与推送目标选择
DooTask 友盟 Alias 用户绑定机制:设备注册、多设备规则与推送目标选择
本文围绕 DooTask 的友盟(UMENG)Alias 用户绑定机制展开:先讲清 umeng_alias 绑定表记录什么、由哪些字段构成,再完整走一遍 api/users/umeng/alias 的别名注册/解绑接口与校验规则,最后深入源码看推送时如何按 userid → alias 反查活跃设备、应用多设备与 30 天活跃规则来选中推送目标。读完后,你可以完整理解 DooTask 移动端「用户登录后为什么能收到离线推送」的底层链路,并能据此排查「收不到推送」类问题。
一、umeng_alias:一张「用户-设备-推送」绑定表
umeng_alias 是 DooTask 用来记录「某用户的某台移动设备应该接收哪些推送」的绑定表。每次移动 APP 启动登录后会调用 api/users/umeng/alias 注册或更新这条记录;后端发推送时再按 userid → alias 反向查到该用户所有活跃设备,把通知投递过去。
从源码结构看,这条链路分三步:
- 注册侧:UsersController::umeng__alias() 在用户登录后把
userid + alias + platform写入或更新umeng_alias; - 选型侧:UmengAlias::pushMsgToUserid() 按
userid查出 30 天内活跃的别名记录,按平台分组后交给友盟; - 投递侧:UmengAlias::sendTask() 通过友盟 SDK 封装(
Hedeqiang\UMeng\IOS/Android)执行customizedcast推送,并把请求/响应落库到umeng_logs表(UmengLog)。
该表由迁移 create_umeng_alias_table 创建,初始仅有 userid、alias、platform 三个业务字段,后续逐步演进:
| 迁移文件 | 新增内容 |
|---|---|
| add_umeng_alias_device | device 设备型号 |
| add_is_notified_to_umeng_alias | is_notified 系统通知权限(默认 0) |
| add_version_to_umeng_alias | version APP 版本号 |
| add_device_hash_to_umeng_alias_table | device_hash 设备指纹,关联 UserDevice 表 |
二、关键字段说明
| 字段 | 说明 |
|---|---|
| userid | DooTask 用户 ID |
| alias | 友盟 alias,用户在友盟侧的唯一标识 |
| platform | ios / android(其他平台调用会被拒) |
| device | 设备型号 |
| device_hash | 设备指纹,关联 UserDevice 表 |
| version | APP 版本号(含 versionName) |
| ua | userAgent |
| is_notified | 系统通知权限(0=未授予 / 1=已授予) |
| updated_at | 最后活跃时间;超过 30 天的别名不再被推送选中 |
字段语义可以直接在模型 UmengAlias 的注释中核对。其中几个字段在写入时有明确的生成逻辑:
- version:接口参数
appVersionName与appVersion拼接为「versionName (appVersion)」,未传appVersion时为空串(UsersController.php#L1561); - is_notified:前端传字符串
'true'或布尔true时记为 1,否则按intval处理(UsersController.php#L1562); - device_hash:取自 UserDevice::check(),其本质是当前登录 token 的
md5值——从源码结构看,它把友盟绑定与 DooTask 自己的设备记录表user_devices通过 token 指纹串了起来,同时带过期校验(过期 token 返回 null)。
三、别名注册接口:api/users/umeng/alias
接口定义在 UsersController.php#L1510-L1530,路由映射见 routes/api-map.md(api/users/umeng/alias,GET,需要 token 身份)。完整参数如下:
| 参数 | 必填 | 说明 |
|---|---|---|
| action | 否 | update 更新(默认)/ remove 删除 |
| alias | 是 | 友盟别名,长度 2-20 个字符 |
| userAgent | 否 | 浏览器信息 |
| deviceModel | 否 | 设备型号 |
| isNotified | 否 | 是否有通知权限(0 不通知、1 通知,兼容 'true') |
| isDebug | 否 | 是否调试(0 不调试、1 调试) |
注册流程(action=update)
APP 启动后调 api/users/umeng/alias?action=update,服务端依次执行:
- 拒绝调试模式:
isDebug非 0 直接返回错误「调试模式下不允许使用」,避免调试包污染生产推送目标(UsersController.php#L1534-L1537); - 表单验证:
alias必填且长度在 2-20 个字符之间; - 平台校验:
Base::platform()必须是ios/android,否则返回「设备类型错误」; - Upsert:以
userid + alias + platform三要素作为唯一判定——已存在则更新ua、device、device_hash、version、is_notified并刷新updated_at,返回「别名已存在」;不存在则插入新记录,返回「添加成功」(UsersController.php#L1555-L1586)。
updated_at 的刷新是这里的关键副作用:它既是「设备最后活跃时间」的语义来源,也是后续 30 天活跃过滤的依据——每次重新注册都相当于一次「续命」。
App 端的调用时机
移动端在 resources/assets/js/App.vue 的登录状态监听中处理别名:登录成功后延迟 6 秒(等待友盟 SDK 初始化)再向原生层发送 setUmengAlias 指令调用注册接口;退出登录时则发送 delUmengAlias 指令删除别名。这也对应了下面解绑小节中 action=remove 分支的用途。
解绑(action=remove)
退出登录时可调 action=remove 删别名。从源码结构看,该分支在平台校验之前执行,直接按 alias 值删除 UmengAlias::whereAlias(...)->delete()——即把该 alias 对应的记录全部移除,成功后返回「删除成功」。
四、多设备规则与推送目标选择
- 同一 userid 可绑定多台设备,每个设备一条记录;
- 推送时按 platform 分组,每个用户每平台最多取最近 5 个 alias 一起发(按 updated_at 倒序);
- 角标数取自该用户未读且非静默消息总数(
WebSocketDialogMsgRead)。
这三条规则全部由 pushMsgToUserid() 实现,核心代码逻辑为:
- 查询条件固定加
updated_at > now - 1 month,即 30 天未活跃的别名不会进入候选集; userid支持单个或数组,结果按updated_at倒序、以 100 条为一批chunkById遍历,避免大用户量下一次性加载;- 每个用户先
take(5)截取最近的设备记录,再groupBy('platform'),同一平台内的 alias 用逗号implode(',')拼成一个批次字符串(对应「每个用户每平台最多 5 个 alias 一起发」;从源码结构看,take(5)发生在按平台分组之前,代码注释也写明「每个会员最多推送 5 个别名」,实际效果是单个用户一轮最多发出 5 条别名、按平台合并投递); - 每个用户处理前,把入参的
badge覆盖为该用户的真实未读角标:WebSocketDialogMsgRead::whereUserid($uid)->whereSilence(0)->whereReadAt(null)->count()——即 未读(read_at 为空)且非静默(silence=0)消息的总条数。
最终每个「用户 × 平台」组合调用一次 pushMsgToAlias(),按 alias_type: 'userid' 的 customizedcast 方式投递。
五、30 天过期、卸载与记录清理
文档给出的三条「负向规则」决定了这条绑定记录的生命周期边界:
- 卸载不删记录:用户卸载 APP 后系统不会主动删除别名记录;该别名后续推送会在友盟侧失败,但同一用户的其他设备不受影响(
customizedcast按 alias 批量发送,失败只影响对应别名); - 30 天自动剔除:超过 30 天未活跃(
updated_at过期)的别名自动从推送目标中剔除,但记录仍保留在表里,用户重新打开 APP 注册别名后即恢复; - 管理员手动清理:管理员可在数据库直接清理
umeng_alias表来处理脏数据。
另外注意,Web 端 / 桌面端不会写 UmengAlias 表,因此桌面端用户不通过友盟推送触达——它们的提醒走 WebSocket / Electron 原生通知等其它通道,这与 umeng_alias 中 platform 只允许 ios / android 的取值约束是一致的。
六、别名如何被消费:一条推送的完整链路
结合仓库源码,alias 记录从写入到最终弹出通知的调用链如下:
新消息落库
└─ WebSocketDialogMsgTask(app/Tasks/WebSocketDialogMsgTask.php)
├─ 组装 title / body / description / extra(含 dialog_id、msg_id,seconds=3600)
└─ 入队 PushUmengMsg(按用户语言分组发送)
└─ PushUmengMsg::start()(app/Tasks/PushUmengMsg.php)
├─ 检查 appPushSetting.push === 'open',否则直接返回
├─ PC 端 60 秒内活跃 → 延迟 10 秒重投递(end() 中 Task::deliver)
└─ 延迟重投时若消息已被读(read_at 非空)→ 跳过
└─ UmengAlias::pushMsgToUserid() → 选定 30 天内活跃 alias
└─ pushMsgToAlias() → sendTask() 调友盟 SDK
几个值得注意的实现细节:
- PC 活跃延迟推送:PushUmengMsg 通过缓存键
user_pc_active:{userid}判断用户 PC 端是否 60 秒内活跃;活跃则延迟 10 秒再投,且重投前检查消息是否已读,已读则跳过,减少「PC 已看到、手机还弹通知」的冗余打扰; - 消息文案组装:WebSocketDialogMsgTask 中,群聊消息的标题替换为群名、正文加「发送人: 」前缀;
description固定为MID:{消息ID},extra携带dialog_id/msg_id供 App 端深链跳转; - iOS payload:标准
aps结构(alert 的 title/subtitle/body、sound: 'default'、badge),并附带policy.expire_time有效期; - Android payload:
display_type: 'notification'、after_open: 'go_app'、set_badge上限 99(min(99, $badge)),开启mipush并指定小米厂商透传 Activity;channel_properties中写死了 DooTask 的各厂商通道参数(main_activity: com.dootask.task.WelcomeActivity、oppo_channel_id: dootask、vivo_category: IM、华为 IM 通道等),local_properties将通知标记为消息类(CATEGORY_MESSAGE),提高厂商通道的展示优先级(UmengAlias.php#L205-L243); - 重试与审计:sendTask() 捕获异常后最多重试 3 次(重试耗尽后记录
[PushMsg] fail日志);每次调用都会把request/response以 JSON 形式写入umeng_logs表,可直接用于排查投递结果; - 前置开关:整条链路受 getPushConfig() 控制——
appPushSetting.push必须为open,且对应平台已配置友盟 App Key / Master Secret,否则该平台直接跳过。配置方法见 配置友盟 APP 推送。
七、限制与适用前提
结合文档的 prerequisites / negative 声明与源码校验逻辑,使用该机制需要满足:
- 管理员已在系统设置中开启 APP 推送并配置对应平台的友盟密钥(
production_mode固定为 true,需正式签名的 APP 包); - 用户在移动端 APP 已登录,且非调试模式(
isDebug=1的 APP 不会注册别名,注册接口会直接报错拒绝); - 别名 30 天未活跃即不再用于推送(
updated_at过期),但记录不删除; - Web 端 / 桌面端不写
UmengAlias表,不通过友盟推送; - 推送通道与友盟 SDK 强绑定,不支持替换为其它推送服务,也不支持脱离友盟的 P2P 推送。
八、排障指引:当推送「查无此别名」时
如果用户收不到推送,可以在 alias 层按以下顺序核验(更完整的排查清单见 移动端推送收不到怎么办):
umeng_alias中是否存在该userid且updated_at在 30 天内的记录(不存在 → 重新登录 APP 触发注册,接口失败可查 APP 端网络);platform是否为目标平台、对应平台密钥是否已配置(只配一端则只推一端);umeng_logs中该 alias 的最近请求/响应,确认友盟侧是否返回成功;- 设备系统层:通知权限、Android 后台保活设置(参见 FAQ 文档中的厂商设置项)。
本文所有结论均可在仓库内验证:概念定义与规则以 alias.md 为准,接口实现见 UsersController.php,选型与投递实现见 UmengAlias.php,表结构演进见 database/migrations 下 umeng_alias 相关迁移文件。