SDK

Device Registration

In this guide we will dive deeper into how you should handle the device registration. If you are using the default re.notifica.push.gcm.DefaultIntentReceiver, this will be done automatically for you. It is recommended that you implement you own Intent Receiver in order to gain control over the device registration.

As explained in the Implementation page, in your own Intent Receiver you will be overriding the onReady method. This is where you first can enable your app to receive notifications:

1
2
3
4
5
6
7
8
9
10
public class MyIntentReceiver extends DefaultIntentReceiver {

	@Override
	public void onReady() {
	  // Enable this device for push notifications
	  Notificare.shared().enableNotifications();
	}

	//more code ...
}

The onReady method signals your application when the Notificare library has loaded its initial configuration and is ready to be used. Only after that, you should request a device identifier from FCM, by calling enableNotifications.

There can be situations where enabling notifications in the Intent Receiver is not the best way to go. For example if your app has an initial on-boarding process, you might not want to enabled notifications until the user actually goes through these screens and lands in your first activity or fragment. If that is the case, instead of enabling notifications in your own Intent Receiver you will want to implement the Notificare.OnNotificareReadyListener in your an activity as follows:

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
public class MyMainActivity extends ActionBarBaseActivity implements Notificare.OnNotificareReadyListener {

	...more code
	@Override
	protected void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);
		...more code

		Notificare.shared().addNotificareReadyListener(this);
	}

	...more code

	@Override
	public void onNotificareReady(NotificareApplicationInfo notificareApplicationInfo) {

		// Enable this device for push notifications
	  	Notificare.shared().enableNotifications();

	  	...more code?

	}

	@Override
	protected void onDestroy() {
		super.onDestroy();

		Notificare.shared().removeNotificareReadyListener(this);
	}
}

Whenever you invoke the Notificare.shared().enableNotifications() method, our library will request a device registration with FCM which in turn will callback the Intent Receiver with a device token. That token needs to be registered in Notificare so you can later own send messages to it. This device registration will occur in the Intent Receiver's onRegistrationFinished method, where you should then handle the device registration with Notificare, as shown below:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
public class MyIntentReceiver extends DefaultIntentReceiver {

...more code

  @Override
  public void onRegistrationFinished(String deviceId) {

	  //This will create an anonymous user
	  Notificare.shared().registerDevice(deviceId, new NotificareCallback<String>() {
		  @Override
		  public void onSuccess(String result) {
		  // After this point is safe to use location services, tags, etc..
		  }

		  @Override
		  public void onError(NotificareError error) {
		  //Got error on device registration
		  }
	  });
  }

...more code

}

Because these tokens can change at any time you need to make sure the device registration happens every time your application launches. The library will automatically discern if the registration should be skipped, in case nothing changes, or actually complete the registration in case a new device token is assigned.

But there will be situations where simply registering an anonymous device is not what you want. For example if you authenticate your users you will not want to register an anonymous device whenever the app launches. When that is the case, you will need to handle the onRegistrationFinished method differently:

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
39
40
41
42
43
44
public class MyIntentReceiver extends DefaultIntentReceiver {

...more code

  @Override
  public void onRegistrationFinished(String deviceId) {

	if (MyAuthClass.isLoggedIn) {

	//This will create an authenticated user
	  Notificare.shared().registerDevice(deviceId, MyAuthClass.userID, MyAuthClass.userName, new NotificareCallback<String>() {
		  @Override
		  public void onSuccess(String result) {
		  // After this point is safe to use location services, tags, etc..
		  }

		  @Override
		  public void onError(NotificareError error) {
		  //Got error on device registration
		  }
	  });

	} else {

	//This will create an anonymous user
	  Notificare.shared().registerDevice(deviceId, new NotificareCallback<String>() {
		  @Override
		  public void onSuccess(String result) {
		  // After this point is safe to use location services, tags, etc..
		  }

		  @Override
		  public void onError(NotificareError error) {
		  //Got error on device registration
		  }
	  });

	}

  }

...more code

}

When you authenticate users, you will also have the need to do this device registration right after they login in your app. This can be done basically from any where in your app using the method below:

1
2
3
4
5
6
7
8
9
10
11
Notificare.shared().registerDevice(Notificare.shared().getDeviceId(), "123456789", "John Doe",  new NotificareCallback<String>() {
	@Override
	public void onSuccess(String result) {
		//Handle Success
	}

	@Override
	public void onError(NotificareError error) {
		//Handle Error
	}
});

You will also want to register users as anonymous once they sign out from your app. This can be done basically from anywhere in your app using the method below:

1
2
3
4
5
6
7
8
9
10
11
12
13
Notificare.shared().setUserId(null);
Notificare.shared().setUserName(null);
Notificare.shared().registerDevice(new NotificareCallback<String>() {
	@Override
	public void onSuccess(String result) {
		//Handle Success
	}

	@Override
	public void onError(NotificareError error) {
		//Handle Error
	}
});

If you've followed these steps correctly and all the request succeeded, you should be able to see and send messages to devices/users via our dashboard and API.

User Data Fields

There are use cases where simply associating an userID and userName will not suffice. For those cases you can make use of User Data Fields where you can create key-value pairs for your application and then use them to extend your device registration. Before you can implement them you will need to first create them in your application via our dashboard. This is described here.

Once you have created one or more fields, you can implement this functionality in your app. To retrieve the list of fields allowed in your app you should use the following method:

1
2
3
4
5
6
7
8
9
10
11
Notificare.shared().fetchUserData(new NotificareCallback<NotificareUserData>() {
	@Override
	public void onSuccess(NotificareUserData notificareUserData) {
		//Handle the key-value pairs
	}

	@Override
	public void onError(NotificareError notificareError) {
		//Handle Error
	}
});

Whenever you want to update those fields with new values you should use the following method:

1
2
3
4
5
6
7
8
9
10
11
Notificare.shared().updateUserData((NotificareUserData) notificareUserData, new NotificareCallback<Boolean>() {
	@Override
	public void onSuccess(Boolean aBoolean) {
		//Handle success
	}

	@Override
	public void onError(NotificareError notificareError) {
		//Handle error
	}
});

If you are using our inbox functionality, these fields will also be available as placeholders when sending notifications by simply including {{userData.key}} in your messages.

Do Not Disturb

Each device registered with Notificare can be configured to specify a period of time during the day where it should not receive notifications. You can use this functionality in your app settings view to allow the user to provide a time range where messages will not be displayed in the lock screen or notification center. Please note that if you are using our inbox functionality these message will still be there.

To retrieve a device's DnD preferences use the following method:

1
2
3
4
5
6
7
8
9
10
11
Notificare.shared().fetchDoNotDisturb(new NotificareCallback<NotificareTimeOfDayRange>() {
	@Override
	public void onSuccess(NotificareTimeOfDayRange notificareTimeOfDayRange) {
		//Handle success
	}

	@Override
	public void onError(NotificareError notificareError) {
		//Handle error
	}
});

You can update the DnD values for a device, using the following method:

1
2
3
4
5
6
7
8
9
10
11
Notificare.shared().updateDoNotDisturb((NotificareTimeOfDayRange) range, new NotificareCallback<Boolean>() {
	@Override
	public void onSuccess(Boolean aBoolean) {
		//Handle success
	}

	@Override
	public void onError(NotificareError notificareError) {
		//Handle error
	}
});

Disable Notifications

It is also possible to disabled notifications in FCM and unregister a device from Notificare. Although it is not a common use case, there might be situations where you want to implement this kind of functionality.

Pretty much the same way you enable notifications you will also disabled them. To do that, use the following method:

1
Notificare.shared().disableNotifications();

Doing this will remove the device token from FCM and deactivate the device in Notificare. This will also mean that all the messages in the device's inbox (if applicable), tags or any other device setting will be deleted too. If this is the user's only device, Notificare will also inactivate the user. Obviously after this you will not be able to find or send a message to this device.