DooTask 友盟 Alias 用户绑定机制:设备注册、多设备规则与推送目标选择

原创2026-10-14 15:23:57715 阅读
文章标签:后端前端桌面应用协同办公

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 反向查到该用户所有活跃设备,把通知投递过去。

从源码结构看,这条链路分三步:

  1. 注册侧:UsersController::umeng__alias() 在用户登录后把 userid + alias + platform 写入或更新 umeng_alias;
  2. 选型侧:UmengAlias::pushMsgToUserid() 按 userid 查出 30 天内活跃的别名记录,按平台分组后交给友盟;
  3. 投递侧: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,服务端依次执行:

  1. 拒绝调试模式:isDebug 非 0 直接返回错误「调试模式下不允许使用」,避免调试包污染生产推送目标(UsersController.php#L1534-L1537);
  2. 表单验证:alias 必填且长度在 2-20 个字符之间;
  3. 平台校验:Base::platform() 必须是 ios / android,否则返回「设备类型错误」;
  4. 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() 实现,核心代码逻辑为:

  1. 查询条件固定加 updated_at > now - 1 month,即 30 天未活跃的别名不会进入候选集;
  2. userid 支持单个或数组,结果按 updated_at 倒序、以 100 条为一批 chunkById 遍历,避免大用户量下一次性加载;
  3. 每个用户先 take(5) 截取最近的设备记录,再 groupBy('platform'),同一平台内的 alias 用逗号 implode(',') 拼成一个批次字符串(对应「每个用户每平台最多 5 个 alias 一起发」;从源码结构看,take(5) 发生在按平台分组之前,代码注释也写明「每个会员最多推送 5 个别名」,实际效果是单个用户一轮最多发出 5 条别名、按平台合并投递);
  4. 每个用户处理前,把入参的 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 层按以下顺序核验(更完整的排查清单见 移动端推送收不到怎么办):

  1. umeng_alias 中是否存在该 userid 且 updated_at 在 30 天内的记录(不存在 → 重新登录 APP 触发注册,接口失败可查 APP 端网络);
  2. platform 是否为目标平台、对应平台密钥是否已配置(只配一端则只推一端);
  3. umeng_logs 中该 alias 的最近请求/响应,确认友盟侧是否返回成功;
  4. 设备系统层:通知权限、Android 后台保活设置(参见 FAQ 文档中的厂商设置项)。

本文所有结论均可在仓库内验证:概念定义与规则以 alias.md 为准,接口实现见 UsersController.php,选型与投递实现见 UmengAlias.php,表结构演进见 database/migrations 下 umeng_alias 相关迁移文件。

登录后查看全文
dootask