Push troubleshooting

In order to get push working successfully with your app, you need to ensure setup of both the app and your Dotdigital push configuration are in sync. If you're having trouble, or seeing high push failures, please check the following.

  1. You have setup your Dotdigital push configuration correctly and it really matches your app
  2. Your app is registering a unique but consistent push profile id per app user and an email address as detailed here
  3. Your app is managing to acquire a native push token and register it with our SDK, and for iOS the format of the token is correct and the environment matches the build. See these sections for more details:
  1. If all of the above is correct then, it could be a issue with your connectivity or another technical issue:


Ensure your user has allowed push notifications!

If your app user does not allow push notifications (they have said No to the initial prompt or subsequently removed permissions for your app in their phone settings) then your app will not receive a push token and will not be able to use push.

APNS (iOS Push)

When configuring APNS, the following factors should be considered:

  • The private key is uploaded to Dotdigital, and the key id set correctly
  • The Apple provisioning profile used to sign your app has push enabled
  • The app entitlements include push and the right APNS environment
  • The Apple team id you refer to owns your app

Setting up a your APNS settings in Dotdigital is covered here.

Development builds push setup

During development, a Apple provisioning profile will be used to sign and deploy your app to a handset. To ensure push works with your app, ensure the following:

  1. Your app provisioning profile includes the Push Notification entitlement
  2. You have uploaded a the correct p8 (private key) to Dotdigital, supplied the correct Bundle identifier for your app, Apple team id and private key id
  3. Your iOS XCode project must have the compiler variable DEBUG=1 in it's build settings, this is normally automatically set
  4. You have included an entitlements file in your app with the following entry:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">

App Store / Distribution builds / Production environment push setup

For release builds, whether for the App Store or for Enterprise Deployment, you will need to ensure the following are all correct:

  1. Your app provisioning profile includes the correct Push entitlement
  2. You have uploaded a the correct p8 (private key) to Dotdigital, supplied the correct Bundle identifier for your app, Apple team id and private key id
  3. Your iOS XCode project must have the compiler variable DEBUG=0 in it's build settings or not defined, otherwise the SDK will register to use APNS sandbox instead of APNS production!
  4. The entitlements file in your app has the following entry:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">

Network Conditions

If you are still seeing intermittent / unreliably push, please consider the following:

Network availability

APNS prefers to use cellular data and will always use this if available. If you are in an area with poor cellular coverage, then this can affect delivery. For devices without a SIM, or those where cellular data is not available, the device will attempt to use WiFi instead. WiFi access requires certain ports to be open (and not routed via a proxy server) in order to get an optimal connection (see https://support.apple.com/en-gb/HT203609)

Connection reliability

Regardless of the type of network, the operating system will use a single connection to Apple. These connections are optimized for power and data efficiency and so will typically have long keep-alive times (exact details unfortunately not documented by Apple). However, depending on the network you are currently attached to, there is a chance that a router or gateway between the device and Apple’s servers will have a shorter connection timeout than the device. In this case, the network appliance kills the connection but the device does not notice until it next tries to send a keep-alive packet. At this point it will re-establish the connection, however there is a period of time where there is no active connection between the device and Apple’s servers and the push cannot be delivered.

In this instance, Apple will temporarily buffer the push until the device reconnects, however they will only buffer a single push for the device (subsequent sends would overwrite the pending data) and they do not say how long they hold it for.

Scenarios like this are of course difficult to capture empirical evidence for, but we have certainly seen higher instances of cases like this on corporate WiFi networks where there are a large number of devices connecting to access points, and connections are more aggressively closed off.

With each evolution of the operating system Apple are making improvements to connection reliability and so these issues are becoming less prevalent.


Try this with specific devices if you suspect the APNS connection is broken

If you have a device that does not receive a push during test scenarios, try to put the device into flight mode for a few seconds and then turn flight mode off again. This would force the device to re-establish any connections and then the next push should arrive normally.

FCM (Android Push)

FCM requires less configuration than APNS, and typically you only use one set of configuration for development and release builds.

In order for FCM to function, you need to ensure that the Sender Id supplied to the SDK matches that configured in the Firebase portal, and that the Server Key configured in Dotdigital is correct for the sender id and package id of your app. If these are in alignment, and the device has a FCM token, then push should function without issue under normal circumstances. See the FCM configuration section for details on how to set these values.

Network availability

Android devices need to be able to establish a socket to Google's FCm servers in order to receive push messages. Android will use either WiFi or mobile data to establish the connection to FCM, but WiFi is preferred. It is important that the network ports FCM uses are open and not restricted.

It is possible that the issue could be related to the mobile network the phones are using, as Android sometimes does not send heartbeat packets on the connection used by FCM to receive data frequently enough to stop the mobile network closing them, therefore cutting the phone off from FCM until it hits the next heartbeat time, which can be 28 mins apart. More details here.

If you have access to the handsets causing the issues it is possible to see info and logs about the FCM connection by opening the dialler and typing:


This should open a hidden app to show you the FCM connection status and the logs about what has been happening, which might reveal the issue.

Slow FCM delivery

On Android push messaging is delivered by the FCM service run by Google. When manufacturers deploy Android they all tune settings in the Android kernel that control performance vs. battery consumption. This tuning when they lean too far towards battery saving can cause delays in FCM. In addition to these power settings that control sleep levels, there are known issues with older Samsung phones around its memory manager shutting down FCM’s service.

It is also worth checking that on the affected devices the background data for mobile networks is still enabled, see here for more details.