. . .

Android Tutorial Push

This toturial will walk through how to build an Android app with the ability to receive push notifications. This entails creating a new Android app, enabling the Google Cloud Messenger, preparing ApiOmat as well as setting up a basic layout and some code.

Creating a new Android App

Open your IDE. We recommend using Android Studio, as that is what we will be using for this tutorial.

Select Start A new Android Studio Project or if you want to enhance an existing project, choose Open an existing Android Studio Project, as shown in the figure below.


If you've decided to create a new project, you will have to setup a few basics, which will be covered in the next 4 screens. If you are using an existing project you can skip right to the step Enable GCM for your app. First you will enter your app's name and a company domain. You will need this information later.


Next, you'll have to pick the android devices and the minimum API levels you are targeting with your app. Please note that you'll need to choose at least API level 9 to be able to use Google's GCM.


Next, decide what kind of activity your app initially should contain. For this tutorial, select the Blank Activity.


Next, set your activity's name, and respectively your activity's title and the layout's name. The name will not effect this tutorial, so we will just leave it as the default as it plays a subordinate role for our use case. Keep the defaults and finish setting up the project by clicking the finish button.


To send push messages to an Android device you have to use the Google Cloud Messaging Service , requiring you to obtain a server API key. The next part of the tutorial will walk you through signing up for GCM.

Enable GCM for your app

Please note that a Google account is required in order to enable the GCM service.

Go to the Enable Google Services for your app section of Google's developer site.

As shown in Figure 01: To create or choose an app you will have to enter your app's name and the corresponding package name. Please make sure that these values are matching those of your app's manifest.

Figure 01: Create or choose an app

Now you can choose and configure your app's services by clicking the button at the bottom.

You can activate other services in addition to cloud messaging, but other services are not required for this tutorial.

Figure 02: Choose and configure services.


Click on the button ENABLE GOOGLE CLOUD MESSAGING, to see your Server API key.

Instead of copying and pasting, you can use the generated config file. Simply click the button at the bottom one more time.


Click on Download google-services.json the .json file includes all the generated values and can be added to your project's app-folder.


Setting up the Backend

1.Log into your account.


2. If you haven‘t created an app yet, you will be asked to give your first app a name and to give a short description. In our example the app is called “Facebook”. For your app, though, you should use a unique name.


3.Now you see the Apiomat Dashbaord. Start on the Module Market with all the available modules you can add to your app. Scroll down and select the Push Module and click "+" to add the module.


4. A pop-up will appear where we can configure the Push module. Insert your GCM API project key and confirm with “OK”.


5. Now we have to deploy our backend, to do this, we click on the slider next to "INACTIVE".

6. Click on the SDK tab on the menu at the top of the screen. This will take you to an overview of the ApiOmat SDKs, which you can download by clicking "DOWNLOAD SDK".

7. For this tutorial you will need the SDK for Android. To download, simply click the button “Download SDK”. This downloaded .ZIP file contains all required classes and resources. Unpack the .ZIP file and save it somewhere on your hard disk.


9. Open the folder containing the unpacked .ZIP file.

10. Copy both of the folders into the “src” folder (source) of your app. Now we can get started on the frontend!

Configure your App

Now you need the configuration file which you downloaded while Enabling GCM for our app. Simply copy the file into the app-Folder of your app-project. As this file is intended to be parsed by the Google Services plugin for Gradle, we have to install this plugin first. You can do this by adding a dependency into your gradle files.

  1. Insert the following line into the build.gradle file in the root folder of your project.

classpath 'com.google.gms:google-services:2.0.0-alpha6'

2. Add the plugin into the build.gradle file in the app folder of your project

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

Next, install the Google Play services SDK. Go to the SDK manager in Android studio, select the SDK Tools tab and install the latest version of the Google Play Services. After the installation is finished, add the following dependency to your app's build.gradle located in your app folder.

dependencies {
compile "com.google.android.gms:play-services-gcm:8.3.0"

Creating the Layout

Next you need to put together a simple layout in order to to be able to trigger the GCM registration. You'll find the XML code below, where the two most important elements are a TextView with the id txt_push and a Button with the id btn_push. You will use those ids later.

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  app:popupTheme="@style/AppTheme.PopupOverlay" />
  android:text="No message recevied yet." />

Writing Code

First, you need to handle the GCM registration. Instantiate the service if no registration token was found. Save the registration token to shared preferences and create a new ApiOmat user with this token within the method on HandleIntent. Finally, save this user.

public class RegistrationIntentService extends IntentService
private static final String TAG = "RegIntentService";
public static final String APIOMAT_PREFERENCES_GCM_TOKEN = "GCM_TOKEN";
public RegistrationIntentService()
public void onHandleIntent(Intent intent)
final InstanceID instanceID = InstanceID.getInstance(this);
final String token = instanceID.getToken(getString(R.string.gcm_defaultSenderId), GoogleCloudMessaging.INSTANCE_ID_SCOPE, null);
final SharedPreferences prefs = this.getSharedPreferences(APIOMAT_PREFERENCES, this.MODE_PRIVATE);
final SharedPreferences.Editor editor = prefs.edit();
editor.putString(APIOMAT_PREFERENCES_GCM_TOKEN, token);
createUser(token, this);
catch (Exception e)
Log.e(TAG, e.getMessage());
public static void createUser(String token, final Context ctx)
final User user = new User();
user.saveAsync(new AOMEmptyCallback()
  public void isDone(boolean wasLoadedFromStorage, ApiomatRequestException exception)
Toast.makeText(ctx, "Registration sucessful", Toast.LENGTH_SHORT).show();

We also need a service to handle a server side token refresh. Simply create a file called InstanceIDService.java and paste the code below.

public class InstanceIDService extends InstanceIDListenerService
private static final String TAG = "MyInstanceIDLS";
public void onTokenRefresh()
final Intent intent = new Intent(this, RegistrationIntentService.class);

Next we will create a service that handles the reception of push messages. When a push message is recieved, we send a broadcast that will be handled in our main activity and displayed in our text view.

public class GCMPushReceiverService extends GcmListenerService
public static final String INTENT_ID = "GCMIntent";
public static final String INTENT_DATA_ID = "GCmIntentData";
private static final String TAG = GCMPushReceiverService.class.getName();
public void onMessageReceived(String from, Bundle data) {
final String message = data.getString("payload");
final Intent intent = new Intent(INTENT_ID);
intent.putExtra(INTENT_DATA_ID, message);

Last but not least, you need to extend the main activity as shown below. If you haven't recieved a token yet, click on the previously defined button to request a new function. Otherwise, hide the button and only show push messages in the text field.

public class MainActivity extends Activity
private static final String REGISTRATION_SUCCESS = "RegistrationSuccess";
private static final String REGISTRATION_ERROR = "RegistrationError";
private BroadcastReceiver receiver;
public TextView push_message;
private Button push_button;
private Context ctx;
protected void onCreate(Bundle savedInstanceState)
push_message = (TextView) findViewById(R.id.txt_push);
push_button = (Button) findViewById(R.id.btn_push);
ctx = this;
receiver = new BroadcastReceiver()
public void onReceive(Context context, Intent intent)
final IntentFilter filter = new IntentFilter();
registerReceiver(receiver, filter);
final String token = this.getSharedPreferences(RegistrationIntentService.APIOMAT_PREFERENCES, MODE_PRIVATE).getString(RegistrationIntentService.APIOMAT_PREFERENCES_GCM_TOKEN, "");
push_button.setOnClickListener(new View.OnClickListener()
public void onClick(View v)
final Intent intent = new Intent(ctx, RegistrationIntentService.class);
protected void onResume()
protected void onPause()

Asking for Permission

An Android app is not allowed to do anything by default. So to access the internet, you have to ask for permission. You can request this in the Android Manifest.

1. Open the AndroidManifest.xml in your app's root folder.

2. Add this line after the <manifest [...]> tag:

<!-- App receives GCM messages.-->
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE"></uses-permission>
<!-- GCM connects to Google Services.-->
<uses-permission android:name="android.permission.INTERNET"></uses-permission>
<!-- GCM requires a Google account.-->
<uses-permission android:name="android.permission.GET_ACCOUNTS"></uses-permission>
<!-- Keeps the processor from sleeping when a message is received.-->
<uses-permission android:name="android.permission.WAKE_LOCK"></uses-permission>

3. Enter the following two permissions, but replace "my_app_package” with your app's package name:

<permission android:name="my_app_package.permission.C2D_MESSAGE" android:protectionLevel="signature"></permission>
<uses-permission android:name="my_app_package.permission.C2D_MESSAGE"></uses-permission>

4. Assign the GCMPushReceiverService as a child node of “application”. For details on this service please see the section above.

<service android:name=".GCMPushReceiverService" android:exported="false" >
<action android:name="com.google.android.c2dm.intent.RECEIVE" />

5. In addition to the GCMPushReceiverService, we also need to add the InstanceIDService, which must also be added as a child node of "application" :

<service android:name=".InstanceIDService" android:exported="false">
<action android:name="com.google.android.gms.iid.InstanceID"/>

6. You also need a BroadcastReceiver, which also has to be a child element of “application”:


Let’s go!

To test our app, Send the push message from the ApiOmat dashboard.

1. Start the app on your Android device.


2. Press the button “Prepare”. A toast saying: “Registration successful” should emerge. The device is now registered at GCM.
3. Open the dashboard of ApiOmat.
4. Click the tab My Modules and then the button “Push”.

5. Click “Send”.
6. Check out your Android app. The text field should contain the push message you entered. In our case it was the message "Test!".