Push notifications

Follow

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

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 time zone
  • Much more

You may use Push Notifications for several reasons, including:

  • Showing particular content inside your application, such as a new product feature.
  • Sending targeted messages for a new campaign.
  • Updating users regarding breaking news.
  • Much more

The Countly push SDK also includes all the code required to receive push messages, meaning you may start using it in your app within seconds. You will need to integrate the 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 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 Google or Apple servers and is then sent to the Countly server for storage. A token is unique to a device, meaning 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 may 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.

Open the Countly dashboard and go to Dashboard > Messaging > Overview to send a push notification. 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 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 Messagebutton, 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 Appssection you may 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 Platformsection you may select if you would like to send this to the users of iOS, Android, or both platforms.
  3. In the Testingsection you may select if you would like to target the production users or just the developers/test users.
  4. In the Geolocationssection 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 may select when the notification will be sent out. The notification may be sent right after you click the Sendbutton if you also select theSend now option. In addition, you may send messages at a specified date and time by selecting the Scheduleoption.

You may select below 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 & Android native SDKs) version of the Countly SDK, as that is the first version when the SDK sends time zone information to the server. 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. There are two notification types that you may send:

  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-onlytype. In the data-onlycase, 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 previewsection for both iOS and Android.

You may customize the message for every available language, otherwise it falls back to the default message. All languages you see under the Compose Messagesection 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 may define how many buttons will be shown on platforms using the Number of buttonswidget.
  2. You may send a rich push notification using images, videos, a sound file, or animated GIFs. 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 & Android.

Reviewing and sending

In the final section 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 readycheckbox and click the Send!button. This message should now be sent to all of your relevant users at the specified date and time you chose.

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)

Requiring message approval via Approver user

The Push Approver plugin, available with the Enterprise Edition, 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.

One last note involves 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. Meaning 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:

Push notifications approval management

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. That is when a user taps the "Yes" (or analogous) button in 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 a number of users who opened a 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.

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 custom events with segmentations to receive more specific and granular actions and analyze this information accordingly. Each action type may be tied to a custom event (by the app developer), and when a push notification is opened and an action completed, this may be visualized directly under Dashboard > Events.

Expired tokens

Note that Countly cannot send a push notification for a device if that token is expired. An 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 the application data
  5. Other system-defined events

When you see one or more devices with a token-expired notification after a push notification has been sent, the reasons for notification are stated above.

Sending automated push notifications

In order to start working 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 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:

Automated Messages

Only in the Enterprise Edition

The automated push notifications feature is only available for Enterprise Edition customers.

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

In this 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 you push notifications 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 looks 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 app-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 (beta)

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

Transactional notifications remove the hassle of creating a Message object (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. Therefore, in regard to transactional notifications, you'll have to perform 2 steps:

  1. Create a Message by calling the /i/pushes/create method with the txattribute set to true (currently, this may only be done through the API). 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're not applicable here. The message you've just created will appear in the messages table in the Scheduled state. In this state, the message won't be sent to any users.
  2. Add some users to this message by calling /i/pushes/push with: * _idof the message you've created in the first step; * dateand possibly tzproperties to define date of sending;*messagePerLocale, data, sound, badge, buttonsproperties to define the message contents which will override the ones previously set in the first step; * userConditions & drillConditionsto define the specific user groups who will receive this message.
  3. Repeat (2) whenever needed.

On datea user group 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.

Performance

Countly Push 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 associates with the APN or GCM services.

Depending on the 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 between the 2,000 - 10,000 messages-per-second range.

Contact us if you need more than 100K notifications per second and we will work alongside you 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 the ones 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 & 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. Basically, all errors you see in a message popup when it's sent have some handy explanations. Yet, in any case, you may like to 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 GCM) 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 GCM-specific cases, check that you aren’t using other GCM SDKs in your app. They might begin competing for tokens with the Countly Android SDK, resulting in inconsistent behavior.

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 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 & OS X guide for details on logging.

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

Looking for help?