Android Library/SDK


QuickStart

Google Cloud Messaging pre-requisites

Catapush Android SDK needs Google Play Services to work.

  1. Create a new GCM / FCM cloud messaging configuration
  2. Save your Server API Key and your Sender ID
  3. Save your google-services.json file in your app/ folder
  4. Go to your Catapush App configuration dashboard and select your app
  5. Add your Server API Key to your Platforms section

Gradle setup

Google Cloud Messaging

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 {
        jcenter()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:2.2.3'
        classpath 'com.google.gms:google-services:3.0.0' // To resolve Google Services 
    }
}

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

apply plugin: 'com.google.gms.google-services'

In the dependencies section, add the following line:


compile 'com.google.firebase:firebase-core:10.0.1'
compile 'com.google.firebase:firebase-messaging:10.0.1'

Catapush SDK

Add a new repository to the repositories section:

repositories {
    maven { url "https://jitpack.io" }
}

Add a new dependencies to the dependencies section:

dependencies {  
    compile('com.catapush:catapush-android-sdk:6.2.1')
}

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

Android Manifest configuration

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

Permissions

Add these permissions outside the <application> block:


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

Receivers and Service

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

<receiver
    android:name="com.catapush.library.firebase.FirebaseMessagingBroadcastReceiver">
        <intent-filter>
            <action android:name="com.google.firebase.MESSAGING_EVENT" />
        </intent-filter>
</receiver>

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

<meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version"/>

<receiver
  android:name=".MyReceiver"
  android:permission="${applicationId}.C2D_MESSAGE" >
  <intent-filter>
    <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.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.support.annotation.NonNull;
import android.util.Log;

public class MyReceiver extends CatapushTwoWayReceiver {

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

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

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

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

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

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

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

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

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

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

Initialization

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

import com.catapush.library.Catapush;
import com.catapush.library.interfaces.Callback;

import android.app.Application;
import android.util.Log;

public class App extends Application {

    @Override
    public void onCreate() {
        super.onCreate();

        Catapush.getInstance().init(this, new Callback<Boolean>() {
            @Override
            public void success(Boolean result) {
                Log.d("MyApp", "Catapush has been initialized: " + result);
            }

            @Override
            public void failure(Throwable t) {

            }
        });
    }
}

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

    <application
            android:allowBackup="true"
            android:icon="@mipmap/ic_launcher"
            android:name=".App"
            android:label="@string/app_name"
            android:theme="@style/AppTheme">

Start

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()
.swipeToDismissEnabled(false)
.title(YOUR NOTIFICATION TITLE)
.vibrationEnabled(true)
.vibrationPattern(new long[]{100, 200, 100, 300})
.soundEnabled(true)
.soundResourceUri(sound)
.circleColor(NOTIFICATION ICON BACKGROUND COLOR) // Check out the Customization section below
.ledEnabled(true)
.ledColor(Color.BLUE)
.ledOnMS(2000)
.ledOffMS(1000)
.build();

Catapush.getInstance()
.setPush(notification)
.setAppKey(YOUR_APP_KEY_FROM_CATAPUSH_DASHBOARD)
.setGcmSenderId(YOUR_GCM_SENDERID_FROM_GOOGLE_DEVELOPERS_DASHBOARD)
.setUser(CATAPUSH_USER, CATAPUSH_PASSWORD)
.start();

Advanced

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 using:

Catapush.getInstance().disableNotifications();

Note: disabling 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 enable/disable 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() {
    super.onResume();
    // Our app is open and we don't want status bar notification in this scenario
    Catapush.getInstance().disableNotifications();
}

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

@Override public void onPause() {
    super.onPause();
    // Our app is not visible and we want status bar notification in this scenario
    Catapush.getInstance().enableNotifications();
}

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:

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

    Intent intent = new Intent(context, MainActivity.class);
    intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_SINGLE_TOP);
    context.startActivity(intent);
}        

Sending Read Notification Receipt Manually

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

Catapush.getInstance().notifyMessageOpened(catapushMessage.id());

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();
recyclerView.setAdapter(adapter);
Catapush.getInstance().getMessagesAsList(new Callback<List<CatapushMessage>>() {
@Override
public void success(List<CatapushMessage> catapushMessages) {
adapter.set(catapushMessages);
}

@Override
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:

adapter.setClipboardToast(false);

Messages containing urls

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

  • www.google.com
  • http://www.google.com
  • google.com

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

adapter.setUrlInPlainMessagesClickable(false)

Customization

Colors

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:

 

Text

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>

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

<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>
</style>

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:

 

Corners

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()
.swipeToDismissEnabled(false)
.title(view.getString(R.string.app_name))
.vibrationEnabled(true)
.vibrationPattern(new long[]{100, 200, 100, 300})
.soundEnabled(true)
.soundResourceUri(sound)
.circleColor(circleColor)
.ledEnabled(true)
.ledColor(Color.BLUE)
.ledOnMS(2000)
.ledOffMS(1000)
.build();

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:

<com.catapush.library.SendFieldView
android:id="@+id/send_container"
android:layout_width="match_parent"
android:layout_height="60dp"/>

SentFieldView_example.png

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>

FAQ

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.