NotificationPusher 高级参数全解:badge、sound、TTL、collapseKey 等 10+ 个推送选项详解

原创2026-11-11 23:04:29770 阅读
文章标签:后端

NotificationPusher 高级参数全解:badge、sound、TTL、collapseKey 等 10+ 个推送选项详解

NotificationPusher 是一款独立的 PHP 推送通知库,支持 Apple APNS 与 Android GCM/FCM 两大通道。对于新手来说,发一条"简单文本推送"只要几行代码;但真正决定推送体验的,是那些藏在消息和适配器里的高级推送参数——比如 iOS 的 badge(角标)与 sound(提示音)、Android 的 TTL(存活时间)与 collapseKey(消息折叠键)。本文将逐一拆解 10+ 个常用推送选项:它们写在哪里、默认值是什么、什么时候该用。

一、参数都写在哪里?Message、Device、Adapter 三层配置

在 NotificationPusher 中,一次推送由三部分构成:消息(Message)+ 设备(Device)+ 适配器(Adapter),参数也分属这三层:

层级 承载对象 参数方式 典型例子
消息层 Message 构造函数第二个数组参数 options badge、sound、notificationData
设备层 Device 构造函数第二个数组参数 parameters 设备已有角标 badge
适配器层 Apns / Gcm 构造函数参数 apiKey、ttl、collapseKey、certificate

理解这三层后,下面的参数表就很好对号入座了。

二、Apple 端(APNS)消息选项详解 🍎

以下选项都通过 Message 的 options 数组传入,由 Apns.php 的 getServiceMessageFromOrigin() 方法逐个读取并拼装成 APNS 报文。官方示例可参考 apns-adapter.md。

2.1 badge:App 图标角标

  • 默认值:不传则不设置角标。
  • 机制:最终角标 = 消息里的 badge + 设备参数里的 badge。也就是说你可以在设备对象上记录"当前已有角标数",每次推送只做增量,避免角标无限累加。核心逻辑见 Apns.php 第 175–177 行。
$message = new Message('你有一条新消息', ['badge' => 1]);
$device  = new Device('token...', ['badge' => 5]); // 最终角标为 6

2.2 sound:自定义提示音

传入 App 包内的音频文件名,如 'sound' => 'example.aiff';不传则使用系统默认提示音。

2.3 静默与扩展类选项

选项 类型 作用
content-available int 设为 1 触发静默推送(Silent Push),App 在后台拉取数据,不弹通知、不响铃
mutable-content int 设为 1 启用 Notification Service Extension,允许 App 扩展在展示前修改通知内容
category string 指定通知分类标识,对应 App 中注册的交互式通知(自定义按钮)
expire int 消息过期时间(Unix 时间戳),设备离线期间的缓存送达窗口

2.4 本地化与展示类选项

  • title:通知标题(与正文 text 分开);
  • locKey / locArgs:正文的本地化 key 及参数数组;
  • titleLocKey / titleLocArgs:标题的本地化 key 及参数数组;
  • actionLocKey:自定义操作按钮的标题(注意:iOS 只支持一个操作按钮);
  • launchImage:从通知跳转 App 时的启动图;
  • urlArgs:iOS 8.2+ 的 URL 跳转参数;
  • custom:任意自定义数据数组,会被原样塞进 payload,供 App 端自行解析(见 Apns.php 第 225 行)。

三、Android 端(GCM/FCM)适配器参数详解 🤖

Android 侧的高级参数属于适配器层,在实例化 Gcm 适配器时传入。GCM 适配器明确声明了这 6 个可选参数,见 Gcm.php 第 175–185 行:

$gcmAdapter = new GcmAdapter([
    'apiKey' => 'YourApiKey',          // 必填
    'collapseKey' => 'promo_2026',      // 消息折叠
    'ttl' => 600,                      // 离线存活时间
    'delayWhileIdle' => true,          // 设备空闲时延迟发送
    'dryRun' => true,                  // 演练模式
]);
参数 默认值 作用
collapseKey 无 消息折叠键:相同 key 的待发高优先级消息会被合并,只送达最新一条,防止促销消息轰炸
ttl 600(秒) Time To Live:设备离线时消息在服务端的缓存时长,超时即丢弃。长期离线用户多的场景可适当调大
priority normal 消息优先级,high 会立即唤醒设备(耗电、影响送达时机),非紧急通知建议保持 normal
delayWhileIdle false 为 true 时,设备处于充电/空闲状态才发送,节省电量
restrictedPackageName 无 限定接收消息的 App 包名,多 App 共用密钥时防止串台
dryRun false 演练模式:true 时只校验参数并返回结果,不真正下发消息,非常适合上线前测试

这些参数的读取位置在 Gcm.php 第 162–167 行。

3.1 notificationData:FCM 通知栏数据(重点)

除 data 字段外,若想让消息出现在系统通知栏(标题 + 正文),FCM 通道必须传 notificationData,有两种等价写法(说明见 gcm-fcm-adapter.md):

// 写法一:放进 Message 的 options
$params = ['notificationData' => ['title' => '标题', 'body' => '正文']];
$message = new Message('This is an example.', $params);

// 写法二:使用专用消息类 GcmMessage
$message = new GcmMessage('This is an example.');
$message->setNotificationData(['title' => '标题', 'body' => '正文']);

GcmMessage 的 notificationData 属性定义见 GcmMessage.php。注意适配器会把 notificationData 从 data 中剥离并单独设置为 notification 字段(Gcm.php 第 151–153 行),否则 FCM 不会按通知栏消息处理。

四、CLI 推送也能带参数 🚀

不想写 PHP 代码?项目根目录提供 np 命令行脚本,通过 --key=value 形式传适配器参数(实现见 PushCommand.php),文档见 push-from-cli.md:

./np push apns <token> "It's an example!" --certificate=/path/to/certificate.pem
./np push gcm <token> "It's an example!" --api-key=XXXXXXXXXX

五、新手常见误区与最佳实践

  1. badge 只加不减:把设备当前角标存到 Device 参数里做增量,是最稳妥的做法;
  2. ttl 不是发送延迟:它描述的是设备离线时服务端"帮你保管"消息的时间,不是"多久后发送";
  3. FCM 不传 notificationData 收不到通知栏弹窗:data-only 消息只会静默送达 App 的 onMessageReceived;
  4. 上线前先用 dryRun 验证:'dryRun' => true 可零成本检验参数配置;
  5. 参数拼写错误会抛异常:适配器用 OptionsResolver 校验,未定义的参数会被拒绝,报错信息会指明缺哪个 key(如 apiKey、certificate)。

六、参数速查表

参数/选项 所属通道 所属层级 一句话说明
badge APNS 消息 + 设备 角标数,支持设备侧增量累加
sound APNS 消息 自定义提示音文件
content-available APNS 消息 静默推送
mutable-content APNS 消息 通知内容可被 App 扩展修改
category APNS 消息 交互式通知分类
expire APNS 消息 消息过期时间戳
custom APNS 消息 透传自定义数据
notificationData FCM 消息 通知栏标题/正文(FCM 必填)
collapseKey GCM/FCM 适配器 同类消息折叠,保留最新
ttl GCM/FCM 适配器 离线消息存活时长(默认 600s)
priority GCM/FCM 适配器 消息优先级(默认 normal)
delayWhileIdle GCM/FCM 适配器 设备空闲时才发送
dryRun GCM/FCM 适配器 演练模式,不真实下发
restrictedPackageName GCM/FCM 适配器 限制接收包名

掌握上表中的 10+ 个推送选项后,无论是 iOS 的静默拉取、交互通知,还是 Android 的消息合并、省电策略,都能用 NotificationPusher 一行配置搞定。更多入门示例可参考 getting-started.md 与 facades.md,单元测试中对参数的覆盖可参考 tests/units/Sly/NotificationPusher/Adapter/Gcm.php。

登录后查看全文
NotificationPusher