PHP/Laravel如何通过FCM向iOS、Android推送带图片的通知

现存代码的基础问题 #

• 冗余配置：$notification数组内重复定义了两次sound字段，PHP解析数组时后者会覆盖前者，属于完全无效的冗余配置。
• 配置错位：把priority参数写到了notification子数组内，实际上FCM的消息优先级是顶层配置项，放在子数组内不会生效，无法实现高优先级推送的触达效果。
• 缺少双端图文通知的必要参数配置。

核心改造逻辑 #

• 清理冗余的重复sound配置，将priority参数移到FCM消息的顶层位置，保证配置生效。
• Android端适配：在notification层级新增image字段，填入公网可访问的图片直链，系统通知栏会自动拉取展示大图，无需客户端额外做解析开发。
• iOS端适配：在消息 payload 中补全APNs层级配置，开启mutable-content权限允许系统通知扩展加载自定义内容，同时把图片URL同步写入自定义data字段，供iOS通知扩展模块读取渲染。

改造后的完整可运行代码 #

$fcmUrl = 'https://fcm.googleapis.com/fcm/send';
// 替换为公网可无鉴权访问的图片直链
$imageUrl = 'https://your-domain.com/notification-banner.jpg';

$notification = [
    'body' => 'Message',
    'title' => 'title',
    'sound' => "Enabled",
    'vibration' => true,
    'badge' => 4,
    'id' => 2,
    // Android端通知图片配置
    'image' => $imageUrl
];

// 自定义携带给客户端的扩展数据
$extraNotificationData = [
    'one' => 1,
    'two' => 2,
    // 供iOS通知扩展读取的图片地址
    'imageUrl' => $imageUrl
];

$fcmNotification = [
    'to' => $this->token, // 单设备推送token
    'data' => $extraNotificationData,
    'notification' => $notification,
    // 消息优先级移至顶层，保证高优先级推送触达
    'priority' => "high",
    // iOS端APNs配置
    'apns' => [
        'payload' => [
            'aps' => [
                'mutable-content' => 1
            ]
        ],
        'fcm_options' => [
            'image' => $imageUrl
        ]
    ]
];

$headers = [
    'Authorization: key=Server_key',
    'Content-Type: application/json'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $fcmUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($fcmNotification));
$result = curl_exec($ch);
curl_close($ch);

落地注意事项 #

• 推送用的图片必须是无鉴权的公网直链，不能是需要登录、带临时时效签名的地址，否则FCM服务无法拉取图片完成通知渲染。
• 图片大小建议控制在1MB以内，分辨率适配通知栏展示尺寸，过大的文件会导致拉取超时，最终无法展示图片。
• iOS端需要提前配置好通知扩展服务，读取data字段内的图片地址完成加载渲染，仅在服务端加FCM配置、不配置客户端扩展的话，图片无法正常展示。

内容的提问来源于stack exchange，提问作者Lb Abid