Push Notifications are a great way to keep your users engaged to your application. Countly Push Notifications gives product managers, marketers, and developers a simple way to send, manage, and analyze push notifications for applications on the world's most popular platforms - iOS and Android. This plugin allows you to send a specific message to a group of users immediately, increasing user retention and satisfaction. 

Push Notifications is available in both the Community Edition and the Enterprise Edition. Enterprise Edition has additional geolocations support.

Using Push Notifications

Typically, push notifications are one component of a product’s broader user engagement strategy. Ideally, push messaging should be implemented in addition to, rather than in place of, emailing users and displaying in-app messages. Unlike email marketing campaigns, push notifications are intended to be short and succinct, as opening the notification will direct the user to the promoted content (e.g. an alert about a breaking news story will send the user to the app screen where the full story appears).

Apps (that is to say, app/product management teams) may send their users push notifications in order to:

• Highlight a new or updated product feature or content
• Remind users of an upcoming event (e.g. a birthday party) or task to complete (e.g. a to-do list item)
• Alert users to an important, time-sensitive event (e.g. flight updates, breaking news)
• Inform users of a commercial activity or event (e.g. concert tickets going on sale, retail promotions)
• Re-engage users who have not interacted with the product recently
• Showing particular content inside your application, such as a new product feature.
• Sending targeted messages for a new campaign.
• Updating users regarding breaking news

Countly Push Notifications Functionality

These are the basic features of Countly push notifications:

• Send rich push with video, image and music
• Show delivery rate, enabling percentage and action percentage
• Show all users and messaging-enabled users
• Send now or schedule to send later
• Send message, sound, badge, custom data or any combination of these
• Send to production or test devices
• Send to two platforms at the same time
• Send interactive push with buttons
• Send push notifications with a URL or deeplink
• Send localized push

Push Notifications' Basics

Latency of Push Notifications

Sometimes it might take a second for notification to be delivered, sometimes it takes longer. Latency mostly depends on device networking and Apple or Google services health and throughput.

Types of Media that Can be Sent

iOS supports video, animated image, image and audio files. Android only supports images. File size limitations for iOS is 10Mb for images, 5Mb for audio and 50Mb for video. Android doesn't have hard limits, however we strongly suggest that you limit file sizes based on iOS.

Using Buttons in Push Notifications

Countly supports up to 2 buttons for iOS and Android.

Sending Rate

Sending rate depends on your server CPU and RAM configuration. On a small server with 4 GB of RAM and 2 CPU cores, both Android and iOS push sending rate is 1500 messages per second. Increasing RAM and CPU also increases this rate.

Character Limit for Single Messages

The message size can be 4096 characters for Android and 2048 characters for iOS.

Sending Push Notifications When a Device is Offline

Sometimes, a user accepts to receive push notifications, but their device may be offline for some reason. In such a case, this request is stored and when device comes online, it's sent to Countly servers in order to not lose the request.

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 to your app, please refer to corresponding pages:

• Countly Push for iOS
• Countly Push for Android

After the SDK has been integrated, when a user opens the application for the first time, a device token is retrieved by your mobile application from the respective push notification provider (Firebase or Huawei Push Kit for Android, APN for iOS) and is then sent to your Countly server for storage. A token is unique to a device, meaning that it identifies that particular device.

Getting a token and sending it to the Countly server is handled automatically by the Countly SDK and you won’t need to worry about this process once you have integrated the Countly SDK properly as shown in the first step.

Sending a Message

You can send messages either from the Countly dashboard or by using the 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 go to Dashboard > Messaging > Overview. This screen gives you an overview of your application's push performance. At the top you can see the total number of app users as well as 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 users have responded (have actioned on a push notification).

At the bottom you can see previously sent push notifications, either from the dashboard, the API, or both. You may click on previous notifications and see their details. You may 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 > One-time Message button, you will be able to create a new push notification. When creating a new push notification, the top bar indicates the step at which 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 may select the apps for which you will send this push notification. Only the valid (with correct APN, FCM or HMS credentials) apps are shown.
2. In the Select Platform section, you may select if you would like to send this to the users of iOS, Android, or both platforms.
3. In the Testing section, you may select if you would like to target the production users or just the developers/test users.
4. In the Geolocations section, you may specify if you would like to target users in a specific geographic location. Those locations are created by you.

Scheduling Your Message

In the scheduling section, you can determine when the notification will be sent out. The notification may be sent right after you click the Send button if you select theSend now option. Alternatively, you can choose to send messages at a specified date and time by selecting the Schedule option.

You can also select if the notifications need to be sent out based on the user’s time zone or if they are sent out at the same time based on the app's time zone. Sending push notifications based on the user’s time zone is only supported in the 16.12+ (iOS and Android native SDKs) version of the Countly SDK. Countly will use the default app time zone in case the SDK has yet to report the time zone.

Preparing the Message

In the Message section, you define the payload that will be distributed as a push notification to all relevant users. You can send two notification types:

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

You may provide JSON data, a badge number, and a URL for both types. However, a JSON data is mandatory only for theData-only type. In the data-only case, notifications will be received without any audio or visual indicator and the user won't notice that their app has received a message.

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

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

The user will also hear the specified sound when a notification is received. Normally, this is a default sound set by the platform, however, you may also specify a sound file yourself. It may also be sent without any audio effect.

Other options available to you:

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

Reviewing and Sending

In the final section, you have the option to review your prepared message and, in case of any error, go back and correct it. When you are done reviewing, check the I'm ready to send this message checkbox and click the Submit for approval button. This message should now be sent to all of your relevant users at the specified date and time you chose.

Recommended Practices when Sending Push Notifications

• Know your average user’s schedule. It is critical to understand when your users want to receive push notifications, and when receiving a message would be an irritation.
• Frequency of notifications is a meaningful factor - our surveys indicate that receiving up to 8 messages in one week causes more than 60% of respondents to disable push notifications.
• Send personal and high-quality content. Even if push notifications arrive at the right time, to be truly effective the content of the messages must feel personal and engaging to the target user. This includes the CTA, i.e. your “ask” of the user, as well as the content/information the push notification directs the user to. An effective push notification will clearly indicate what the user needs to know, why they should care, and what action they can take.
• Employ deep linking / Dynamic Deep Linking to direct users to specific pages/screens.
• Prior to launching a campaign, test push notifications (e.g. via A/B testing) to identify strengths and weaknesses of proposed messages, and adjust the content accordingly.

Receiving Messages

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

• Receive messages
• Track conversions via actions
• Show the UIAlertView, if required (iOS)
• Show the Notification/dialog, if required (Android)

Resend Failed Notifications

If your push notification does not get sent due to some error(s), you can try to resend it by clicking on the three-dot overflow menu next to the Push Notification to launch the Push Notification table and selecting the option to "Resend Failed Notifications".

Requiring Message Approval via Approver User

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

1. Create a 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" the app to see messages and any Global Admin or "Admin of" the app to create and send messages. To make this 2-step procedure possible, the Countly user role system introduces another role - Push Approver.

After message creation, a user with the Push Approver role will log in and see messages waiting for their approval located in the standard table of messages:

... which they may either approve or delete.

It is also important, here, to mention the right to create messages by the actual Push Approver user. While the Push Approver role doesn't grant any more rights regarding the Push plugin, meaning this user cannot create messages, this user may also be a Global Admin or "Admin of" the app. In this case, the Push Approver may create messages, however, they will be put on hold, just like with any other type of user. One message cannot be created and approved by a single user. That means that if there is another Push Approver 2 registered in Countly, they may approve messages created by Push Approver 1.

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

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

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

Sending Geolocation-Aware Push Notifications

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

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

There, you may 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 may 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 tracked by Countly:

1. Number of notifications sent successfully: A notification is considered sent whenever you send a push notification on the Countly dashboard.
2. Number of actions: A notification is "actioned" whenever the Countly SDK is sure that a user has positively reacted on it, i.e., when a user taps the "Yes" (or analogous) button in the alert or clicked the push notification button. For example, when you send a message with your sale landing page URL, the actioned metric shows you the number of users who opened a web browser with that link.

Note: 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.

In addition, you will see a number of "Messaging enabled users" on the main Messages page. This is a number corresponding to how many of your users have enabled receiving push notifications. For iOS, this number shows how many users have opted in for push. Push notifications are enabled by default on Android.

You may also use Events with segmentations to receive more specific and granular actions and analyze this information accordingly. Each action type may be tied to a specific Event (by the app developer), and when a push notification is opened and an action completed, this may be visualized directly under Dashboard > Events.

Automated Push Notifications

In order to start working with Automated Push Notifications, you must first 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 will first need to click the “Cohorts” item on the left side of the main menu.

We have a great video showing you how to use Automated Push Notifications with Countly.

Creating Automated Push Notifications

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

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

When naming a Cohort, we recommend you give as much information as possible. As the number of your user groups increases, cohorts will also become 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 (it represents the number of users with a token stored in the Countly server). Through this screen you will need to click on the Create Message section.

On the next screen, click on Automated Messageto be able to send push notifications automatically based on the Cohort you defined above. The other tab also includes a redirect to send your push notifications only one time. Note that while the One-time Message feature is available in both the Community Edition and the Enterprise Edition, the Automated Message feature is only 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 (e.g. iOS or Android) and whether to send the push notification to test or production devices.

On the next screen, you may select the user groups, which will allow them to receive notifications upon the Cohort entry or exit phase. You may also organize the time scheduling of the push notification here.

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

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

On the next screen you will organize the content you wish to send to the user group. Here you may prepare content in the form of a rich push notification, assuming you would like to send them alongside media with your content.

You may also add a deeplink, allowing your users to navigate to your chosen URL with certain options. As you enter content, you can instantly see how it would look on an actual device, either Android or iPhone, respectively.

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

Personalized Push Notifications

Both standard and automated messages may now be customized for the particular user receiving them. For example, you may insert a user's first name into the message title or add their company name to the message body. Personalization works for any property stored by Countly in User Profiles, including custom properties. Click the "{{" button in the message title or body to add personalized content:

Transactional Notifications

In addition to standard (data-only or message-typed) and automated push notifications, Countly allows to send transactional notifications.

Transactional Notifications are a type of message triggered by an API request sent from external server.

They remove the hassle of creating a message object (i.e., a line in the messages table on the dashboard) for each notification you send. Instead, you may create one or several message objects beforehand and simply add particular users to it later on.

Transactional Notifications can be created via an API or using the Countly Dashboard interface.

Creating Transactional Messages via API

In order to use an API to create transactional notifications, follow the steps below:

1. Create a Message by calling the /i/pushes/create method with the tx attribute set to true. Fill in the default message, data, sound, or badge properties just as you would with regular messages but leave any date properties as not set, as they are not applicable here. The message you have just created will appear in the messages table in the Scheduled state. In this state, the message will not be sent to any users.
2. Add some users to this message by calling /i/pushes/push with:
   • _id of the message you have created in the first step;
   • dateand possibly tz properties to define date of sending;
   • messagePerLocale, data, sound, badge, buttons properties to define the message contents which will override the ones previously set in the first step;
   • userConditions and drillConditions to define the specific user groups who will receive this message.

On date, all users defined by the specified conditions will receive this message. You may add as many users or different notifications as you need, or in other words, repeat step 2 whenever needed.

Note that you may activate/deactivate transactional notifications just as with automated ones by sending a /i/pushes/active request.

Creating Transactional Messages from Countly Dashboard

Similarly to the process of creating the other types of Push Notifications, Transactional Messages repeat some of the steps, but with certain differences.

To get started, upon clicking the Create Message and choosing the Transactional option, you will open the Create Push Notification drawer, consisting of 5 steps.

1. Platforms: allows you to select both the platform (iOS, Android, or both) and the type of user that will receive the message.
2. Campaign Rules: sets the start and optional end of the messaging campaign.
3. Message Delivery: lets you cap the number of messages sent to each user.
4. Message: contains the push notification editor with a preview and all the personalization features possible, including visuals, actionable buttons, and data.
5. Review: shows the summary of the content, campaign, and targets of the notification.

Performance

Countly Push Notifications has a very powerful push sending mechanism that you may use when you need to send thousands or even millions of notifications to all the users of one or many apps. Internal optimization algorithms spread the load over different CPU cores, if there are any, and adapt to the network bandwidth available for a particular server, while handling numerous use cases and common issues associated with the APN, FCM, or HMS services.

Depending on the particular server resources and APN/FCM/HMS availability, Countly can send 10,000 - 100,000 notifications per second. Push rate on small virtual servers (e.g. 1-2 cores) is usually somewhere between the 2,000 - 10,000 messages-per-second range and highly depends on MongoDB performance.

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

FAQ and Troubleshooting

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 the one displayed below:

Countly validates a certificate at the time of upload by establishing a connection and sending a dummy message to a 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 has yet been completed. This error means that either your certificate has been generated incorrectly (use Keychain Access or openssl to check) or you may have specified the incorrect passphrase. Export your certificate from Keychain Access again if the 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 and Sandbox in the Apple Developer Portal). Only Production or Sandbox certificates are no longer needed for iOS apps, as 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 your certificate is invalid because it is signed with the incorrect private key. To be sure about the validity of your certificate, regenerate it from a computer, which will use it to create Ad Hoc or App Store builds (since you can submit it to Apple, it would seem that you have all the provisioning profiles and private keys installed; sometimes Xcode would regenerate some for you in the process).

I receive 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. However, all errors you see in a message popup when it is sent have valid explanations. Yet, in any case, you can consult the APN errors and FCM errors links for more details. However, if you see such errors after you send a notification, your possible actions include:

• Check that your certificate (for your APN, or the server key for FCM/HMS) is made for the app to which you are sending the message. Other credential-related checks include ensuring that the 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 your server key, respectively.
• For iOS-specific cases, check that your app has correct entitlements.
• For Android-specific cases, check that you aren’t using other FCM-enabled SDKs in your app. They might begin competing for tokens with the Countly Android SDK, resulting in inconsistent behaviour.

A device doesn't receive a notification

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

To assure that device is sending push tokens to the Countly server, you may enable SDK logging to ensure that requests containing a string token_session are submitted during the app session. See the Android SDK guide and iOS, watchOS, tvOS, and OS X guide for details on logging.

Some of the users don't receive push notifications

If you see on the dashboard that some of your users don't receive push notifications, then either they have uninstalled your application, or their device tokens are invalid. In this case, push notification is not received at the end. Under the Messaging dashboard, you will see how many invalid push notification tokens there are, per each push notification sent.

Does Countly push notifications have API?

It's possible to send push notifications programmatically. Please refer to REST API Reference documentation for more information.

Where can I host my images or videos?

All images and videos should be hosted on a site and each device will retrieve those images and videos before showing the notification to your users. Note that Apple requires storing those images on a secure URL (which eventually should start with HTTPS).

How can I enter required information for my app to send a push notification?

Push notifications is integrated into Countly. When you add an application and then click on edit button, you'll see a list of necessary credentials and certifications for iOS and/or Android. You need to fill in these blanks and this information is available on your dashboard on either Google Play or App Store dashboard.

What are general industry standards for opening push notifications?

In our investigations, opening rate is between 10-60% for most applications. You can greatly increase this number by educating your app users before asking for a push receipt request - so that they can know they'll benefit from your app by allowing to get push notifications.