Skip to content

Latest commit

 

History

History
147 lines (111 loc) · 5.3 KB

push.adoc

File metadata and controls

147 lines (111 loc) · 5.3 KB

Aerobase Service Push SDK

Aerobase for Android provides support for integrating Firebase Cloud Messaging (FCM) with the Aerobase Server.

Push messaging is a mechanism for sending data to mobile clients from a remote server. For mobile applications, this reduces battery usage, removes polling code and provides for a better user experience as data changes are communicated in real time.

Messages that FCM receives from an application server are sent to the Android device over a connection managed by the operating system. These messages are then extracted and passed to an application using services definied provided by the Aerobase library.

Boilerplate example

For a full example, see our example projects on Github.

Adding dependency

Add the push dependency to your application module

implementation "org.aerobase:android-push:[version]"
implementation "com.google.firebase:firebase-messaging:[version]"

Firebase setup

In order to receive push messages you need to setup the Firebase in your project.

  1. Create a new project in Firebase console

  2. Add The Google Services Gradle Plugin in your root build.gradle file

buildscript {
    dependencies {
        classpath 'com.google.gms:google-services:[version]'
    }
}

  1. Apply the plugin in your app build.gradle file

// ADD THIS AT THE BOTTOM
apply plugin: 'com.google.gms.google-services'

  1. Download the google-services.json from Firebase console and drop it into your app folder

See the complete guide in the Firebase website

Aerobase Configuration file

A mobile-services.json file must exist in the apps assets directory. It should specify configuration for Aerobase Server. This configuration can be generated by the AeroGear Mobile CLI.

For an example of push configuration see example apps mobile-services.json.

Registering with Aerobase Server

This example demonstrates how to register a device to provide the values required to register the application with FCM and Aerobase and perform the registration.

PushService pushService = MobileCore.getInstance().getService(PushService.class);

pushService.registerDevice(new Callback() {
    @Override
    public void onSuccess() {
        // Yay
    }

    @Override
    public void onError(Throwable error) {
        // Oops!
    }
});

You also can add some optional parameters using UnifiedPushConfig

UnifiedPushConfig unifiedPushConfig = new UnifiedPushConfig();
unifiedPushConfig.setAlias("Aerobase");
unifiedPushConfig.setCategories(Arrays.asList("Android", "OpenShift"));

pushService.registerDevice(unifiedPushConfig, yourCallback);

If you want to add option for user to stop receiving notifications.

PushService pushService = MobileCore.getInstance().getService(PushService.class);
pushService.unregisterDevice(new Callback() {
    @Override
    public void onSuccess() {
        // yay
    }

    @Override
    public void onError(Throwable error) {
        // Oops!
    }
});

Handling messages

MessageHandler is responsible for handling the messages received from FCM. It will give you total flexibility to decide what to do with the message recieved.

Receiving Background and Foreground Messages

Currently, push messages are received by an instance of AeroGearFirebaseMessagingService. The messages are processed and passed to PushService.notifyHandlers.

Classes which implement MessageHandler can ask that their methods be called on either the UI thread using PushService.registerMainThreadHandler or on a background thread using PushService.registerBackgroundThreadHandler. UI threads are most useful for Activities and Fragments; background threads are most useful for everything else.

In an Activity (or in a Fragment) you must remove the handler when the Activity goes into the background and must reenable it when it comes into the foreground.

@Override
public void onStart() {
    super.onStart();
    PushService.registerMainThreadHandler(this);
    PushService.unregisterBackgroundThreadHandler(myBackgrondHandlerInstance);
}

@Override
public void onStop() {
    super.onStop();
    PushService.unregisterMainThreadHandler(this);
    PushService.registerBackgroundThreadHandler(myBackgrondHandlerInstance);
}

Default handler

Unfortunately when you close or kill the app the Android system can destroy the PushService instance and we will lose the handler you have added there. To solve this we provide a way to register a default handler, it will be used when app is not running (actually running in background) and there are no others handlers registered.

AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest>
    <application>
        <meta-data
            android:name="DEFAULT_MESSAGE_HANDLER_KEY"
            android:value="package.ClassName" />
    </application>
</manifest>