Skip to content

Gravitum Push Android

Jump to bottom
Gravitum edited this page Dec 22, 2016 · 15 revisions

Push Notifications

Push notifications are an easy way for developers and marketers to send short, real-time, messages to users with announcements, news, or events. They are a feature built into mobile devices, web browsers, and operating systems. If you are here, you are interested in push notifications for Android mobile platform.

IMPORTANT: Please make sure you have your GCM Setup before you proceed.

Let's start the push notifications setup for the Admin Section now that you have the Server API Key from the previous GCM section setup.

Select Projects in Admin Dashboard

Select List in Project sections

Select the Android Icon

Enter your Android Push Token which you received in the previous GCM Section setup.

Let's move to the push notifications setup in the required AndroidManifest.xml tags for Gravitum SDK. You have to add two Gravitum services and one receiver in your main AndroidMaifest.xml file.

Important: All the {YOUR APP BUNDLE ID} places should be replaced with your own application bundle ID.

<receiver android:name="com.gravitum.messaging.CloudMessagingReceiver" android:exported="true" android:permission="com.google.android.c2dm.permission.SEND" >
  <intent-filter>
    <action android:name="com.gravitum.messaging.OPEN" />
    <action android:name="com.google.android.c2dm.intent.RECEIVE" />
    <category android:name="{YOUR APP BUNDLE ID}" />
  </intent-filter>
</receiver>

<service android:name="com.gravitum.messaging.CloudMessagingService" android:exported="false" >
  <intent-filter>
    <action android:name="com.google.android.c2dm.intent.RECEIVE" />
  </intent-filter>
</service>

<service android:name="com.gravitum.messaging.CloudRegistrationService" android:exported="false">
</service>

The permissions required by Gravitum are listed below

<permission android:name="{YOUR APP BUNDLE ID}.permission.C2D_MESSAGE" android:protectionLevel="signature" />

<uses-permission android:name="{YOUR APP BUNDLE ID}.permission.C2D_MESSAGE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.INTERNET" />

Gravitum SDK records two push message events: 1)when the notification is sent to the user and 2) when the user taps on the notification and the app will open up.

The use-case for received push listener is following:

Analytics.SetReceivedPushListener(new IReceivedPushMessageListener() {
            @Override
            public void onReceived(int id, String title, String subtitle, String content, boolean isAppForeground, JSONObject json) {
                Log.d("Gravitum", "!!!PUSH RECEIVED!!! " + Integer.toString(id) + "|" + title + "|" + content + "|" + Boolean.toString(isAppForeground) + "|" + json.toString());
            }
        });

The use-case for launched push listener is following:

Analytics.SetLaunchPushListener(new ILaunchedPushMessageListener() {
            @Override
            public void onLaunched(int id, String title, String subtitle, String content, JSONObject json) {
                Log.d("Gravitum", "!!!PUSH LAUNCHED!!! " + Integer.toString(id) + "|" + title + "|" + content + "|" + json.toString());
            }
        });

Important: Make sure, that all these setters have been called before Analytics.Init. Let's take a look at all the parameters you will get to your listener onReceived and onLaunched methods. They are the same, despite the boolean isAppForeground. This parameter doesn't exist in ILaunchedPushMessageListener, just in IReceivedPushMessageListener.

Parameters

int id - notification ID. This is unique identifier for every notification.

String title - the title of the notification. You can use this value if you want to make your own in-game notification UI.

String subtitle - the subtitle of the notification. You can use this value if you want to make your own in-game notification UI.

String content - the content or, in other words, message of the notification. You can use this value if you want to make your own in-game notification UI.

JSONObject json - custom additional data that was sent with the notification. Set on the Gravitum Dashboard under Messages > New Message > Additional Fields flag enabled.

**boolean **isAppForeground (for IReceivedPushMessageListener only) - this flag indicates whether the application was in foreground or background mode.

Imaportant: You will get IReceivedPushMessageListener onReceived callback only when your application is not closed. There are two cases: the app is working foreground and background (but not closed!).

So, when the app is running in the foreground, you will get IReceivedPushMessageListener onReceived callback with isAppForeground flag set to true and the notification will not be displayed in system notification bar. In such a case that's your responsibility to display your custom in-game UI for this notification. When the app is running in the background, you will get IReceivedPushMessageListener onReceived callback with isAppForeground flag set to false and the notification will be displayed in system notification bar.

Push notifications customization

You have the opportunity to set up custom icons for your push notifications. The notification icons customization page in your Gravitum Dashboard looks like shown in the screenshot below.

Three customization options are available - Small icon, Large icon (Android 3.0+) and Big picture icon (Android 4.1+). Small and large icons demonstration shown on the next screenshot

There are two ways to provide all these icons for your push notification - in the app resources or via Url. If you want to provide your icons as the application resources, you have to add all the files (icon png/jpeg files) in the res/drawable folder of your app project. Let's take a look at the following screenshot. hello_world and push_icon icons will be used for customizing your push notifications.

Custom Small icon can be set only via app resources. But Large icon can be set via app resources and via image Url as well. If you want to display push notifications with great art presentation, the big picture notification style is right what you are looking for. The example of push notification big picture style is shown in this screenshot

Big picture icon can be set both - in application resources and via Url as well.

If any kind of issue will take place while small/large icon loading (e.g. the resource with such a name does not exist or the image was not loaded with the provided Url), the default application icon will be chosen in this case. If any kind of issue will take place while the big picture icon is loading, the notification will not be displayed with the big picture style. Just the general push notification will be displayed in this case.

If you need more detailed information about each API, you can find all the SDK API References here .

Clone this wiki locally