NotificationPusher 高级参数全解:badge、sound、TTL、collapseKey 等 10+ 个推送选项详解
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 |
- 消息层的选项读写逻辑集中在 BaseOptionedModel.php 的
getOptions()/setOption()方法中; - 设备层则基于 BaseParameteredModel.php;
- 适配器层的参数通过 Symfony OptionsResolver 做校验(必填/默认值),见 BaseAdapter.php 构造函数。
理解这三层后,下面的参数表就很好对号入座了。
二、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
五、新手常见误区与最佳实践
- badge 只加不减:把设备当前角标存到
Device参数里做增量,是最稳妥的做法; - ttl 不是发送延迟:它描述的是设备离线时服务端"帮你保管"消息的时间,不是"多久后发送";
- FCM 不传 notificationData 收不到通知栏弹窗:data-only 消息只会静默送达 App 的
onMessageReceived; - 上线前先用 dryRun 验证:
'dryRun' => true可零成本检验参数配置; - 参数拼写错误会抛异常:适配器用 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。