Silent push

A silent push wakes your app in the background and hands it the data set on the message, without showing anything to the person. Use this page to set your app up to receive silent pushes.

How it works

When you send a silent push, Firebase delivers a data-only message to your app, even when your app is in the background. The SDK reports Delivered to Customer.io and passes the key/value data set on the message to a callback you register. The SDK doesn’t show a notification or open a link for a silent push, and it doesn’t report Opened.

Silent push needs version 5.1.0 or later of the Android SDK. Older versions ignore silent pushes. Customer.io sends silent pushes to every Android device a message targets, and doesn’t check which SDK version the device uses.

Set up silent push

Register a callback with setBackgroundPushCallback when you configure the push module in Application.onCreate, where you initialize the SDK. Firebase can start your app’s process in the background only to deliver a silent push, and only a callback that you register during startup receives it.

val builder = CustomerIOConfigBuilder(
    applicationContext = this,
    cdpApiKey = "your-cdp-api-key"
).addCustomerIOModule(
    ModuleMessagingPushFCM(
        MessagingPushModuleConfig.Builder()
            .setBackgroundPushCallback { context, payload ->
                // Key your work on payload.deliveryId: the same push can arrive more than once.
                enqueueAccountRefresh(context, payload.deliveryId, payload.data)
            }
            .build()
    )
)

CustomerIO.initialize(builder.build())

The callback gets a CustomerIOBackgroundPushPayload:

The SDK calls your callback on the thread that handed it the message, and Firebase gives that thread only a short time. Keep the callback short, and hand longer work to WorkManager.

If your app has its own FirebaseMessagingService that forwards messages to CustomerIOFirebaseMessagingService.onMessageReceived, as described in push notifications, silent pushes reach your callback the same way. onMessageReceived returns true for a silent push.

When automatic push tracking (autoTrackPushEvents) is on, which is the default, the SDK reports Delivered for each silent push. If you don’t register a callback, the SDK still reports Delivered and drops the data.

What to plan for

Firebase and Android decide when to deliver a silent push, and don’t always deliver it:

• Repeats: The same push can arrive more than once, and the SDK calls your callback for every copy it receives. Use deliveryId to skip work you already did.
• Delays: Android can hold normal-priority messages while the device is idle. If your app needs the data right away, set the message’s Android priority to High in Design Studio. Firebase may still lower the priority of high-priority messages that keep showing no notification.
• Offline devices: After a device has been offline, silent pushes can arrive late, out of order, or not at all. Treat each silent push as a signal to fetch the latest state from your own backend.
• Force-stopped apps: Android doesn’t deliver pushes to an app the person force-stopped.