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.

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:

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.

Performance

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.

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

Push notifications

Send timely and relevant messages to your users to increase retention