Push Notifications: Frequently Asked Questions

How do conversions work with push notifications?

Conversions are attributed to the last email or message sent, opened, or clicked before the person performs an event or enters/leaves a segment defined in your conversion goal. If you track users performing an action or entering a segment after receiving a push, then the message will be marked as converted, regardless of the device we reached them on.

What Firebase permissions does Customer.io need in order to send push notifications?

Firebase’s documentation says that we need the cloudmessaging.messages.create permission since we use the FCM HTTP API to send push notifications, that permission however does not belong to the Firebase Cloud Messaging Admin role. The roles that have that permission (found here) include:

  • Owner (roles/owner)
  • Editor (roles/editor)
  • Firebase Admin (roles/firebase.admin)
  • Firebase Grow Admin (roles/firebase.growthAdmin)
  • Firebase Admin SDK Administrator Service Agent (roles/firebase.sdkAdminServiceAgent)
  • Firebase SDK Provisioning Service Agent (roles/firebase.sdkProvisioningServiceAgent)

Alternatively, if you wanted to provide even more limited permissions, you should be able to define a custom role with only the cloudmessaging.messages.create permission.

How do I know if a push notification was opened?

Our SDKs can automatically track opens.

If you don’t use our SDKs, you’ll need to add some code to your app; first, to detect when an open occurs, and then to send an event to our API. To track opens and attribute them to specific notifications, you’ll need to send us events including the CIO-Delivery-ID and CIO-Delivery-Token parameters from the push, as documented in our Technical Integration Guide.

How do I know if a push notification failed because the app has been uninstalled?

Push notification services don’t provide a reliable way of detecting this with absolute certainty. However, when you look at a push notification’s status, getting a Bad Device Token error for a device is a reasonable indicator that this particular person no longer has the app installed.

How do I track app uninstalls?

Some push services use scheduled silent push notifications as a brute force way of seeing if an app is still installed on a device. Usage of silent background pushes for app uninstall tracking violates Apple and Google developer policies and is now significantly limited with iOS 15:

With iOS & iPadOS 15 Beta 4: Background pushes will only be delivered if the app has been used in the foregraound in the past few weeks.

Instead, you can use app activity (i.e. has logged in in last 30 days) to reliably measure conversions and engagement.

Is there a character limit or best practice?

Because push notifications go to so many devices, their text might get cut off at different points. What looks great on an iPad’s lock screen might get awkwardly truncated in a Pixel’s notification center.

As devices and operating systems change, so do the number of ways a push notification can be seen. The only concrete restriction is a message size limit: 4KB (4096 bytes) for both Apple Push Notification service (APNs) and Android’s Firebase Cloud Messaging (FCM). This isn’t just for the message text, but for the entire payload— this includes any other custom data being sent along with that notification.

Tip: To reduce payload size, omit whitespace and line breaks!

To make sure your notifications are as successful as possible, we encourage you to:

  • Keep it brief! A good general guideline is to make it actionable and beneficial in less than 40 characters.
  • Test them! This way, you can see how they’re appearing in the wild, and make them shorter if you need to.

I’ve set up push for iOS, but am getting an invalid token error!

If you receive an Invalid device token (APNs BadDeviceToken) error, Apple doesn’t recognize the token you added via our updateDevice API call as valid for that app or environment. There are a few reasons why that might occur:

  • You are using an incorrect token for that particular end-user, or an old token that no longer exists.
  • Your app is built using the development configuration rather than production. Device tokens are unique to each environment and today, we only support the production environment.

Apple rotates device tokens for several reasons, one of which is the end-user reinstalling the app or updating their OS. Because these tokens rotate frequently, we recommend that you send us an updateDevice API call every time your app is launched to ensure that we’ve always got the latest device token.

To fix this issue, confirm that:

  1. The iOS .p8 app certificate you’ve uploaded is the same one that’s in use for the app that generated the device token. Device tokens are not re-used - they’re unique to the app and certificate.
  2. The device token is for the production environment, not using the development/sandbox environment.
  3. You’re attempting to send to the most recently generated device token. Once a new token has been generated, the old one will fail.

If you’re still getting this error, get in touch with us at win@customer.io.

How is the last used device determined?

A given user’s “last used device” is the device they last used to access your app. It’s determined by the timestamp in the most recent identifyDevice API call. We recommend calling this every time your app is launched to keep the “Last Used” value up to date.

This is sometimes a friendlier way of targeting people, and lets you send a message to the device a person is most likely to use rather than sending a message to every device a person owns.

How do I know that a person saw or dismissed the push notification?

Our SDKs can automatically track push delivered and opened metrics. You can reasonably infer “dismissed” notifications from those two metrics.

If you don’t use our SDKs, iOS and Android’s push notification services don’t generally provide this information. There are some platform-specific ways to add code to your app to detect that a notification was received when the app is in the foreground or background. However, this won’t catch notifications received when your app isn’t running.

In our Rich Push editor, you can add images and deep links and specify whether iOS devices should play the default sound or not. In both the Rich Push and Custom Payload editors, you can add custom JSON for buttons and other formatting.

How should I set up testing?

We recommend that you set up a separate workspace to test your push notifications, even if (in the case of iOS, for example) you use the same configuration credentials for testing and production.

If you have different versions of your app, notifications will be routed correctly based on the device IDs that each app sends to Customer.io—which should be unique per app. If you choose to use separate workspaces per version of your app (e.g., dev/staging/production) then each version of your app should register devices in the proper workspace.

How do I find a device token so I can send a test push from the composer?

Device tokens are located on an individual’s Person page:


You can search for a the specific person you want to send the test to, and then go to the Devices tab to see their device tokens. You can then hover over a device and click to copy the token to a push notification.


How do I target a test version of my app?

We recommend that you create a new workspace, in which push notifications are configured with the certificates for your test app. You can also swap the certificates in your configuration.

Can I send to iOS via FCM/Firebase?

Yes, you can! You will see this option in your iOS configuration:


It will be available for you if you have not set up Android as well. If you select this option, you will still need to setup the configuiration for Android if you haven’t yet done so.

Whether or not you should do this depends entirely upon your setup and what’s easier for you. For example, if FCM is a critical part of your infrastructure, and you don’t plan to configure the Apple Push Notification Service anytime soon, this may be a valuable option.

I want to send push notifications only to Android/iOS. How?

On the push notification workflow item, you’ll be able to select a specific platform:


A push notification with a platform specified here will only be sent if a customer has a device with that platform!

How do I configure my notification to display text right-to-left (RTL)?

The alignment for push notifications is determined by the iOS or Android OS and device settings. It is not configurable through the push notification payload. For iOS, the system looks at the first character in the title and automatically chooses RTL or LTR based on the character’s languague. On Android, the text alignment is defined by the device’s locale/language.

I need a new feature! When will you add it?

If you find that push notifications are missing a critical feature, let us know what it is, and what kind of messages you’d like to send using it. As an intermediate workaround, webhooks are really powerful!

What kinds of apps do your SDKs support?

Today, we support both native Android and iOS apps, as well as the following hybrid mobile platforms: React Native, Flutter, and Expo.

If your app is built in another hybrid platform like Ionic, you might be able to use our SDKs, but you’ll need to write custom code (or “bridges”) to integrate our existing SDKs into your apps.

Do Customer.io SDKs work with Segment’s SDK?

Yes, and if you already use Segment, you should integrate with Customer.io as well! The Segment SDK collects data, and you can pipe that data to Customer.io through Segment. Segment’s SDK does not interpret push notifications, identify devices in Customer.io, etc. You need Customer.io’s SDKs to do those things. So, we strongly suggest that you integrate with our SDKs, even if you already use Segment’s SDKs.

 Integrate with iOS 2.x versions if you also use Segment’s SDK

Our iOS 3.x versions don’t support having both Segment and Customer.io installed at the same time. If you’ll need this ability long-term, please let us know. Our iOS 3.x versions do support our own CDP, Data Pipelines, which you can migrate to.

Do I have to use Customer.io SDKs to handle push notifications?

No, you’re welcome to write your own integration. But we think that our SDKs greatly simplify the process of identifying devices and interpreting push notifications, without adding bloat to your app.

Do Customer.io SDKs support in-app messaging?

They do! See our in-app documentation for more information.

Copied to clipboard!