Countly Documentation

Countly Resources

Here you'll find comprehensive guides to help you start working with Countly as quickly as possible.


Push Notifications

Send timely and relevant messages to your users to increase retention

Countly Push Notifications gives developers, marketers and product managers a simple way to send, manage and analyze push notifications for world's most popular platforms, iOS & Android. Push notifications are available for Community Edition and Enterprise Edition. Enterprise Edition has geolocations support on top of push plugin.

Countly provides powerful and useful messaging features, including:

  • Built-in message localization
  • Default message handling for most popular use cases
  • Test mode for both platforms
  • Message conversion tracking
  • Scheduling
  • Ability to send in user's timezone
  • And even more

You can use Push Notifications for several reasons, including:

  • Showing a particular content inside your application, like a new product feature.
  • Sending targeted messages for a new campaign.
  • Updating users about a breaking news.
  • Many more...

Countly push SDK also includes all required code to receive push messages, which means that you can start using it in your app within seconds. You need to integrate corresponding SDK (either iOS or Android) into your application.

Let's take a look at common usage scenarios.


Here is a step by step integration guide for your application to start receiving push notifications.

Integrating SDK

In order to plug in Countly SDK in your app, please refer to corresponding pages:

After SDK is integrated, when user opens the application first time, a device token is retrieved by your mobile application from Google or Apple servers, and then sent to Countly server for storage. A token is unique to a device, identifying that particular device.

Getting a token and sending it to Countly server is handled by Countly SDK automatically and you don't need to worry about this process once you integrate Countly SDK properly in first step.

Providing geolocation data (Enterprise Edition only)

Countly can send messages to users located in some area defined by a circle in Countly dashboard.
By default, Countly SDKs determine users' location using geoip database. If your app uses GPS or can provide better accuracy location, you can call setLocation method of Countly SDK of your choice to provide better location.

To define the locations that are used while sending push notifications, go to Dashboard > Messaging > Geolocations.

There you can create the new locations by providing the name of the location, the location on the map and the radius around the location that should contain the target audience for your push notification. Optionally you can also limit the location to a single application.

Requiring approval of message by Approver user (Enterprise Edition only)

Push Approver plugin allows 2-step procedure for sending push notifications:

  1. Create message and save it for approval.
  2. Approve message, effectively sending it right away or scheduling it for a date specified in (1).

Without the plugin being enabled, Countly allows any "User of" app to see messages and any Global Admin or "Admin of" app to create and send messages. To make this 2-step procedure possible, Countly user role system introduces another role - Push Approver.

Push Approver role itself doesn't give any rights to the user except for ability to approve messages. Meaning that to be able to see any messages for a particular app, user needs to be "User of" of that particular app.

Enabling Push Approver plugin also changes the way messages are handled on the server. For example, in the case user has rights to create a message, message is not sent anymore after a click on "Create" button. Instead, that button is named "Send for Approval" and the message is being put on hold for a user with Push Approver role to approve and actually send it:

After message creation, user with Push Approver role logs in and in standard table of messages sees messages waiting for his approval:

... which he can either approve or delete.

One last note involves right to create messages by Push Approver user himself. While Push Approver role doesn't give any more rights regarding Push plugin, meaning this user cannot create messages, this user can also be Global Admin or "Admin of" app. In this case, Push Approver can create messages, but they will be put on hold just like for any other kind of users. One message cannot be created and approved by single user. It means, that if there is another Push Approver 2 registered in Countly, he can approve messages created by Push Approver 1.

Sending a message

You can send messages either from Countly dashboard, or using Countly push API. Both methods have the same functionality and allow you to enter localized messages, set user filters, send messages to multiple apps and platforms at once, etc.

To send a push notification, open the Countly dashboard and then go to Dashboard > Messaging > Overview. This screen gives an overview of your application push performance. At the top, you can see the total number of your app users and how many of them have messaging enabled and could potentially receive your push notifications.

In the metrics section you can see how many messages have been sent (monthly or weekly) and how many of users have responded (have actioned on a push notification).

At the bottom you can see previously sent push notifications, either from the dashboard, from the API or from both. You can click on previous notifications and see their details. You can also duplicate them and prepare a new notification with the same data and options.

Selecting apps and platforms

If you click on the Create Message button, you will be able to create a new push notification. When creating a new push notification, the top bar indicates in which step you currently are. First, let's select applications and platforms. There are 4 parts in this first step.

  1. In the Select Apps section you can select for which apps you will send this push notification.Only the valid (with correct APN or GCM credentials) apps are shown.
  2. In the Select Platform section you select if you want to send this to the users of iOS, android or both platforms.
  3. In the Testing section you select if you want to target the production users or just the developers/test users.
  4. In the Geolocations section you can specify if you want to target users in a specific geographic location. Those locations are created by you.

Scheduling message

In the scheduling part, you select when the notification will be sent out. It can be sent right after you click the Send button if you select the Send now option. You may also send messagesat a specified date and time if you select the Schedule option.

Below, you can select if the notifications have to be sent out based on the user timezone or they are sent out at the same time based on the app's timezone. Sending push notifications based on the user timezone is supported only in Countly SDK 16.12+ (iOS & Android native SDKs) since that is the first version when SDK's send timezone information to the server. Countly will use default app timezone in case SDK haven't reported timezone yet.

Preparing the message

In the Message part you define the payload that will be distributed as push notification to all relevant users.

There are two notification types that you can send:

  1. Message notification, or
  2. Data-only (silent) notification.

For both types you can provide JSON data, badge number and a URL. However, only for the Data-only type a JSON data is mandatory. In data-only case, notification will be received without any audio or visual indicator and user won't notice that his app has received a message.

If you are sending a notification with a message, then it will be displayed as either a notification or dialog. A preview of how the notification will look can be seen in the Message preview section for both iOS and Android.

You can customize the message for every available language, otherwise it falls back to the default message. All languages you see under Compose Message part shows a list of languages that are reported by application for different user device languages. For example, if you see 5 different languages there, this shows that your users have 5 different operating system languages used.

When the notification is received the user will also hear the specified sound. Normally this is a default sound set by platform, but you can also specify a sound file. It can also be sent without any audio effect.

Reviewing and sending

In the final part you have the option to review your prepared message and in case of some error, go back and correct it. When you are done reviewing, check the I'm ready checkbox and click the Send! button. This message should now be sent to all of your relevant users at the specified date and time.

Receiving messages

Usually, Counly SDK is responsible for messages handling. Countly SDK has the following capabilities:

  • Receive a message
  • Track conversions via actions
  • Show UIAlertView if required (iOS)
  • Show Notification/dialog if required (Android)

Push Analytics

Countly is an analytics platform, so it's not a surprise that we integrated conversion tracking whenever we could. There are several metrics Countly tracks:

  1. Messaging enabled users: This is a number corresponding to how many of your users have enabled to receive push notifications. For iOS, this number shows how many users have opted in for push. On Android, push notifications are enabled by default.
  2. Number of notifications sent: A notification is considered to be sent whenever you sent a push notification on Countly dashboard.
  3. Number of actions: Notification is "actioned" whenever Countly SDK is sure that user positively reacted on it. That is when user taps "Yes" (or analogous) button in alert. For example, when you send a message with your sale landing page URL, actioned metric shows you a number of users who opened web browser with that link. When you send an update request, this metric shows a number of users who were taken to App Store or Google Play.

You can also use custom events with segmentations to get more specific and granular actions and analyze this information accordingly. Each action type can be tied to a custom event (by app developer) and when a push notification is opened and an action is done, this can be visualized directly under Dashboard > Events.


Countly Push has very powerful push sending mechanism when you need to send thousands or even millions of notifications to all users of one or many apps. Internal optimisation algorithms spread the load over different CPU cores, if any, adapt to network bandwidth available for a particular server and handle numerous use cases and common issues associates with APN or GCM services.

Depending on particular server resources and APN / GCM availability Countly can send up to 10.000 - 100.000 notifications per second. Push rate on small virtual servers (e.g 1-2 cores) is usually somewhere in 2.000 - 10.000 of messages per second range.

Contact us if you need more than 100K notifications per second and we will work with you in parallel to build a scalable infrastructure.


Apple Push Notifications Service certificate cannot be uploaded

In some cases, as you start to upload your APNS certificate, you may see popups, similar to below:

Countly validates certificate at the time of upload by establishing a connection and sending a dummy message to dummy user token. Depending on what happens, Countly responds with 3 main types of errors:

1. APN production certificate is invalid. Please check your passphrase. (Couldn't read certificate)

In this case, check your passphrase, make sure it's valid. Export certificate from Keychain Access again if error persists.

2. APN production certificate is invalid. Please check your passphrase. (Countly now requires universal HTTP/2 certificates. Please see our guide here.)

Starting from version 16.06, Countly supports only universal certificates. Depending on how you generate it, it can be called by Apple Production or Production & Sandbox. Just Sandbox or Development certificates are no longer needed for iOS apps since universal certificates work for both sandbox and production environments.

3. APN production certificate is invalid. Please check your passphrase. (Certificate rejected by APN. Possibly wrong private key if you have more than one.)

This error means that your certificate has been rejected by Apple several times. Most likely certificate is invalid because it contains invalid private key. To be sure about certificate validity, regenerate it from a computer which has all provisioning profiles installed along with correct private key (you must have ability to generate production build of your app from this computer).

I get some error codes after a notification is sent

Depending on the push service performance, uptime and reliability, you may get several errors as you send notifications. You may want to consult to APN errors and GCM errors
links for more details, but if you see such errors after you send a notification, your possible actions include:

  • Check that your certificate in case of APN or server key in case of GCM is made for the app you're sending message to. Other credentials-related checks include ensuring that Bundle ID of your iOS and Android project number in your Countly.initMessaging() call are the same as in your iOS certificate and Android project used to generate server key respectively.
  • For iOS-specific case, check that your app has correct entitlements.
  • For GCM-specific case, check that you don't use other GCM SDKs in your app. They might start competing for tokens with Countly Android SDK resulting in inconsistent behavior.

A device doesn't receive a notification

There are two possible reasons for that:

  1. Device doesn't support push notifications. Please check that push notifications are enabled on iOS globally and for this particular app. Also note that on Android Countly only supports GCM, so Google Play Services have to be enabled on the device.
  2. There is some connectivity issue so device is unable to submit token to your Countly server. You can enable SDK logging to ensure that request containing string token_session is submitted during app session. See Android SDK guide and iOS, watchOS, tvOS & OS X guide for details on logging.

Push Notifications

Send timely and relevant messages to your users to increase retention