Android Library/SDK


Firebase Cloud Messaging pre-requisites

Catapush Android SDK needs Firebase to work.

  1. Create a new Project in Firebase Console and obtain your Server Key and your Sender ID
  2. Save your google-services.json file in your app/ folder
  3. Go to your Catapush App configuration dashboard and select your app by clicking "View Panel"
  4. In Platforms section add your Server API Key to your Android configuration

Gradle configuration

The Google Services plugin for Gradle parses configuration information from the google-services.json file. Add the plugin to your project by updating your app build.gradle file as follows:

buildscript {
    repositories {
    dependencies {
        classpath ''
        classpath '' 

At the bottom of build.gradle, add the following line:

apply plugin: ''

In the dependencies section, add the following line:

implementation ''
implementation ''

Catapush SDK

Add a new repository to the repositories section:

repositories {
    maven { url "" }

Add a new implementation:

implementation ('com.catapush:catapush-android-sdk:7.4.24') {
    exclude group: 'org.jetbrains', module: 'annotations'

Catapush follows Semantic Versioning rules, so you can safely replace the static version dependency with a dynamic 7.+ one.

Android Manifest configuration

To properly run Catapush, you need to add a few setup lines to your AndroidManifest.xml file.


Catapush requires the following permission usages to be declared in your app's AndroidManifest.xml

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

App key

Declare this meta-data inside the application node of your AndroidManifest.xml

   android:value="YOUR_APP_KEY" />

YOUR_APP_KEY is the AppKey of your Catapush App (go to your Catapush App configuration dashboard, select your App by clicking "View Panel" and then click on App details section)

Receivers and Service

In the <application> block, just before the closing tag, add these lines:

            <action android:name="" />

<service android:name="com.catapush.library.MessagingService" android:label="YOUR_MESSAGE_CENTER_LABEL" />

<meta-data android:name="" android:value="@integer/google_play_services_version"/>

  android:permission="${applicationId}.C2D_MESSAGE" >
    <action android:name="com.catapush.library.action.MESSAGE_RECEIVED"/>
<action android:name="com.catapush.library.action.MESSAGE_OPENED"/>
<action android:name="com.catapush.library.action.MESSAGE_SENT"/>
<action android:name="com.catapush.library.action.MESSAGE_SENT_CONFIRMED"/>
<action android:name="com.catapush.library.action.NOTIFICATION_CLICKED"/>
<action android:name="com.catapush.library.action.RELOGIN_NOTIFICATION_CLICKED"/>
<action android:name="com.catapush.library.action.INVALID_LIBRARY"/>
<action android:name="com.catapush.library.action.CONNECTING"/>
<action android:name="com.catapush.library.action.CONNECTED"/>
<action android:name=“com.catapush.library.action.NETWORK_ERROR” />
<action android:name="com.catapush.library.action.DISCONNECTED"/> <category android:name="${applicationId}"/> </intent-filter> </receiver>

Create a receiver

To communicate with Catapush, you can extend CatapushReceiver and implement the needed methods. You can copy/paste the following class:

import com.catapush.library.CatapushTwoWayReceiver;
import com.catapush.library.exceptions.CatapushAuthenticationError;
import com.catapush.library.messages.CatapushMessage;

import android.content.Context;
import android.content.Intent;
import android.util.Log;

public class MyReceiver extends CatapushTwoWayReceiver {

public void onConnecting(Context context) {
Log.d("MyApp", "Connecting...");

public void onConnected(Context context) {
Log.d("MyApp", "Connected");

public void onMessageReceived(@NonNull CatapushMessage catapushMessage, Context context) {
Log.d("MyApp", "Received Message: " + catapushMessage);

public void onMessageOpened(@NonNull CatapushMessage catapushMessage, Context context) {
Log.d("MyApp", "Opened Message: " + catapushMessage);

public void onMessageSent(@NonNull CatapushMessage catapushMessage, Context context) {
Log.d("MyApp", "Message marked as sent");

public void onMessageSentConfirmed(@NonNull CatapushMessage catapushMessage, Context context) {
Log.d("MyApp", "Message sent and delivered");

public void onNotificationClicked(@NonNull CatapushMessage catapushMessage, Context context) {
Log.d("MyApp", "Notification clicked: " + catapushMessage);

public void onReloginNotificationClicked(Context context) {
Log.d("MyApp", "Authentication lost. Need to relogin");

public void onRegistrationFailed(@NonNull CatapushAuthenticationError error, Context context) {
Log.e("MyApp", "Error Message: " + error.getReason());

public void onDisconnected(int errorCode, Context context) {
Log.d("MyApp", "Disconnected: " + errorCode);


You can initialize Catapush in your class that extends Application. Your onCreate() method should contains the following lines:

public class App extends MultiDexApplication {

    private static final String NOTIFICATION_CHANNEL_ID = "";

    public void onCreate() {

        Catapush.getInstance().init(this, NOTIFICATION_CHANNEL_ID, getString(R.string.notifications_default_channel_name),
                new Callback<Boolean>() {
                    public void success(Boolean response) {
                        Log.d("APP", "Catapush has been successfully initialized");

                    public void failure(Throwable t) {



From version 6.6.0 the method Catapush.getInstance().init() has been updated with two additional parameters to better comply with the new Android Oreo requirements regarding notification channels:

  • channelId: The id of the notification channel. Must be unique per package. The value may be truncated if it is too long.
  • channelName: The user visible name of the channel. You can rename this channel when the system locale changes by listening for the Intent.ACTION_LOCALE_CHANGED broadcast. The recommended maximum length is 40 characters; the value may be truncated if it is too long.

If you are creating the class App that extends Application for the first time, remember to add it to your AndroidManifest.xml:



Catapush setup is complete. Whenever you want to start using Catapush, you just need to call the start() method. For instance, in your main Activity, after your user has logged in, you can use the following code to customize a Notification and start Catapush:

Uri sound = RingtoneManager.getDefaultUri(RingtoneManager.TYPE_ALARM);

Notification notification = Notification.builder()
.vibrationPattern(new long[]{100, 200, 100, 300})
.circleColor(NOTIFICATION ICON BACKGROUND COLOR) // Check out the Customization section below


  • CATAPUSH_USER is the user Identifier present in Users section of the Catapush App dashboard
  • CATAPUSH_PASSWORD is the user Password present in Users section of the Catapush App dashboard


Notification management

By default Push Notifications visualization is managed by the Catapush library, which builds Notifications and displays them in the notification bar with your UI settings.

Disable Push Notification Visualization

You can choose to disable Push Notifications visualization permanently using:


And re-enable them using:


This state will be persisted and preserved across app restarts and Catapush starts/stops.

Note: disabling Push Notifications does not stop receiving messages, but you have to handle Open Notification feedback by your own.

Pause Push Notification Visualization

You can choose to disable Push Notifications visualization temporarily using:


And re-enable them using:


This state will not be persisted. If you restart your app or stop/start Catapush the push notifications visualization will be resumed.

Note: pausing Push Notifications does not stop receiving messages, but you have to handle Open Notification feedback by your own.

Hide Notifications when User is in your Messages List

It is also useful to pause/resume Push Notifications visualization when your Message list is active and visible.

You can disable and enable them as in the following example, taking advantage of your Activity lifecycle methods:

@Override public void onResume() {
    // Our app is open and we don't want status bar notification in this scenario

Enable Push visualization when the user close your Message Thread list, e.g. ListActivity:

@Override public void onPause() {
    // Our app is not visible and we want status bar notification in this scenario

Notification Visualization

When you decide to use Android system Notification provided by Catapush, you can detect the click on the notification with your MyReceiver class. In the following example, when the user clicks the notification, an onNotificationClicked event is triggered and the appropriate CatapushMessage is passed as argument. The example shows how to start an Activity on this click event:

public void onNotificationClicked(CatapushMessage catapushMessage, Context context) {
    Log.d("MyApp", "Opened Message: " + catapushMessage);

    Intent intent = new Intent(context, MainActivity.class);

Sending Read Notification Receipt Manually

If you decide to disable default Push Notification management, you have to manually report every message opening:


Advanced UI

Catapush SDK comes with a native ready-to-go solution to display your messages.

Catapush RecyclerView Adapter

Catapush SDK provides full support for RecyclerView via CatapushRecyclerViewAdapter. This adapter can receive a list of messages and display them in a stylish bubble cell:


adapter = new CatapushRecyclerViewAdapter();
Catapush.getInstance().getMessagesAsList(new Callback<List<CatapushMessage>>() {
public void success(List<CatapushMessage> catapushMessages) {

public void failure(Throwable throwable) {
Log.e("MyApp", throwable.getMessage());

Toast on copy to clipboard

Catapush gives you the opportunity to copy a message content to the clipboard using long click. Every time you copy a message, a Toast message appears. You can disable this toast message with:


Messages containing urls

Catapush gives you the opportunity to send messages containing URLs, like these


A message containg an URL is clickable and default web browser will take care of opening the URL. You can disable this behavior with:




Catapush provides a default color scheme that you can override to achieve the user experience you want. To customize the color scheme, you will need to create these colors in your res/values/colors.xml:

<color name="catapush_message_list_item_bg">#b6e6ed</color>
<color name="catapush_message_border_color">#b6e6ed</color>

<color name="catapush_message_title_color">#ff0000</color>
<color name="catapush_message_subtitle_color">#999292</color>
<color name="catapush_message_datetime_color">#ff9d9d9d</color>

Changing these colors, you will change the previous image into this:



Catapush provides a default text style that you can override to achieve the user experience you want. To customize the text, you will need to create these styles in your res/values/styles.xml

<style name="catapush_message_title" parent="android:Widget.TextView">
  <item name="android:singleLine">false</item>
  <item name="android:textColor">@color/catapush_message_title_color</item>
  <item name="android:textSize">@dimen/catapush_message_title_size</item>
  <item name="android:typeface">sans</item>
  <item name="android:textStyle">normal</item>

<style name="catapush_message_subtitle" parent="android:Widget.TextView">
  <item name="android:textColor">@color/catapush_message_subtitle_color</item>
  <item name="android:textSize">@dimen/catapush_message_list_item_subtitle_size</item>
  <item name="android:textStyle">bold</item>
  <item name="android:typeface">sans</item>

<style name="catapush_message_datetime" parent="android:Widget.TextView">
  <item name="android:textColor">@color/catapush_message_datetime_color</item>
  <item name="android:textSize">@dimen/catapush_message_list_item_datetime_size</item>
  <item name="android:textStyle">italic</item>
  <item name="android:typeface">sans</item>

These styles relay on colors and dimensions. You can override Catapush default dimensions adding these values to your res/values/dimens.xml file:

<dimen name="catapush_message_title_size">22sp</dimen>
<dimen name="catapush_message_list_item_padding">5dp</dimen>
<dimen name="catapush_message_list_item_subtitle_size">12sp</dimen>
<dimen name="catapush_message_list_item_datetime_size">6sp</dimen>

Changing these dimensions like this will produce this result:



Catapush message bubbles come with rounded corners. You can change them overriding this property in your res/values/dimens.xml file:

<dimen name="catapush_message_corner_radius">10dp</dimen>

If you don't want rounded corners at all, simply set it to 0dp.


Notification icon

By default, Catapush shows your notification icon with a grey background. During the setup time, this color can be customized:

Notification notification = Notification.builder()
.vibrationPattern(new long[]{100, 200, 100, 300})

The previous snippet shows a typical configiration of Catapush notification. The highlighted line shows how to customize the icon background color. circleColor can be any ARBG int value, for example:

int circleColor = ContextCompat.getColor(context, R.color.accent)

Sending messages

Catapush provides the possibility to let your users sent you messages. Just add a SendFieldView to your layout, like this:



SendFieldView colors can be customized like this:

<color name="catapush_sentfield_border_color">YOUR COLOR</color>
<color name="catapush_sentfield_bg_color">YOUR COLOR</color>


Which is the minimum supported Android API?

Catapush supports Android API 16 (Jelly Bean) and greater. For details about Android versions distribution, you can check Android Dashboards.

What's the size of the library?

Catapush is less than 400KB and we try to keep the methods count as smallest as possible, too.

What are battery and bandwidth usages?

Catapush works hard to be a good citizen. In a test environment, with new messages received hourly, Catapush has proved to use less than 1% of battery and less than 100KB/day. In everyday scenarios, with low or zero message traffic, Catapush uses even less battery and the data traffic is near to 0KB/day.

There is an example project available?

You can download an example project here.