Message-ID: <322954264.1201.1425409855204.JavaMail.javamailuser@localhost> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_1200_738119733.1425409855003" ------=_Part_1200_738119733.1425409855003 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html Android Reference

Android Reference

=20
=20

Please Notice

=20 Icon=20
=20

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

=20
=20
=20

 

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 y= our 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 t= he getInstance() method.

 

public<= /span> static void init(Context context, String googleProjectNumber, String appToke= n)
Type Name Description
Context

context

The context in which the PushManag= er instance is initiated. It is recommended to pass your application c= ontext.
String

googleProjectNumbe= r

Your Google project number, i= nitiated from the Google Cloud Console.
String

appToken

Your app token, initiated from the=  PushApps a= dmin console.

Example:

 

PushManager.init(getApplicationContext(), "YOUR GOOGLE PROJECT NU=
MBER", "YOUR PUSHAPPS APP TOKEN"); 
=20
=20 Icon=20
=20

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

=20
=20
=20

public static PushManager getIn= stance(Context context)

Type Name Description
Context

context

The context in which the PushManag= er instance is initiated. It is recommended to pass your application c= ontext.

Example:

 

1
PushManager.getInstance(getApplicationContext())= ; 
=20
=20 Icon=20
=20

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

=20
=20
=20

 

Notifications

Launch Intent

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

public void setIntentNameToLaun= ch(String intentName)

Type Name Description
String

intentName

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

Example:

 

1
2
PushManager mPushManager =3D PushManager.getInst= ance(getApplicationContext()); 
mPushManager.setIntentNameToLaunch( "com.example.pushappsdemo.MainActivity&quo= t; );

 

Icon

If you would like to open a specific view or do some specific action, af= ter the notification was tapped, we do not recommend using this option. Ins= tead, handle it from your main activity, in which all the JSON parameters a= re available for you. For more information, please see the Handling notification clicks<= /a> section

Custom settings

No= tification icon

By default, the notification icon is a smaller conversion of your app ic= on. 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)

Type Name Description
int

iconResource

The resource id, representing your= notification image.

Example:

 

1
2
PushManager mPushManager =3D PushManager.getInst= ance(getApplicationContext());
mPushManager.setNotificationIcon(R.drawable.noti= fication_icon);

 

For more information about designing a notification icon, please visit&n= bsp;http://developer.android.com/design/style/iconography.ht= ml#notification

Display more than one notification<= /h4>

You can display more than one notification at the same time by calling&n= bsp;setShouldStackNotifications(true)

 

PushManager.getInstance(getApplicationContext())= .setShouldStackNotifications( true );
=20
=20 Icon=20
=20

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.

=20
=20
=20

Vibration

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

public void setVibrationEnabled= (boolean enabled)

Type Name Description
boolean

enabled

false to disable vibration, true o= therwise. Default is true

public long isVibrationEnabled()

no parameters

Returns false if vibration for notifications were disabled, true ot= herwise.

Available for API 19 ( Kit Kat ) and above

public void setVi= brationPattern(long[] pattern)

Type Name Description
long[]

pattern

the pattern for the vibration when= receiving notifications

Example:

PushManager.getInstance(getApplicationContext()).setVibrationPattern(new lo= ng[] {0,300,200,300});
=20
=20 Icon=20
=20
  • If you want to enable vibration add the permission android.permission.V= IBRATE to your AndroidManifest
=20
=20
=20

 

Callback

In some cases, you will want to run some code block, when a new notifica= tion received. In order to do so, all you need is to implement the PushAppsMessageInterface. This interface declares the method&= nbsp;onMessage, with a Context and an Intent which contain= s a bundle which has the notifi= cation properties they can be retrieved by calling intent.get= Extras()

 

1
2
3
4
public=20 interface=20 PushAppsMessageInterface {
 
     public=20 void=20 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=20 com.example.pushappsdemo;
 
import=20 com.groboot.pushapps.PushAppsMessageInterface;
 
import=20 com.groboot.pushapps.PushManager;
 
import=20 android.app.Application;
import=20 android.content.Context;
import=20 android.content.Intent;
 
public=20 class=20 DemoApplication extends=20 Application {
 
     public=20 static=20 final=20 String GOOGLE_API_PROJECT_NUMBER = =3D "your sender id (Google API project number= )" ;
     public=20 static=20 final=20 String PUSHAPPS_APP_TOKEN =3D "your application token from PushApps"= ; ;
 
 
     @Override
     public=20 void=20 onCreate() {
        = ; super .onCreate();
 
        = ; PushManager mPushManager =3D PushManager.getInst= ance(getApplicationContext());
        = ; mPushManager.registerForMessagesEvents( new=20 PushAppsMessageInterface() {
 
        = ;     @Override
        = ;     public=20 void=20 onMessage(Context context, Intent intent) {
        = ;         Bundle extras =3D intent.getExtras();
        = ;         //do something with the data
// This is the notification message
        = ;     String notificationMessage =3D extras.getString(PushManager.NOTIFICATION_MESSAGE_KEY);
        = ;     // This is the notification title
        = ;     String notificationTitle =3D extras= .getString(PushManager.NOTIFICATION_TITLE_KEY);
        = ;     // This is the notification link
        = ;     String notificationLink =3D extras.= getString(PushManager.NOTIFICATION_LINK_KEY);
        = ;     // This is the notification custom JSON
        = ;     String notificationCustomJSON =3D extras.getString(YOUR_CUSTOM_JSON_KEY);
        = ;         //you can then either create your own notific= ation, or call buildNotification() static method
        = ;         PushManager.buildNotification(extras, context, <= /code> 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 no= tification view. If you do not want to handle it yourself, and you prefer t= he 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 Vie= w section.

Icon

The callback will be on a different thread, and not on the main executio= n 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 f= rom the PushAppsMessageInterface onMessage() callback

 

public static void buildNotific= ation(Bundle data, Context context, int notificationId)

Type Name Description
Bundle

data

The bundle that was passed from th= e PushAppsMessageInterface onMessage() callback
Context context  
int NotificationId Id for status bar notification, if= you want to display more than one notification at once you should pass a r= andom 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 =3D  "your sender id (Google API project number)"  ;
      public   static   final   String PUSHAPPS_APP_TOKEN =3D  "your application token from PushApps"  ;
 
 
      @Override
      public   void   onCreate() {
          super  .onCreate();  
 
          PushManager mPushManager =3D PushManager.getInstance(getApplicationCo= ntext());
          mPushManager.registerForMessagesEvents(  new   PushAppsMessageInterface() {
 
           &nb= sp;  @Override
           &nb= sp;  public   void   onMessage(Context context, Intent intent) {
           &nb= sp;      Bundle extras =3D intent.getExtras();
           &nb= sp;    //pass a random number if more than one notifica= tions should be displayed
           &nb= sp;      PushManager.buildNotification(extras, context,(new Random()).nextInt(= 150) + 1);
           &nb= sp;  }
          });
  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 th= e received notification and the application launched. An access to the push= notification properties is a must in those case. PushApps gives you an eas= y access to the title, message and link, associated with the push notificat= ion message.

 

public=  static String NOTIFICATION_MESSAGE_KEY

 = public static String NOTIFICATI= ON_TITLE_KEY

 public static String NOTIFICATION_LINK_KEY

There are two places where you can handle a user notification click on t= he notification, by default if the activity is closed then you need to hand= le the click in the onCreate() of the activity.<= /p>

All you need to do, is to get the desired property from the intent bundl= e. 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=20 com.example.pushappsdemo;
 
 
import=20 com.groboot.pushapps.PushManager;
 
import=20 android.app.Activity;
import=20 android.os.Bundle;
import=20 android.util.Log;
 
public=20 class=20 MainActivity extends=20 Activity {
 
     @Override
     protected=20 void=20 onCreate(Bundle savedInstanceState) {
        = ; super .onCreate(savedInstanceState);
        = ; setContentView(R.layout.activity_main);
 
        = ; Bundle bundle =3D this .getIntent().getExtras();    = ;  
        = ; if=20 (bundle !=3D null ) {
        = ;     // This is the notification message
        = ;     String notificationMessage =3D bundle.getString(= PushManager.NOTIFICATION_MESSAGE_KEY);
        = ;     // This is the notification title
        = ;     String notificationTitle =3D bundle.getString(Pu= shManager.NOTIFICATION_TITLE_KEY);
        = ;     // This is the notification link
        = ;     String notificationLink =3D bundle.getString(Pus= hManager.NOTIFICATION_LINK_KEY);
        = ;     // This is the notification custom JSON, the = default key will be PushManager.EXTRA_DATA
        = ;     String notificationCustomJSON =3D bundle.getStri= ng(YOUR_CUSTOM_JSON_KEY);
        = ;    try=20 {
        = ;     JSONObject jsonObject =3D new=20 JSONObject(notificationCustomJSON )= ;
        = ;    } catch=20 (JSONException e)
        = ;    {
        = ;    }
        = ; }
     }
}
=20
=20 Icon=20
=20

As you can see in the example, this is also the way to get your custom p= roperties 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 n= otifications. If you want to do it through the Remote Server API (serve= r side), please refer to the Re= mote Server API section.

=20
=20
=20

 

 

If the activity is in the foreground, or if the activity is in the backg= round and it hasn't been destroyed by the system then the onNe= wIntent() 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=20 com.example.pushappsdemo;
 
import=20 com.groboot.pushapps.PushManager;
 
import=20 android.app.Activity;
import=20 android.os.Bundle;
 
public=20 class=20 MainActivity extends=20 Activity {
 
     @Override
     public=20 void=20 onNewIntent(Intent intent){
        = ; Bundle bundle =3D intent.getExtras();  = ;  
        = ; if=20 (bundle !=3D null ) {
        = ;    //handle the notification click, same code as= in the onCreate()
        = ; }
     }
}
=20
=20 Icon=20
Please note that if you set  setShouldStartIntentAsNewTask(true) then a new instan= ce of the activity will always be created and the  onCreate() will always be called when the user clicks= on the notification.=20
=20
=20

Registration

Register device

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

public=  void register()

No parameters.

Example:

 

1
2
PushManager mPushManager =3D PushManager.getInst= ance(getApplicationContext());
mPushManager.register();

 

Unregister device

It is considered to be user friendly to let your users to unregister fro= m receiving push notifications at any time. If you want to let your users t= o do so, all you need is to call the unregister()&nbs= p;method.

public void unregister ()

No parameters.

Example:

 

1
2
PushManager mPushManager =3D PushManager.getInst= ance(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 t= hePushAppsRegistrationInterface. This is interface declare= d two callbacks, one for register and another for the unregister.

=20
=20 Icon=20
=20

The callback will be on a different thread, and not on the main executio= n 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.=20

=20
=20

onRegistered

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

public void onRegistered(Contex= t context, String registrationId)

Type Name Description
String

registrationId

=
the device registrationId used to = send messages to the device
Context context the service context

onUnregi= stered

public void onRegistered(Contex= t context, String registrationId)

Type Name Description
String

registrationId

=
the device registrationId
Context context the service context
1
2
3
4
5
6
public=20 interface=20 PushAppsRegistrationInterface {
 
     public=20 void=20 onRegistered(Context context, String registratio= nId);
 
     public=20 void=20 onUnregistered(Context context, String registrat= ionId);
}

 

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=20 com.example.pushappsdemo;
 
import=20 com.groboot.pushapps.PushAppsRegistrationInterfa= ce;
 
import=20 com.groboot.pushapps.PushManager;
 
import=20 android.app.Application;
import=20 android.content.Context;
import=20 android.content.Intent;
 
public=20 class=20 DemoApplication extends=20 Application {
 
     public=20 static=20 final=20 String GOOGLE_API_PROJECT_NUMBER = =3D "my project number" ; //your sender id (google API project id)
     public=20 static=20 final=20 String PUSHAPPS_APP_TOKEN =3D "my app token" ; //your application token from PushApps
 
 
     @Override
     public=20 void=20 onCreate() {
        = ; super .onCreate();
 
        = ; PushManager mPushManager =3D PushManager.getInst= ance(getApplicationContext());
        = ; mPushManager.registerForRegistrationEvents( new=20 PushAppsRegistrationInterface() {
 
        = ;     @Override
        = ;     public=20 void=20 onUnregistered(Context context, String paramStri= ng) {
        = ;         // The device has been unregistered
        = ;     }
 
        = ;     @Override
        = ;     public=20 void=20 onRegistered(Context context, String registratio= nId) {
        = ;         //The device is registered to the GCM service= , the registrationId is the unique device token which will be used for send= ing messages.
        = ;         
        = ;     }
        = ; });
 
        = ; PushManager.init(getApplicationContext(), = GOOGLE_API_PROJECT_NUMBER, PUSHAPPS_APP_TOKEN);
     }
}

 

<= span class=3D"confluence-anchor-link" id=3D"AndroidReference-Tags">T= ags

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, t= he 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 mo= re about Segments please re= fer to our Segmentation guide

there are 4 types of tags:

  • int

  • Date

  • Boolean

  • String

Through the SDK , You can send multip= le tags at once.

 

=20
=20 Icon=20
=20

A tag with the same identifier can on= ly have a single data type.

=20
=20
=20

 Tag class

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

You can send different tags at once.<= /span>

A tag with the same identifier can on= ly have a single data type.

 

public Tag(String = identifier, int value)

Type Name Description
String

identifier

name for the tag
int value the tag value

public Tag(String = identifier, String value)

Type Name Description
String

identifier

name for the tag
String value string tag value

public Tag(String = identifier, Date value)

Type Name Description
String

identifier

name for the tag
Date value date tag value

public Tag(String = identifier, boolean value)

Type Name Description
String

identifier

name for the tag
boolean value boolean tag value

= SendTagResponseListener<= /h3>

An Interface to listen to the se= ndTag() method response

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

public void respon= se(boolean success, String message)

Type Name Description
boolean

success

boolean indicating if the request = was successful
String message response message from the server

sendTag method

me= thod used to send the tag, you can pass a listener which is optional and Ta= g objects. 

public void sendTa= g(SendTagResponseListener responseListener, Tag... tags)

Type Name Description
SendTagResponseListener

responseListener

optional: pass a = listener to receive the response of the call
Tag tags pass any amount of tags for sendin= g

Example:

sending a single tag without a response li= stener: 

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",&quo=
t;stringvalue"), 
new Tag("my_boolean_tag_name",true), new Tag("my_date_t=
ag_name",new Date()));
 pass a listener for the response:<= /span>
1
2
3
4
5
6
7
8
9
10
11
12
13
SendTagResponseListener mTagResponseListener =3D new SendTagResponseLi=
stener() {
=09@Override
=09public void response(boolean success, String message) {
=09=09if (success) {
=09=09=09//
=09=09=09} else {
=09=09=09// failure
=09=09=09Log.d("pushapps", "response message " + messag=
e);
=09=09=09}
=09=09}
=09};
PushManager.getInstance(getApplicationContext()).sendTag(mTagResponseListen=
er, new Tag("my_int_tag_name", 12),
=09new Tag("another_tag_name", "stringvalue"), new Tag(=
"my_boolean_tag_name", true), new Tag("my_date_tag_name"=
;, new Date()));

removeTag me= thod

remove a single or multiple tags this method receives an optional listen= er and multiple or one tag names

public void remove= Tag(SendTagResponseListener responseListener, String... tagsToRemove)

Type Name Description
SendTagResponseListener

responseListener

optional: pass a = listener to receive the response of the call
String...tagsToRemove tagsToRemove one or multiple tag names to be re= moved
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 =3D new SendTagResponseLi=
stener() {
@Override
=09public void response(boolean success, String message) {
=09if (success) {
=09=09//success
=09    } else {
=09=09// failure
=09=09Log.d("pushapps", "response message " + message);
=09=09}
=09}
};

 

Device Properties

Registration Id

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

=20 Icon=20
=20

The registration id will be available only after a successful registrati= on ( by calling init or register&nb= sp;)

=20
=20
=20

public String getDeviceRegistrationId ()

No parameters.

Example:

 

1
2
PushManager mPushManager =3D PushManager.getInst= ance(getApplicationContext());
String registrationId =3D mPushManager.getDevice= RegistrationId();

Custom Id 

Add a custom id to a device, it allows you to have another id for the de= vice 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)

Type Name Description
String

id

the custom id for the user

<= /td>

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_NU= MBER, PUSHAPPS_APP_TOKEN);

App version

The application version name mentioned in the manifest

public=  String getAppVersion ()

No parameters.

Example:

 

1
2
PushManager mPushManager =3D PushManager.getInst= ance(getApplicationContext());
String versionName =3D mPushManager.getAppVersio= n();

 

Device Id

The Device ID is the device unique identifier.

public=  String getDeviceId ()

No parameters.

Example:

 

1
2
3
4
5
PushManager mPushManager =3D PushManager.getInst= ance(getApplicationContext());
 
// retrive the device ID
String deviceId =3D mPushManager.getDeviceId();<= /code>
 

Device Id t= ypes

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 wi= ll need to add the android.permission.READ_PHONE_STATE permission in the A= ndroidManifest.xml file.

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

=20
=20 Icon=20
=20

You must call this method before calling init(Con= text,String,String) for the first time, since init(Context,String,St= ring) will register the device in our service and if change the id type lat= er the device will be duplicated in our service. Furthermore, once choosing= the identifier type it is obviously recommended to never change it again.<= /p>=20

=20
=20

public void setDeviceIDType(Dev= iceIDTypes type)

Type Name Description
DeviceIdTypes

type

the desired source for the devi= ce id property

 

OS version

The android api int version.

public String getOSVersion ()

No parameters.

Example:

 

1
2
PushManager mPushManager =3D PushManager.getInst= ance(getApplicationContext());
int=20 apiVersion =3D mPushManager.getOSVersion();

 

SDK version

The PushApps sdk version.

public=  String getSDKVersion ()

No parameters.

Example:

 

1
2
PushManager mPushManager =3D PushManager.getInst= ance(getApplicationContext());
String pushAppsSdkVersion =3D mPushManager.getSD= KVersion();

Enums

DeviceIDTypes

The = available sources for the device id property.
Name Value
IMEI 1
ANDROID_ID 2
------=_Part_1200_738119733.1425409855003--