Skip to main content

Rich push image behavior

Push notifications can include an Image URL that displays as a rich media attachment. Layout differs by platform and Android OS version — this is expected platform behavior, not an SDK defect.

Prerequisites​

  • Push payload includes image_url (HTTPS, publicly reachable, under ~1 MB)
  • Android: SDK renders the notification via showActionableNotification or turnkey setupPushNotifications
  • iOS: Notification Service Extension (NSE) with OpenCdpPushExtensionHelper and aps.mutable-content: 1

Step 1 — Add an image to your push​

Dashboard: In the push editor, set the Image field to a public HTTPS URL.

API / FCM data payload:

{
  "title": "Hello",
  "body": "Check this out",
  "image_url": "https://example.com/images/promo.jpg"
}

Step 2 — Android layout​

The OpenCDP Android SDK uses NotificationCompat.BigPictureStyle. Collapsed layout depends on the device API level:

Android 12+ (API 31+) — collapsed:
┌─────────────────────────────────────┐
│ [icon] Title              [thumb] ▼ │
│        Body text                    │
└─────────────────────────────────────┘

Android 12+ — expanded:
┌─────────────────────────────────────┐
│ [icon] Title                        │
│        Body text                    │
│ ┌─────────────────────────────────┐ │
│ │         Full image              │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────┘

Android 7–11 (API 24–30) — collapsed:
┌─────────────────────────────────────┐
│ [preview] Title                 ▼   │
│           Body text                 │
└─────────────────────────────────────┘
StateAndroid 12+ (API 31+)Android 7–11 (API 24–30)
CollapsedApp icon left; thumbnail rightImage preview left (setLargeIcon)
ExpandedFull-width image at bottomFull-width image at bottom
Not an SDK bug

Right-side thumbnails on newer Android and left-side previews on older Android are intentional. The SDK branches on Build.VERSION.SDK_INT >= 31.

Step 3 — iOS layout​

iOS uses a Notification Service Extension to download and attach the image before display.

  • Set aps.mutable-content: 1 in the APNS payload when image_url is present
  • Add NSE target using OpenCdpPushExtensionHelper
  • Collapsed/expanded layout is controlled by iOS — not Android-style left/right thumbnails
  • Without NSE: notification shows title and body only (no image)

See: Flutter push notifications (NSE setup) · iOS push example

Step 4 — Verify it worked​

PlatformWhat to check
Android 12+Collapsed: thumbnail on right; expanded: full image at bottom
Android 7–11Collapsed: preview on left; expanded: full image at bottom
iOSImage attachment visible when NSE is wired
AllDelivery/open metrics still fire after image attach

Enable debug: true and look for SDK logs confirming image download and notification post.

Text-only notification (no image)​

If you expected an image but see title/body only:

CauseFix
No image_url in payloadAdd Image URL in editor or payload
Image download failedUse HTTPS, valid content-type, reachable URL; check logs
Hybrid FCM payload (notification + data)Send data-only on Android when SDK owns display
Custom handler not using SDKCall showActionableNotification or setupPushNotifications
iOS missing NSEAdd Notification Service Extension

Backend contract (summary)​

FieldLocationNotes
image_urlFCM data / APNS custom dataHTTPS URL string
custom_dataFCM dataJSON string of custom key-values
actionsFCM dataJSON array of action buttons
mutable-contentAPNS apsRequired for iOS rich content

Android: Prefer data-only FCM messages when the SDK renders notifications. Hybrid payloads can cause duplicate tray entries.

Troubleshooting​

SymptomLikely causeAction
Thumbnail on right (new phone)Android 12+ expectedNone — document for QA
Preview on left (old phone)API 24–30 OS behaviorNone — OS limitation
No imageMissing NSE (iOS) or no SDK render (Android)Wire NSE / showActionableNotification
Duplicate notificationsHybrid FCM payloadUse data-only Android push
Plain notification despite URLDownload failedCheck URL, HTTPS, size, logs