Page tree
Skip to end of metadata
Go to start of metadata

Please Notice

If you are testing on an emulator - set the target of the emulator to Google APIs

 

Push Manager

The PushManager instance is the main object and the most important one. Once initiated, an automatic call to register device is being made, using your Google Project Id and your PushApps App Token, initiated for you in the Admin Console

You can always get the current instance of PushApps, simply by calling the getInstance() method.

 

public static void init(Context context, String googleProjectNumber, String appToken)
TypeNameDescription
Context

context

The context in which the PushManager instance is initiated. It is recommended to pass your application context.
String

googleProjectNumber

Your Google project number, initiated from the Google Cloud Console.
String

appToken

Your app token, initiated from the PushApps admin console.

Example:

 

PushManager.init(getApplicationContext(), "YOUR GOOGLE PROJECT NUMBER", "YOUR PUSHAPPS APP TOKEN"); 

If you want to set your own Custom Id , set it before calling to init(), as seen here .

public static PushManager getInstance(Context context)

TypeNameDescription
Context

context

The context in which the PushManager instance is initiated. It is recommended to pass your application context.

Example:

 

1
PushManager.getInstance(getApplicationContext()); 

We recommend to hold a PushManager instance in your application class or inside your main activity.

 

Notifications

Launch Intent

The launch intent option enables you to decide which intent you would like to launch, after the user tap on the notification from the status bar. By default, if you do not set this to a specific intent, PushApps will launch your main activity. You can use this option, for example, if you want to launch another app (e.g: web browser).

public void setIntentNameToLaunch(String intentName)

TypeNameDescription
String

intentName

The package name, which represent the intent you would like to initiate, once the notification is tapped.

Example:

 

1
2
PushManager mPushManager = PushManager.getInstance(getApplicationContext()); 
mPushManager.setIntentNameToLaunch("com.example.pushappsdemo.MainActivity");

 

Icon

If you would like to open a specific view or do some specific action, after the notification was tapped, we do not recommend using this option. Instead, handle it from your main activity, in which all the JSON parameters are available for you. For more information, please see the Handling notification clicks section

Custom settings

Notification icon

By default, the notification icon is a smaller conversion of your app icon. In some cases, the icon does not look as you'll expect it to be, due to some limitations in the conversion process of the OS. We recommend to provide an icon that the system can display in the status bar whenever a new notification is available. Please notice that the notification icon must be 24x24 dp.

 

public void setNotificationIcon(int iconResource)

TypeNameDescription
int

iconResource

The resource id, representing your notification image.

Example:

 

1
2
PushManager mPushManager = PushManager.getInstance(getApplicationContext());
mPushManager.setNotificationIcon(R.drawable.notification_icon);

 

For more information about designing a notification icon, please visit http://developer.android.com/design/style/iconography.html#notification

Display more than one notification

You can display more than one notification at the same time by calling setShouldStackNotifications(true)

 

PushManager.getInstance(getApplicationContext()).setShouldStackNotifications(true);

If you decide to set setShouldStackNotifications to true then make sure you override the onNewIntent(Intent intent) method in your activity to handle the notification click.

Vibration

You can enable and disable vibration for a notification, and set the pattern of the vibration as well.

public void setVibrationEnabled(boolean enabled)

TypeNameDescription
boolean

enabled

false to disable vibration, true otherwise. Default is true

public long isVibrationEnabled()

no parameters

Returns false if vibration for notifications were disabled, true otherwise.

Available for API 19 ( Kit Kat ) and above

public void setVibrationPattern(long[] pattern)

TypeNameDescription
long[]

pattern

the pattern for the vibration when receiving notifications

Example:

PushManager.getInstance(getApplicationContext()).setVibrationPattern(new long[] {0,300,200,300});
  • If you want to enable vibration add the permission android.permission.VIBRATE to your AndroidManifest

 

Callback

In some cases, you will want to run some code block, when a new notification received. In order to do so, all you need is to implement the PushAppsMessageInterface. This interface declares the method onMessage, with a Context and an Intent which contains a bundle which has the notification properties they can be retrieved by calling intent.getExtras()

 

1
2
3
4
public interface PushAppsMessageInterface {
 
    public void onMessage(Context context, Intent intent);
}

 

Example:

 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
package com.example.pushappsdemo;
 
import com.groboot.pushapps.PushAppsMessageInterface;
 
import com.groboot.pushapps.PushManager;
 
import android.app.Application;
import android.content.Context;
import android.content.Intent;
 
public class DemoApplication extends Application {
 
    public static final String GOOGLE_API_PROJECT_NUMBER = "your sender id (Google API project number)";
    public static final String PUSHAPPS_APP_TOKEN = "your application token from PushApps";
 
 
    @Override
    public void onCreate() {
        super.onCreate();
 
        PushManager mPushManager = PushManager.getInstance(getApplicationContext());
        mPushManager.registerForMessagesEvents(new PushAppsMessageInterface() {
 
            @Override
            public void onMessage(Context context, Intent intent) {
                Bundle extras = intent.getExtras();
                //do something with the data
// This is the notification message
             String notificationMessage = extras.getString(PushManager.NOTIFICATION_MESSAGE_KEY);
             // This is the notification title
             String notificationTitle = extras.getString(PushManager.NOTIFICATION_TITLE_KEY);
             // This is the notification link
             String notificationLink = extras.getString(PushManager.NOTIFICATION_LINK_KEY);
             // This is the notification custom JSON
             String notificationCustomJSON = extras.getString(YOUR_CUSTOM_JSON_KEY);
                //you can then either create your own notification, or call buildNotification() static method
                PushManager.buildNotification(extras, context, 108);
            }
        });
PushManager.init(getApplicationContext(),GOOGLE_API_PROJECT_NUMBER, PUSHAPPS_APP_TOKEN);
    }
}
  

 

Icon

If you implement this interface, you will also need to build your own notification view. If you do not want to handle it yourself, and you prefer the default view that the PushApps SDK supplies, you can just call our buildNotification method, which will do it for you. For more information, please refer to the Custom Notification View section.

Icon

The callback will be on a different thread, and not on the main execution thread, please make sure you are not accessing the UI directly from this thread, or starting new threads which may cause an ANR dialog to appear.

BuildNotification

creates a status bar notification, it can only be called with the data from the PushAppsMessageInterface onMessage() callback

 

public static void buildNotification(Bundle data, Context context, int notificationId)

TypeNameDescription
Bundle

data

The bundle that was passed from the PushAppsMessageInterface onMessage() callback
Contextcontext 
intNotificationIdId for status bar notification, if you want to display more than one notification at once you should pass a random number.

 

Example:

 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
package  com.example.pushappsdemo;
 
import  com.groboot.pushapps.PushAppsMessageInterface;
 
import  com.groboot.pushapps.PushManager;
 
import  android.app.Application;
import  android.content.Context;
import  android.content.Intent;
 
public  class  DemoApplication extends  Application {
 
     public  static  final  String GOOGLE_API_PROJECT_NUMBER"your sender id (Google API project number)" ;
     public  static  final  String PUSHAPPS_APP_TOKEN = "your application token from PushApps" ;
 
 
     @Override
     public  void  onCreate() {
         super .onCreate();  
 
         PushManager mPushManager = PushManager.getInstance(getApplicationContext());
         mPushManager.registerForMessagesEvents( new  PushAppsMessageInterface() {
 
             @Override
             public  void  onMessage(Context context, Intent intent) {
                 Bundle extras = intent.getExtras();
                //pass a random number if more than one notifications should be displayed
                 PushManager.buildNotification(extras, context,(new Random()).nextInt(150) + 1);
             }
         });
 PushManager.init(getApplicationContext(), GOOGLE_API_PROJECT_NUMBER, PUSHAPPS_APP_TOKEN);
     }
}

 

Handling notification clicks

Most of the apps would like to do something, after the user tapped on the received notification and the application launched. An access to the push notification properties is a must in those case. PushApps gives you an easy access to the title, message and link, associated with the push notification message.

 

public static String NOTIFICATION_MESSAGE_KEY

 public static String NOTIFICATION_TITLE_KEY

 public static String NOTIFICATION_LINK_KEY

There are two places where you can handle a user notification click on the notification, by default if the activity is closed then you need to handle the click in the onCreate() of the activity.

All you need to do, is to get the desired property from the intent bundle. For example:

 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
package com.example.pushappsdemo;
 
 
import com.groboot.pushapps.PushManager;
 
import android.app.Activity;
import android.os.Bundle;
import android.util.Log;
 
public class MainActivity extends Activity {
 
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
 
        Bundle bundle = this.getIntent().getExtras();      
        if (bundle != null) {
            // This is the notification message
            String notificationMessage = bundle.getString(PushManager.NOTIFICATION_MESSAGE_KEY);
            // This is the notification title
            String notificationTitle = bundle.getString(PushManager.NOTIFICATION_TITLE_KEY);
            // This is the notification link
            String notificationLink = bundle.getString(PushManager.NOTIFICATION_LINK_KEY);
            // This is the notification custom JSON, the default key will be PushManager.EXTRA_DATA
            String notificationCustomJSON = bundle.getString(YOUR_CUSTOM_JSON_KEY);
           try {
            JSONObject jsonObject = new JSONObject(notificationCustomJSON );
           } catch (JSONException e)
           {
           }
        }
    }
}

As you can see in the example, this is also the way to get your custom properties which is in the notification JSON. More about how to send custom properties through the PushApps admin console, inside the notification JSON, please refer to Sending notifications. If you want to do it through the Remote Server API (server side), please refer to the Remote Server API section.

 

 

If the activity is in the foreground, or if the activity is in the background and it hasn't been destroyed by the system then the onNewIntent() will be called, and not the onCreate() callback.

 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
package com.example.pushappsdemo;
 
import com.groboot.pushapps.PushManager;
 
import android.app.Activity;
import android.os.Bundle;
 
public class MainActivity extends Activity {
 
    @Override
    public void onNewIntent(Intent intent){
        Bundle bundle = intent.getExtras();    
        if (bundle != null) {
           //handle the notification click, same code as in the onCreate()
        }
    }
}
Please note that if you set setShouldStartIntentAsNewTask(true) then a new instance of the activity will always be created and the onCreate() will always be called when the user clicks on the notification.

Registration

Register device

Once you call the init method of PushApps, the device is automatically registered to get push notification. That being said, there will be situations, in which you'll want to register the device directly (e.g.: after the user unregister the service and ask to register again).

public void register()

No parameters.

Example:

 

1
2
PushManager mPushManager = PushManager.getInstance(getApplicationContext());
mPushManager.register();

 

Unregister device

It is considered to be user friendly to let your users to unregister from receiving push notifications at any time. If you want to let your users to do so, all you need is to call the unregister() method.

public void unregister ()

No parameters.

Example:

 

1
2
PushManager mPushManager = PushManager.getInstance(getApplicationContext());
mPushManager.unregister();

 

Callbacks

If you would like to do some operations, after the user was register or unregister to the push notification service, all you need is to implement thePushAppsRegistrationInterface. This is interface declared two callbacks, one for register and another for the unregister.

The callback will be on a different thread, and not on the main execution thread, please make sure you are not accessing the UI directly from this thread, or starting new threads which may cause an ANR dialog to appear.

onRegistered

The callback is called after the device has been successfully registered to the gcm service

public void onRegistered(Context context, String registrationId)

TypeNameDescription
String

registrationId

the device registrationId used to send messages to the device
Contextcontextthe service context

onUnregistered

public void onRegistered(Context context, String registrationId)

TypeNameDescription
String

registrationId

the device registrationId
Contextcontextthe service context
1
2
3
4
5
6
public interface PushAppsRegistrationInterface {
 
    public void onRegistered(Context context, String registrationId);
 
    public void onUnregistered(Context context, String registrationId);
}

 

Example:

 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
package com.example.pushappsdemo;
 
import com.groboot.pushapps.PushAppsRegistrationInterface;
 
import com.groboot.pushapps.PushManager;
 
import android.app.Application;
import android.content.Context;
import android.content.Intent;
 
public class DemoApplication extends Application {
 
    public static final String GOOGLE_API_PROJECT_NUMBER = "my project number"; //your sender id (google API project id)
    public static final String PUSHAPPS_APP_TOKEN = "my app token"; //your application token from PushApps
 
 
    @Override
    public void onCreate() {
        super.onCreate();
 
        PushManager mPushManager = PushManager.getInstance(getApplicationContext());
        mPushManager.registerForRegistrationEvents(new PushAppsRegistrationInterface() {
 
            @Override
            public void onUnregistered(Context context, String paramString) {
                // The device has been unregistered
            }
 
            @Override
            public void onRegistered(Context context, String registrationId) {
                //The device is registered to the GCM service, the registrationId is the unique device token which will be used for sending messages.
                 
            }
        });
 
        PushManager.init(getApplicationContext(), GOOGLE_API_PROJECT_NUMBER, PUSHAPPS_APP_TOKEN);
    }
}

 

Tags

There will be a time when you will want to send a push notification to a group of users, with a common characteristics. In order to do that, the PushApps Android SDK gives you the ability to mark users with a specific tag. For example: one's age. You can add as many tags as you want per user. For each, you'll need to supply the tag's identifier and the tag's value.

A set of tags and conditions between them creates a Segment, to learn more about Segments please refer to our Segmentation guide

there are 4 types of tags:

  • int

  • Date

  • Boolean

  • String

Through the SDK , You can send multiple tags at once.

 

A tag with the same identifier can only have a single data type.

 Tag class

Tag represents the data that is being sent, it has 4 constructors, 1 for each data type.

You can send different tags at once.

A tag with the same identifier can only have a single data type.

 

public Tag(String identifier, int value)

TypeNameDescription
String

identifier

name for the tag
intvaluethe tag value

public Tag(String identifier, String value)

TypeNameDescription
String

identifier

name for the tag
Stringvaluestring tag value

public Tag(String identifier, Date value)

TypeNameDescription
String

identifier

name for the tag
Datevaluedate tag value

public Tag(String identifier, boolean value)

TypeNameDescription
String

identifier

name for the tag
booleanvalueboolean tag value

SendTagResponseListener

An Interface to listen to the sendTag() method response

it has a callback method with a boolean indicating if the sendTag() call was successful and a String message.

public void response(boolean success, String message)

TypeNameDescription
boolean

success

boolean indicating if the request was successful
Stringmessageresponse message from the server

sendTag method

method used to send the tag, you can pass a listener which is optional and Tag objects. 

public void sendTag(SendTagResponseListener responseListener, Tag... tags)

TypeNameDescription
SendTagResponseListener

responseListener

optional: pass a listener to receive the response of the call
Tagtagspass any amount of tags for sending

Example:

sending a single tag without a response listener: 

1
PushManager.getInstance(getApplicationContext()).sendTag(null, new Tag("my_int_tag_name",12));
sending multiple tags without a response listener:
1
2
PushManager.getInstance(getApplicationContext()).sendTag(null, new Tag("my_int_tag_name",12), new Tag("another_tag_name","stringvalue"), 
new Tag("my_boolean_tag_name",true), new Tag("my_date_tag_name",new Date()));
 pass a listener for the response:
1
2
3
4
5
6
7
8
9
10
11
12
13
SendTagResponseListener mTagResponseListener = new SendTagResponseListener() {
	@Override
	public void response(boolean success, String message) {
		if (success) {
			//
			} else {
			// failure
			Log.d("pushapps", "response message " + message);
			}
		}
	};
PushManager.getInstance(getApplicationContext()).sendTag(mTagResponseListener, new Tag("my_int_tag_name", 12),
	new Tag("another_tag_name", "stringvalue"), new Tag("my_boolean_tag_name", true), new Tag("my_date_tag_name", new Date()));

removeTag method

remove a single or multiple tags this method receives an optional listener and multiple or one tag names

public void removeTag(SendTagResponseListener responseListener, String... tagsToRemove)

TypeNameDescription
SendTagResponseListener

responseListener

optional: pass a listener to receive the response of the call
String...tagsToRemovetagsToRemoveone or multiple tag names to be removed
Examples:

remove one tag

1
PushManager.getInstance(getApplicationContext()).removeTag(null, "my_int_tag");

 

remove multiple tags
1
PushManager.getInstance(getApplicationContext()).removeTag(null, "my_int_tag","my_string_tag","another_tag");

 

pass a response listener:
1
2
3
4
5
6
7
8
9
10
11
SendTagResponseListener mTagResponseListener = new SendTagResponseListener() {
@Override
	public void response(boolean success, String message) {
	if (success) {
		//success
	    } else {
		// failure
		Log.d("pushapps", "response message " + message);
		}
	}
};

 

Device Properties

Registration Id

The device registration id it is used to send messages to the device.

The registration id will be available only after a successful registration ( by calling init or register )

public String getDeviceRegistrationId ()

No parameters.

Example:

 

1
2
PushManager mPushManager = PushManager.getInstance(getApplicationContext());
String registrationId = mPushManager.getDeviceRegistrationId();

Custom Id 

Add a custom id to a device, it allows you to have another id for the device alongside the unique device id. If you want to use this feature, call this method before calling the init(Context, String,String) method

public void setCustomId(String id)

TypeNameDescription
String

id

the custom id for the user

public String getCustomId()

No parameters.

 

Set the custom Id before calling init() or register.

1
2
PushManager.setCustomId("123432");
PushManager.init(getApplicationContext(), GOOGLE_API_PROJECT_NUMBER, PUSHAPPS_APP_TOKEN);

App version

The application version name mentioned in the manifest

public String getAppVersion ()

No parameters.

Example:

 

1
2
PushManager mPushManager = PushManager.getInstance(getApplicationContext());
String versionName = mPushManager.getAppVersion();

 

Device Id

The Device ID is the device unique identifier.

public String getDeviceId ()

No parameters.

Example:

 

1
2
3
4
5
PushManager mPushManager = PushManager.getInstance(getApplicationContext());
 
// retrive the device ID
String deviceId = mPushManager.getDeviceId();
 

Device Id types

You can choose which identifier will be used as the device id.

The default is the device's IMEI if it accessible, but this means you will need to add the android.permission.READ_PHONE_STATE permission in the AndroidManifest.xml file.

use this method to select your desired source for the device id property

You must call this method before calling init(Context,String,String) for the first time, since init(Context,String,String) will register the device in our service and if change the id type later the device will be duplicated in our service. Furthermore, once choosing the identifier type it is obviously recommended to never change it again.

public void setDeviceIDType(DeviceIDTypes type)

TypeNameDescription
DeviceIdTypes

type

the desired source for the device id property

 

OS version

The android api int version.

public String getOSVersion ()

No parameters.

Example:

 

1
2
PushManager mPushManager = PushManager.getInstance(getApplicationContext());
int apiVersion = mPushManager.getOSVersion();

 

SDK version

The PushApps sdk version.

public String getSDKVersion ()

No parameters.

Example:

 

1
2
PushManager mPushManager = PushManager.getInstance(getApplicationContext());
String pushAppsSdkVersion = mPushManager.getSDKVersion();

Enums

DeviceIDTypes

The available sources for the device id property.
NameValue
IMEI1
ANDROID_ID2