Android Push Quick Start

Get Push up and running in your Android App using Gimbal.

Setup Gimbal Application

Important This guide assumes you have a Android project setup with Gimbal. Please follow Gimbal Quick Start guide if you have not yet setup an Android project with Gimbal.

Gimbal Android Quickstart »

Google Cloud Messaging (GCM)

Gimbal uses Google Cloud Messaging (GCM) for enabling push on Android. In order to use GCM you'll have to setup your application on Google Cloud Console and obtain a Server API key (Google Cloud Messaging Key) and generate a Sender ID. Please refer to GCM getting started and follow the steps to generate these keys. Here's an overview of the steps you'll have to follow:

If you are using old Google API console page

  • Create an Google API project
  • Note the value after #project: present in browser URL. This is used as Sender ID
  • Turn on Google Cloud Messaging from Services menu
  • Select API access from Google APIs console
  • Click on Create a new Server key
  • Make note of the newly generated Server API key

If you are using new Google Cloud Console

  • Create a new project
  • Note the Project Number on the newly created project detail page. This is used as Sender ID
  • Turn on Google Cloud Messaging from APIs & auth menu
  • Register a new Web Application from Registered apps menu
  • Make note of the newly generated API key from Server Key section on Registered App detail page

Note Before moving forward make sure that you have obtained the Server API key and Sender ID (project number) from Google Cloud console. Also ensure that Google Cloud Messaging for Android is enabled for your application.

Enable Gimbal Push

Once you have obtained the Server API key (Google Cloud Messaging Key) and Sender ID from Google Cloud Console for you application follow these steps to enable Push on Android using Gimbal

Add Google API to Gimbal Manager

On Gimbal Manager, go to your existing Android application and click on Configure to setup Android push. Enter the Server API Key (Google Cloud Messaging Key) and save. Now your application on Manager is set to send push messages to your Android application running on the device.

Configuring the Client Application

Add Google Play Services

Google Play service is used on the client to enable receiving push messages. Add Google Play Services apklib project as a library to your existing application. Google has detailed instructions here to set it up. Here's an overview of the steps you'll have to follow:

  • Download Google Play Service from Android SDK Manager
  • Import google-play-services_lib project in Eclipse as existing android project (Usually found at <android-installation>/extras/google/google_play_services/libproject/google-play-services_lib)
  • Add a reference to the apklib project on your project. Detailed instructions here.

Application Manifest Changes

Edit your application's AndroidManifest.xml file, and add the following declaration within the <application> element. This embeds the version of Google Play services that the app was compiled with.

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

Also add these permissions to your application's AndroidManifest.xml file (in addition to all permissions needed by Gimbal) to allow Google to send push messages to your application.

    <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
    <permission android:name="com.companyname.applicationname.gcm.permission.C2D_MESSAGE" android:protectionLevel="signature" />
    <uses-permission android:name="com.companyname.applicationname.gcm.permission.C2D_MESSAGE" />

Note Make sure to change "com.companyname.applicationname" to your application's package name in above permissions.

Register for Push Notifications

Once Gimbal is enabled in your application you can tell Gimbal your application is interested in receiving Push Messages. You can make a call to ContextPushNotificationsConnector.registerForRemoteNotification to register with Gimbal to receive Push. SENDER_ID is the project number that was generated when you created a project on Google Cloud Console.


    contextCoreConnector.enable(this, new Callback() {
        @Override
        public void success(Void responseObject) {
            ContextPushNotificationsConnector.registerForRemoteNotification(context, SENDER_ID);
        }

        @Override
        public void failure(int statusCode, String errorMessage) {
            //Failed
        }
    });
                

Receive Push Content

In order to receive Push Content, create an instance of ContextCoreConnector or use the instance that was created earlier and add an implementation of ContentListener to it. Whenever a push is sent to the client, Gimbal will call your application on ContentListener.contentEvent. Your application can now decide whether or not to raise a notification to the User.

                
    ContextCoreConnector contextCoreConnector = ContextCoreConnectorFactory.get(context);
        contextCoreConnector.addContentListener(new ContentListener() {
        @Override
        public void contentEvent(ContentEvent contentEvent) {
            // Push Content Received
        }
    });
                  

Note If you want your Listener to survive service/device restart, then make sure you have an Android Service in your application that is started as STICKY and the above code is executed in onCreate of the service.

Note In order to send Push only to users in certain geofences, you'll have to add place.state.available.on.server=true to usercontext.properties in your application.

Schedule Time Triggered Push

You are ready to schedule a Time Trigerred Push to the client. Make sure you run your application on a device and enable Gimbal. Go to the Communication tab on Gimbal Manager to send a Time Trigerred Push. Click on Add Communication on the right and select Communication.

Go to the Triggers tab and select triggers type to 'Time'. You will be able schedule time triggered push here.

Send Instant Push

You are ready to send an Instant Push to the client. Make sure you run your application on a device and enable Gimbal. Go to the Communications tab on Gimbal Manager to send an Instant Push. Click on Add Communication on the right and select Instant Communication.

On the next page fill in the details of your push message and click on Save & Publish to send your Instant Communication to your device.

Learn More

For additional details on how to leverage the SDK functionality, refer to the sample applications and documentation included in the zip file provided.

Detailed Gimbal Android Guide »