Skip to main content

Rich Push Notifications (Images)

Attach an image to a push notification — product shots, artwork, event photos — displayed by iOS as part of the notification itself.

On Android and web push (Chromium browsers) images work with no app changes: set an image on the send and the platform renders it. On iOS, Apple requires the app to ship a small Notification Service Extension (NSE) that downloads and attaches the media before display. HoberKit provides the whole implementation — your extension is one line.

How it works​

When a send carries an image, Hober delivers the APNs payload with mutable-content: 1 and the image URL in the hober_image_url key. iOS hands the notification to your NSE before showing it; HoberKit's HoberNotificationServiceExtension downloads the image, attaches it, and delivers. If the download can't finish inside the system's time budget, the notification is delivered as text — your message always arrives.

One-time setup​

Step 1 — Add the extension target​

In Xcode: File → New → Target… → Notification Service Extension. Name it (e.g. NotificationService), and activate the scheme when prompted.

Step 2 — Add HoberKit to the new target​

Select the extension target → General → Frameworks and Libraries → add HoberKit (the same package your app target already uses).

Step 3 — Subclass​

Replace the generated template class with:

import HoberKit

final class NotificationService: HoberNotificationServiceExtension { }

That's the entire extension. Override points exist if you need custom behavior — the class is open.

Sending an image​

  • Dashboard: Compose → Push customization → Image URL.
  • API: set content.image_url on the notification (see the notifications API).

The URL must be HTTPS and publicly reachable. Keep images reasonably sized (≲ 1 MB) — the extension runs under a tight system time budget, and a slow download means the notification falls back to text.

Verifying​

  1. Send yourself a test from Compose with an Image URL set.
  2. On a real device (the simulator supports NSEs but not remote push), long press the notification — the full image expands.
  3. No image? Check, in order: the app target actually embeds the extension (Build Phases → Embed Foundation Extensions), the image URL is HTTPS and loads in Safari, and the device has network reachability beyond the push itself.

Notes​

  • Supported formats: JPEG, PNG, GIF, WebP, HEIC.
  • The attachment is downloaded fresh per notification; it does not count against your app's storage.
  • Silent (background) notifications never carry attachments — images apply to visible pushes only.