Push notifications


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.

Sending rich & interactive push notifications

Countly provides powerful and useful messaging features, including:

  • Built-in message localization
  • Ability to send a one time or automated push notifications
  • 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.

Integrating push notifications

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.

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 your 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 messages at 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 (usual, visible push 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.

Other options that you can use here are as follows:

  1. You can attach up to 2 buttons for each platform. You can define how many buttons to be shown on platforms using Number of buttons widget.
  2. You can send a rich push notification using images, videos, sound file or animated GIFs. Note that there are a few restrictions by platforms, so it's suggested that you check type and size of media that can be sent to iOS & Android.

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)

Requiring approval of message by Approver user

Push Approver plugin, available with Enterprise Edition, allows 2-step procedure for sending push notifications:

  1. Create message and save it for approval.
  2. Approve this 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.

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.

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:

We have a short introductory video showing how push approval works:

Push notifications approval management

Sending geolocation aware push notifications

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.

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. Number of notifications sent successfully: A notification is considered to be sent whenever you sent a push notification on Countly dashboard.
  2. 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, or clicked on push notification button. 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.

Note that if you send a push notification with at least one button, then you'll also be able to see how many users have clicked on a particular button as well.

Also, on the main Messages page, you will also see number of "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.

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.

Expired tokens

Note that Countly cannot send to a token for a device if a token is expired. APN or GCM/FCM can issue a new device token for a variety of reasons:

  1. User installs your app on a new device
  2. User restores device from a backup
  3. User reinstalls the operating system
  4. User clears application data
  5. Other system-defined events

When you see one or more devices with token expired notification after a push notification is sent, reasons are stated above.

Sending automated push notifications

In order to start with automated push notifications, first you must determine your user groups. Cohorts makes it very easy to group your users who performed or didn’t perform a specific event. In order to create a cohort, you first need to click the “Cohorts” item on the left side of the main menu.

We have a great video showing how to use automated push notifications with Countly:

Automated Messages

Only in Enterprise Edition

Automated push notifications feature is only available for Enterprise Edition customers

To create a cohort, press “Create cohort” button and select the information that will help create the user group you want.

On this page you can group users who perform / do not perform an event within a certain time period. You can also add as many conditions as you want - each condition will be connected with "AND", and users who fall in both conditions will be counted as push notification receivers.

When naming a cohort, we recommend that you give as much information as possible. As the number of your user groups increases, cohorts will also be difficult to distinguish.

As a next step in creating a cohort, all you have to do is click on the Messaging tab from the main menu.

The next screen shows the total number of users and the number of users who allow push notifications. Through this screen you need to click on Create Message section.

In this next screen, click on Automated Message to be able to send push notifications automatically based on your cohort you defined before. The other tab also includes a redirect to send you push notifications one time. Note that while One-time Message feature is available in both Community Edition and Enterprise Edition, Automated Message feature is available for Enterprise Edition customers.

This screen will guide you through the steps required to send a push in 5 steps. On the first screen you will see options for the platform (eg. iOS or Android), and whether to send the push notification to test or production devices.

On the next screen, you can select user groups, which will allow them to get notified on cohort entry or exit phase. You can also organize the time scheduling of the push notification here.

The next screen directs you to the details you want to check for the transmission of the notification. It is up to you to check the information such as when the user can receive this notification, when the notification will be sent, and such.

Note that not all of your users are in the same time zone. For example, morning time in London, your users in New York may still be asleep. You may want send your push notifications according to user's timezones.

On the next screen you will organize the content you want to send to the user group. Here you can prepare content in the form of a rich push notification, in case you want to send them media alongside with your content.

You may also add a deeplink, allowing your users to navigate to the URL you want in certain options. As you enter content, you can see how it looks on a device, either Android or iPhone, instantly.

In the last step you will see a summary of the content you have created. If all the information is correct, you can tick the checkbox and start sending the message.

Personalised push notifications

Both standard and automated messages can now be customised for a particular app user who receives them. For example, you can insert user's first name into message title or add his company name to the message body. Personalisation works for any property Countly stores in User profiles, including custom properties. To add a personalised content just click "{{" button in message title or body:

Transactional notifications (beta)

In addition to standard (data-only or message-typed) and automated push notifications, version 18.08 of Countly adds limited support of so-called transactional notifications. There is no full-featured UI for this type of messages, but API side is ready for non-production use.

Transactional notifications remove the hassle of creating a Message object (line in messages table in dashboard) for each notification you send. Instead you can create one or several Message objects beforehand and just add particular users to it later on. Therefore, in case of transactional notifications you'll have to make 2 steps: 1. Create a Message by calling /i/pushes/create method with tx attribute set to true (through API only so far). Fill in default message, data, sound or badge properties just like you do with regular messages, but leave any date properties not set since they're not applicable here. Message you've just created will appear in messages table in Scheduled state. In this state message won't be sent to any users. 2. Add some users to this message by calling /i/pushes/push with: * _id of the message you've created in first step; * date and possibly tz properties to define date of sending; * messagePerLocale, data, sound, badge, buttons properties to define message contents which will override the ones set previously in first step; * userConditions & drillConditions to define specific group of users who will receive this message. 3. Repeat (2) whenever needed.

On date, user group defined by specified conditions will receive this message. You can add as many users or different notifications as you need, that is repeat step 2 whenever needed.

Note that you can activate / deactivate transactional notifications just like automated ones by sending /i/pushes/active request.


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, Countly couldn't read your certificate, no test connection have been done yet. This error means that either certificate is generated in a wrong way (use Keychain Access or openssl to check), or you may have specified wrong passphrase. 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 (Production & Sandbox in Apple Developer Portal). Just Production or Sandbox 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 is signed with wrong private key. To be sure about certificate validity, regenerate it from a computer which use use to create Ad Hoc or App Store builds (since you can submit it to Apple, it would mean you have all provisioning profiles and private keys installed, sometimes Xcode would regenerate some for you in the process).

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. Pretty much all errors you see in a message popup when it's sent have some handy explanations. But in any case, 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

Please ensure that device count on message creation screen includes your troubling device. If it doesn't, ensure that device supports push notifications (has play services installed for Android and authorised push notifications when app is first opened for iOS).

To ensure that device sends push token to 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.

Was this article helpful?
0 out of 0 found this helpful

Looking for help?