SDK

Device Registration

In this guide we will dive deeper into how you should handle the device registration. Using Website Push functionality is still in very young stages and most of your website visitors will not be totally familiar with this functionality, so it is crucial that you pick the right moment to ask for notifications, explain why it is necessary and provide an easy way to opt-out.

To start the request for notifications, you should wait until our library is fully initialized. We will emmit the following event when it does:

1
2
3
4
5
6
7
8
9
...more code

var instance = $('body').notificare();

...more code

$("body").bind("notificare:onReady", function(event, data) {
	instance.notificare("registerForNotifications");
});

The onReady method signals your website when the Notificare library has loaded its initial configuration and is ready to be used. Only after that, you should register for notifications. Please note that this might not be the best experience for the user, it is also not permitted by some browsers (latest Safari for desktop), because invoking this method will trigger the permission dialog, it is important that is done by a user initiated gesture. Instead you will want to wait for this event to enable or show a button which the user would then click to enable or even later disable notifications. Take the following example in consideration:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
...more code

var instance = $('body').notificare(), isReady = false;

...more code

$("body").bind("notificare:onReady", function(event, data) {
	isReady = true;
});

... more code

if (isReady) {
	//Show the enable notifications button
	$("#enable-button").show();
} else {
	//Hide the enable notifications button
	$("#enable-button").hide();
}

$("#enable-button").click(function(e) {
	e.preventDefault();
	instance.notificare("registerForNotifications");
});

Whenever you invoke the instance.notificare("registerForNotifications") method, our library will request a device subscription to FCM, VAPID or Apple depending on the browser your visitor is using. If your configuration is correct it will trigger the following event with a device identifier, which you should use to register the device with Notificare:

1
2
3
$("body").bind("notificare:didReceiveDeviceToken", function(event, data) {
	instance.notificare("registerDevice", data);
});

If for any reason this registration fails, the following event will be triggered:

1
2
3
$("body").bind("notificare:didFailToRegisterDevice", function(event, data) {
	//Handle error
});

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 if the user is actually in an authenticated session in your website. When that is the case, you may want to register the device to a user profile like shown below:

1
2
3
4
5
$("body").bind("notificare:didReceiveDeviceToken", function(event, data) {
	instance.notificare("userId", "userID");
	instance.notificare("username", "userName");
	instance.notificare("registerDevice", data);
});

Although this is possible, it is not recommended if you're going to use identifiers that are guessable or use personal data. Due to the nature of javascript doing this registration on the client-side is simply not secure and for most cases it will not be an option. If that is your case consider registering these user profiles using your server-side code and our REST 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
instance.notificare("fetchUserData", function(data) {
	//Handle user data fields
}, function(error) {
	//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
var myData = {
	firstName: "John",
	lastName: "Doe"
};

instance.notificare("updateUserData", myData function(success) {
	//Handle success
}, function(error) {
	//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. As with the registering user profiles, you may want to do this using your server-side code and our REST API.

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 website settings page to allow the user to provide a time range where messages will not be displayed generate an alert. Please note that if you are using our inbox functionality these message will still be visible there.

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

1
2
3
4
5
instance.notificare('fetchDoNotDisturb', function(data){
	//Handle start and end time
},function(error){
	//Handle error
});

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

1
2
3
4
5
instance.notificare('updateDoNotDisturb', "01:00", "08:00", function(data){
	//Handle success
}, function(error){
	//Handle error
});

Finally you will probably also need to eventually clear this time range, to do that, simply use the method below:

1
2
3
4
5
instance.notificare('clearDoNotDisturb', function(data){
	//Handle success
}, function(error){
	//Handle error
});

Disable Notifications

A good practice when using web push notifications is to allow the user to opt-out. Visitors are more likely to allow you to send push notifications if they can also quickly opt-out.

Pretty much the same way you register a device you will also be able to delete it. To do that, consider the following example:

1
2
3
4
5
6
7
8
9
10
11
...more code
$('.disable-notifications').on('click', function(e) {
	e.preventDefault();

	instance.notificare("unregisterDevice", function(data){
		//Show the enable notifications button and hide the disable
	}, function(error){
		//Handle error
	});

});

Doing this will remove the subscription from the push provider 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.