Push Notifications enables you to send messages to mobile app users with the purpose of announcing, informing, or promoting anything related to your products or campaigns. This feature is only available for mobile applications, and make up a great way to keep your users engaged with your application.

Benefits of Push Notifications

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. With this feature, you can incorporate push notifications right into your product analytics solution, sending a specific message to a group of users immediately to increase user retention and satisfaction, without needing to integrate additional communication tools.

Getting Started

Countly relies on push notification providers to deliver notifications:

• For iOS, we use APN (Apple Push Notification service).
• For Android, Countly supports 2 providers:
  • FCM (Firebase Cloud Messaging) for Google-enabled devices, and
  • HMS (Huawei Messaging Service) for Huawei devices.

The Countly push SDK also includes all the code required to receive push notifications, meaning you can start using it in your app within seconds. You will need to integrate the corresponding SDK (either iOS or Android) into your application.

In order to plug in Countly SDK to your app, please refer to the 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.

Push Notifications Overview

Performance and Capability

Countly Push Notifications has a very powerful push sending mechanism that you can 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.

Applying Push Notifications

Typically, push notifications are one component of a product’s broader user engagement strategy. Ideally, push notifications should be implemented in addition to, rather than in place of, emailing users and displaying in-app messages. Unlike e-mail 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 and marketing teams) may send a push notification to their users in order to:

• Highlight a new or updated product feature or content
• Remind users of an upcoming event (e.g., a sale) 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
• Show particular content inside your application, such as a new product feature
• Send targeted messages for a new campaign
• Update users regarding breaking news

Types of Push Notifications

Countly offers five types of push notifications:

• One-time Notifications: One-time Notifications are a type of message that you can set up and send for campaigns or information for which you would like to communicate with your users once. This is a one-time setup that allows you to communicate with a group of identified users, carrying any unique message required. These can be set up in minutes and sent out right away or scheduled for later delivery.
• Automated Notifications: Automated Notifications are similar to one-time notifications in their setup, but differ in their scheduling. You can set up and maintain automated notifications to go live when a user meets specific behavior or activity. With automated notifications, you do not need to repeatedly set up a notification every time a group (such as a specific cohort) refreshes. You can simply target the group such that users receive the notification whenever they interact with the group in a specific manner (enter the group, exit the group, and so on).
• Recurring Notifications: Recurring notifications are types of messages that you can send to users on a regular, scheduled basis. These notifications are typically used to remind or inform users about specific events, tasks, or updates that occur repeatedly over time. 
• Multiple Days: Multiple days type push notifications allow you to schedule messages to be sent on multiple dates and times. This versatile notification type is invaluable for a wide range of applications, from event reminders and subscription services to personalized greetings and marketing campaigns. By allowing you to precisely target when your notifications are delivered, you can engage with your audience at the most relevant moments, ensuring that your messages reach them when it matters most.
• API Notifications (Transactional Notifications): API (Transactional) Notifications are a type of message triggered by an API request sent from an external server. It is generally used to build loyalty and increase user engagement by setting up push notifications triggered by events or any user properties provided by external servers or databases. For example, send push notifications to users when a new message is received from other users, a new payment is received, credit card limit is over.

The above five types of notifications can further be categorized into two formats:

• Message: This is a notification that contains content, images, video, and audio, as per your preferences, and is seen by the user. The way they see/receive the notification can be customized on the basis of the type of notification as well as your own preferences.
• Silent (Data-only): In this format, users do not see any message or get any notification sound when the notification is received by the user app. These push notifications are designed to keep your app's data "up-to-date" by providing a way to "wake up" the app to refresh the data in the background.

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

Latency of Push Notifications

Sometimes it might take a second for a 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, (still) 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 per notification for iOS and Android.

Sending Rate

As mentioned above, the sending rate depends on your server CPU and RAM configuration. On a small server with 4GB 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 4,096 characters for Android and 2,048 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 the device comes online, it is sent to Countly servers in order to not lose the request.

When using Push Notifications in Countly, you will often come across specific terms. Let's jump into these terms and their meanings:

• Total app users: Total number of users of the app.
• Push enabled users: Number of users who agreed to receive push notifications, which is the number of users with iOS or Android tokens stored in the database.
• Icons: Mobile Push Icons are set within your mobile app. Android Mobile App Large icons can use external resources. iOS only uses the main app icon.
• Badge: Notification Badges that show on app icons refer to the little dots that show up on your mobile app icon and are meant to help capture a response from the user.
• On-click URL (CTA URL): Default URL or deeplink which opens when a user taps a message in the notification. If the notification body was clicked, the on-click URL is opened. If an action button was clicked, the action button URL is opened.
• Large icon: Optional for Android, the large notification icon will show up to the left of the notification text on Android 4.0.3 - Android 6.0 devices, and shows on the right for Android 7.0+ devices. If it is not set, the small icon is used. 
• Payload size: Payload size refers to the limitations of the notification. The maximum payload size can be 4,096 characters for Android and 2,048 characters for iOS. [From iOS: For Voice over Internet Protocol (VoIP) notifications, the maximum payload size is 5 KB (5,120 bytes). For all other remote notifications, the maximum payload size is 4 KB (4,096 bytes) Source: click here].
  You can simply copy-paste the emoji you want into the message or title. We recommend keeping your messages clear and short. Here are our recommendations:

Platform	Title	Body
iOS	~25 - 50 (Same for Subtitle)	~150
Android	~50	~150

 

• Media: These are large images, videos, sound files, or animated GIFs that appear with the notification. Note that there are a few restrictions depending on the platform, so we recommend you check the type and size of media that can be sent to iOS and Android. Here are our recommended Media sizes:
  

	Android	IOS
FileTypes	jpg, jpeg, png*	jpg, jpeg, png, gif
Resolution	Recommendations: 2:1 aspect ratio landscape Max Width: 2000 pixels Min Width: 300 pixels Common sizes: 512x256px 1440x720px	Recommendations: 2:1 aspect ratio landscape Max Width: 2000 pixels Min Width: 300 pixels Common sizes: 512x256px 1440x720px

*GIF image animations are not supported on Android mobile apps.

Layout of Push Notifications Feature

To go to Push Notifications, you need to click on Push Notifications in the Main Menu. The Push Notifications feature has two main elements:

1. Data Card, seen as three widgets at the top of the page.
2. Table, located under the Data Card.

Data Card

The Data Card shows three widgets that contain the below data:

• Total App Users: Number of users using your app.
• Notification-enabled Users: Number of users using your app who have enabled receiving notifications.
• Enabled Users Percentage: Number of users who have enabled receiving notifications expressed as a percentage of the total number of users using your app.

These metrics and the data they contain reflect information for the total number of notifications you are running and are not for just one type of notification. Hence, even if you filter notifications or any parameters (i.e., one notification type to another), this data will not change.

Table

The table will show data based on the notification type you have selected from the filter section. You can select multiple notification types to see the data, by default it shows data for all the notification types. 

The Table is specific to the notification type you have selected from the filter option, and offers an overview of the data for the same. A dropdown menu at the top of the Table allows you to filter notifications by platforms and status (see below for more details). The Table contains the below columns and data:

• Campaign Name: Name of the campaign. In case of a name that exceeds 55 characters, you will see a truncated version of the name, and hovering over the name will provide a pop-up with the full name. Also included are the platform(s) to which the notification applies, and the name of the creator.
• Status: This indicates the status of the notification. The status options differ for One-time, Recurring, Automated, and API Notifications, as detailed in the table below:

One-time	Recurring	Automated and API
Draft Scheduled or deleted Sending|Failed Sent|Failed|Stopped	Draft Scheduled or deleted  Sending|Failed Scheduled|Failed|Stopped	Draft Scheduled or deleted  Sending|Failed Scheduled|Failed|Stopped

• Created: Date and time when the notification was created.
• Date Sent/Scheduled: Date on which the notification was sent or is scheduled to be sent (in case of scheduled notifications).
• Sent: Number of notifications sent.
• Actioned: Number of notifications that received an action from the user, and the percentage of this number in relation to the number of notifications sent.
• Status with Push Approver Enabled: In the event that the admin has enabled Push Approver, the status visible on the Table will differ. Push Approver being enabled means that push notifications need to be approved by an admin before they can go live. In such a case, the below status options appear on the Table:

  • Draft: Can be sent and duplicated as well.

  • Waiting for approval: Will be sent when a user with push approver permission approves it.

  • Scheduled: Will be sent when appropriate.

  • Sending: Sending right now.

  • Sent: Sent, no further actions required.

  • Stopped: Stopped sending (one time from UI).

  • Failed: Removed from the queue, no further actions.

  • Rejected: Will be rejected when approver user rejects.
• Optional Columns: The user can also add two optional columns to the Table, namely:
  • Message Content: Detailed contents of the message included in the notification.
  • Created By: Name of the creator of the push notification.

Details of Each Push Notification

To see the details of any push notification, you simply need to click on the row of that notification in the Table. That will take you to a detailed view of the push notification, which will contain the below information:

1. Users Targeted: Total number of users targeted to receive the selected notification.
2. Sent Notifications: Total number of notifications sent, also expressed as a percentage of total users targeted.
3. Clicked Notifications: Total number of notifications clicked on or reacted to, also expressed as a percentage of total users targeted.
4. Failed: Total number of notifications that failed to get delivered, also expressed as a percentage of total users targeted.
5. Notification Summary: This section contains the below data, divided in three tabs:
   • Message Content: Details of the notification including title, text, button text, button URL, and media URL.
   • Targeting and Delivery: Details of the targeting and delivery such as the group targeted, sending time, and scheduled sending time.
   • Errors: Any errors that may have caused failure in the notification reaching the users targeted.

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 for push notifications:

1. Number of notifications sent successfully: A notification is considered sent whenever you send a push notification in Countly.
2. Number of actions: A notification is "actioned" whenever the Countly SDK is sure that a user has positively reacted to it, i.e., when a user taps the "Yes" (or analogous) button in the alert or clicks the push notification button. For example, when you send a notification 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 will also be able to see how many users have clicked on a particular button.

In addition, you will see a number of Notification-enabled Users on the main Push Notifications View. 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 Events.

Using Push Notifications

Selecting Notification Type

When you want to see data in the Table for any notification type, you need to start by selecting the notification type for which you want to see data, you can select multiple notification types as well. By default, the table will show data for all notification types. A dropdown menu under the Data Card allows you to select between the below options:

• One-Time Notifications
• Automated Notifications
• Recurring Notifications
• Multiple Notifications
• API Notifications

Selecting Platforms

To further fine-tune your data you can filter it by selecting the platforms and status for which you want to see data. A dropdown menu at the top of the table allows you to select between the below options:

• All Platforms: See data for the selected notification type on all platforms.
• iOS: See data for the selected notification type on iOS devices.
• Android: See data for the selected notification type on Android devices.

The option you select for the platforms will affect data within the Chart and the Table.

Re-sending Failed Notifications

In some cases, you may see a notification status being Sending | Failed or Sent | Failed. In this case, the notification may have failed to deliver for some reason. We delve into this in more detail below, however, it is important to note here that you can choose to edit, duplicate, re-send, or delete such notifications by clicking on the three-dot ellipsis menu in the relevant notification row.

Creating Push Notifications

Once you have integrated the SDK, you are ready to use the Push Notifications feature. To start, click on the + New Message button at the top right corner of the page. A drawer will open up that will take you through the process of setting up your notification. The number of steps and some details are shared by notification type. In the below sections, we will go through the steps for each notification type.

Step 1: Type

In this section, all you need to do is give your campaign a name and choose the type of notification you want to use. We recommend choosing a name that is short and easy to understand. Once you've made these selections, you can save the campaign as a draft by clicking the Save as Draft button, or you can move on to the next step by clicking the Next Step button.

Step 2: Targeting

Next, you need to select the platforms to which you want to send the notification. Users on the selected platform will receive the notification. You can choose iOS, Android, or both. Simply select the checkbox next to your preferred platforms.

For One-time, Recurring, and Multiple Days Notifications, you need to add the below details fields:

• Targeting: Here, you need to select the target audience for the notification. You can choose either of the two options. The first option will select all users who have enabled push notifications, which will send your notification to all users who have agreed to receive notifications and are on the selected platform. On selecting this option, you will see the expected target group size in the same box. The second option is to target users on the basis of segmentation. If you opt for this method, you will be required to add details of the desired segmentation.
• Segmentation: If you opt for segmentation-based targeting, you will need to additionally select one of the below options, as well as select when you wish to determine the number of users:
  • Cohort(s): This will send the notification to all users within the specified Cohort(s).
  • Geolocation(s): This will send the notification to all the users within specified geographic location(s). The Geolocation feature is used for this purpose. This option is shown only if the Geolocation feature is enabled.
  • When to determine the users, i.e., whether you want to determine the users at this stage or at a later stage to identify the number of users who will receive the notification(this section is not required for multiple days notification).

For Automated Notifications, you can toggle the Geolocation selection to send push notifications to users within a set geolocation. If you opt to include this, you will need to use the dropdown to determine the targeted regions. Additionally, instead of Targeting as in the one-time notifications setup, you need to select Triggers, requiring details to be added to the below fields:

• Cohort Entry: Triggered when a user enters any of the cohorts you select.
• Cohort Exit: Triggered when a user exits from any of the cohorts you select. If one of the cohorts related options is selected, then the cohort dropdown is shown and the user selects one or more cohorts to set a trigger. It is important to note here that the Cohort(s) needs to be created prior to setting up the notification.
• Performed Event(s): Triggered when a user performs specified Events.

Selecting a specific trigger will lead to one or more of the below additional details being required:

• Delivery Date Calculation: Here, you need to determine the criterion in relation to which the delivery date will be calculated. You will need to select your preferred option between Relative to the date Event arrived to the server or to select Relative to the date Event occurred on a device.
• Behavior when Trigger condition is no longer met: This determines what happens to the push notification when the conditions of the selected trigger are no longer met, and is required for Cohorts-based triggers. You can choose Send anyway to resend the notification when a user enters or exits a Cohort for a second time. Or you can choose to Cancel when a user enters selected cohort(s) back to send the notification only the first time the user enters/exits a Cohort.
• Select one or more Events to set the Trigger: This is required for the Performed Event(s)-based trigger. Using the dropdown, select the Event (you can select more than one Event) that will trigger the push notification.

Once you have filled in these details, you can either save this notification as a draft at this point by clicking the Save as Draft button, or move on to the next step by clicking the Next Step button.

Step 3: Delivery

The Delivery step allows you to set up the scheduling and timezone details for your push notification. You are required, at this step, to fill in the below details for each type of notification.

For One-time Push Notifications:

• Delivery: You can choose any one of two scheduling options to determine when your push notification will be sent to users. Selecting the Send Now option will result in your notification being sent as soon as you complete setting it up. Select Schedule for Later if you wish to schedule this notification to be sent at any time in the future. If you select Schedule for Later, you will need to fill in the additional fields:
  • Timezone: Timezone allows you to select the time at which your users will receive the notification. You can choose to either Send to all users at the same time or Deliver in user's local timezone. In the first option, the notification will be sent at a single time that you choose, regardless of the time in the user's geolocation. In the second option, you can set a specific time and the notification will be sent to the user's device when their phone reaches that specific time. Sending push notifications based on the user’s timezone 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 timezone.
  • What if the user is past the scheduled time?: This option will become necessary when you select the option to Deliver in user's timezone. To allow for differences in time zone, you can choose to either not send the notification to users whose timezones have passed the scheduled time, or you can choose to deliver it the next day (at the same time).
• Expiration Time: Using the dropdown menus, you need to set an expiration time. The expiration time highlight the number of days after which push notifications that have been undelivered due to device connectivity issues or other errors will stop retrying to be delivered.

For Recurring Notifications:

• Delivery Timeframe: You can choose the date when you want to begin sending notifications to users using the recurring push start date picker. You also have the option to select an end date by turning on the end date toggle. If you don't turn on the end date, the notification will be sent multiple times according to the notification frequency.
• Notification Frequency: Notification frequency lets you pick how often users will get the notification. Your choices are- Daily, Weekly, or Monthly.
• Repeat for every?: This option enables you to choose the frequency at which you want the notification to appear to the user, specifying the number of days between repetitions.
• Repeat at?: With this option you can set the specific time when the notification will be sent. 
• What if the user is past the scheduled time?: This option will become necessary when you select the option to Deliver in user's timezone. To allow for differences in time zone, you can choose to either not send the notification to users whose timezones have passed the scheduled time, or you can choose to deliver it the next day (at the same time).

For Multiple Days Notifications:

• Delivery Date and Time: Here, you can choose multiple dates and times for when you'd like the notification to be shown to the user.
• Timezone: Timezone allows you to choose when your users will get the notification. You have two choices:
  • Deliver to all users at the same time sends the notification to everyone at a particular time, but this may mean users in different time zones receive it at various times of the day or night.
  • The other option sends the notification to users at a specific time in their own time zone, matching the time on their device.
• What if the user is past the scheduled time?: This option will become necessary when you select the option to Deliver in user's timezone. To allow for differences in time zone, you can choose to either not send the notification to users whose timezones have passed the scheduled time, or you can choose to deliver it the next day (at the same time).
• Expiration Time: Using the dropdown menus, you need to set an expiration time. The expiration time highlight the number of days after which push notifications that have been undelivered due to device connectivity issues or other errors will stop retrying to be delivered.

For Automated Notifications and API Notifications:

• Delivery Timeframe: Here, you can determine the start and end dates of the campaign. Automated Push Start offers two options: Start Now or Schedule; you also need to add an End Date for the campaign. Adding an end date is optional and, if added, will be the date on which the server will stop sending this notification.
• Campaign Delivery Method: You can choose when the notification should be delivered, selecting from the two options provided:
  • Immediately: Deliver the notification as soon as the triggering cohort is recalculated.
  • Delayed: Set a specific day and hour for delivery and delay delivery until that point.
• Delivery Time: You can set an optional delivery time for the notification by checking this field and selecting any time from the list.
• Capping: You can choose to configure the number of messages per user. Setting a capping limit will ensure that your notifications are not perceived as being too frequent, and that you can effectively engage with your users at optimal times. For Capping, you can choose between the below two options:
  • No capping: Message is sent whenever user entered to or exited from the cohort
  • Capped: The number of messages is limited. If you select this option, you are asked to fill in the below details additionally:
    • Maximum messages per user: Total number of messages an individual user can receive from this campaign
    • Minimum time between messages: User will be eligible to receive a repeated notification only if they trigger the campaign conditions after the minimum set period between notifications has passed.
• Expiration Time: Using the dropdown menus, you need to set an expiration time. The expiration time highlight the number of days after which push notifications that have been undelivered due to device connectivity issues or other errors will stop retrying to be delivered.

Once you have filled in these details, you can either save this notification as a draft at this point by clicking the Save as Draft button, or move on to the next step by clicking the Next Step button.

Step 4: Content and Settings

In this step, you can set up all the details of the notification itself, including its localization, buttons, URLs, and more. Many of these fields are customizable on the basis of selections and platforms. The below points explain this in more detail. Each of the below fields that need to be filled remain the same for all notification types.

Select the Notification Format

Notifications can be of two types: Message and Silent Notification. Message is the type of notification that the user sees and can take an action on. A Silent Notification is a data-only notification, in which users do not see any message nor get any notification sound when received by the user app. These push notifications are designed to keep your app's data "up-to-date" by providing a way to "wake up" the app to refresh the data in the background. Using the dropdown, you can select the type of notification you wish to send.

Composing the message and adding Media URL

Once you have selected the notification format, you need to compose the actual message, including the below details:

• Message Title: An optional title for the message.
• Message Text: Mandatory text that the message will contain, this needs to be limit the character to 4,096 for Android and 2,048 for iOS.
• Button URL: You can add a maximum of two buttons that the user can click in any notification. Add text and URL for each button. You can also choose to not include a button, in which case the user will only see a text message.
• Media URL: Media attachments are fully supported on iOS 10+, Android supports only images, and iOS 9- doesn't support media at all. In case media is not supported, users will only see message text. The URL you add here is used for both iOS and Android platforms in case of no customizations being added in Platform Settings.

Personalizing Push Notifications with Variables

All push notifications can be customized depending on the particular user receiving them. For example, you can insert a user's first name into the notification title or add their company name to the notification body.

Personalization works for any property stored by Countly in User Profiles, including custom properties, or for external properties. In both cases, click on Add Variable in either the message title or the message content to add personalized content. You have to also set a Fallback value, in case the user that is bound to receive the notification - as determined in your Targeting - lacks the value that triggers the variable (e.g., their name is not loaded). 

Different languages for different locations

You also have a built-in message localization feature in this step. Users can customize the message for every available language; alternatively, it falls back to the default message. If the user selects the localization choice, then the fields included in composing a message would be customizable for different languages.

Platform Settings

Users can customize notifications for each platform.

Customizable settings for Android

• Media URL: If the user sets a different URL for Android, a customized URL for the platform is used and Media URL in Compose Message sections is ignored.
• Sound file: Used for a custom sound for the notification.
• Add badge: Android requires additional steps (more details in our Android SDK Guide).
• Large icon: Used to include a large icon instead of default small icon. It is specific to the Android platform.
• CTA URL (On-Click URL): Default URL or deeplink which opens when a user taps a message. If the notification body is clicked, the on-click URL is opened. If an action button is clicked, the action button URL is opened.
• Send JSON: App-specific JSON data can be sent along with standard content. JSON data is mandatory for silent notifications.
• Send User Data: Select user properties to include in the notification payload.

Customizable settings for iOS

• Subtitle: It is an option specific to iOS.
• Media URL: If the user sets a different URL for iOS, a customized URL for the platform is used and Media URL in Compose Message sections is ignored.
• Sound file: Used for a custom sound for the notification.
• Add badge: iOS requires additional steps (more details in our iOS SDK Guide).
• Large icon: Used to include a large icon instead of default small icon. It is specific to the Android platform.
• CTA URL (On-Click URL): Default URL or deeplink which opens when a user taps a message. If the notification body is clicked, the on-click URL is opened. If an action button is clicked, the action button URL is opened.
• Send JSON: App-specific JSON data can be sent along with standard content. JSON data is mandatory for silent notifications.
• Send User Data: Select user properties to include in the notification payload.

Once you have filled in these details, you can either save this notification as a draft at this point by clicking the Save as Draft button, or move on to the next step by clicking the Next Step button.

Step 5: Review

In this step, you can review all the details that you have added in the previous steps. If you wish to edit anything, you need to click the Previous Step button, make the necessary changes, and move onto the next steps until you reach the review step. You can also run a test at this step. Each of the below fields that need to be filled remains the same for all notification types.

Testing your notification

You can send messages to test users on the production app, setting up test users by going to Push in Settings. You can define test users by adding user IDs or selecting cohorts from the provided list. The number of test users is shown in the review step.

Downloading review details

You can download the review page by clicking on the three-dot ellipsis menu at the top right of the review page.

Push Approver

We go into more details about the push approver a little later. However, at this stage, your next steps are determined by whether push approver is enabled or not, as follows:

If the Push Approver plugin is not enabled

When you check the confirmation message, the Complete button is enabled, the message is created, and the process is completed. Or you can save the notification by clicking the Save as Draft button. 

If the Push Approver plugin is enabled

When you check the confirmation message, the Send for Approval button is enabled, the message is created and the message is queued for approval. Alternatively, you can simply save it by clicking the Save as Draft button.

Requiring Message Approval via Approver User

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

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

Without Push Approver being enabled, Countly allows any person with User access to see notifications, and any Global Admin to create and send notifications. To make this 2-step procedure possible, the Countly user role system introduces another role - Push Approver.

After creating the notification, a user with the Push Approver role will log in and see notifications waiting for their approval located in the standard table of messages, which they can approve or delete:

It is also important to mention the right of the Push Approver user to create notifications. While the Push Approver role does not grant any more rights regarding the Push feature, meaning this user cannot create notifications, this user may also be a Global Admin. In this case, the Push Approver may create notifications, however, they will be put on hold, just like with any other type of user. One notification 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 notifications created by Push Approver 1.

The Push Approver role itself does not give any rights to the user, except for the ability to approve notifications. This means that to be able to see any notifications for a particular app, the user needs to be a User of that particular app instance.

Enabling the Push Approver feature also changes the way notifications are handled on the server. For example, in the event that a user has the right to create a notification, the notification is not sent anymore after they click on the Complete button. Instead, that button is named Send for Approval, and the notification is put on hold for a user with the Push Approver role to approve and actually send it.

Creating Transactional Messages via API

API Notifications, or Transactional Notifications as they are also known, can also be created by a second method - but using an API. To do this, you need to follow the below steps:

1. Create a Notification 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 notifications but leave any date properties as not set, as they are not applicable here. The notification you have just created will appear in the notifications table in the Scheduled state. In this state, the notification will not be sent to any users.
2. Add some users to this notification by calling /i/pushes/push with:
   • _id of the notification 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 notification 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 notification.

On date, all users defined by the specified conditions will receive this notification. 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.

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 ellipsis menu next to the Push Notification. This will launch the Push Notification table and you can then select the option to Resend Failed Notifications.

Expired Tokens

Countly cannot send a push notification for a device if that token is expired. APN, FCM, or HMS 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 Geolocation-Aware Push Notifications

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

To define the locations that are used while sending push notifications, go to Locating Targeting in Sidebar > Management. Here, 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. For more information, review the Utilities User Guide.

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 notification would be an irritation.
• Frequency of notifications is a meaningful factor: Our surveys indicate that receiving up to 8 notifications 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 notification 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.

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