SDK

Device Registration

In this guide we will dive deeper into how you should handle the device registration. The very first time you instantiate our library we will automatically assign a device token to the browser, this will allow you to continue using all the functionality of Notificare until you actually decide you want to register for WebPush or Safari Website notifications. Obviously until you actually register for notifications, you'll not receive any remote notifications although messages will still end up in the in-app message inbox if implemented.

To start the request for notifications, you should wait until our library is fully initialized. Make sure you only call it after the onReady callback function is triggered:

1
2
3
4
5
6
7
8
9
10
11
12
document.addEventListener("DOMContentLoaded", () => {

	//This instantiates the library
	const notificare = new Notificare();

	notificare.launch(); // When launched for the first time Notificare will create a device token for this browser

	notificare.onReady = (application) => {
		notificare.registerForNotifications();
	}

});

The onReady callback method signals your website that the Notificare library has loaded its initial configuration and is ready to be used. Only after that, you should actually attempt to use any functionality of our library. 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 until you proper on-board a user, explain why you would like to use remote notifications, before you actually prompt the user with the remote notifications permission dialog. 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
25
26
27
28
29
30
31
32
33
34
35
36
37
...more code

const notificare = new Notificare();

// Let's check if remote notifications are supported and only launch if it is supported
// This will make sure that nothing is registered in Notificare if a browser does not support remote notifications
if (notificare.isWebPushSupported()) {
	notificare.launch();
}

// This example expects an element with an id named enableNotifications
let button = document.getElementById("enableNotifications");
button.style.display = 'none';

...more code

notificare.onReady = (application) => {

	//If it does let's check if it is already enabled
	if (notificare.isWebPushEnabled()) {

		//Remote notification are enabled already, proceed
		notificare.registerForNotifications();

	} else {
		//It's not let's on-board the user by showing the enable notifications button
		button.style.display = 'block';

		button.addEventListener('click', (e) => {
			e.preventDefault();
			notificare.registerForNotifications();
		});

	}
}

... more code

Whenever you invoke the notificare.registerForNotifications() method, our library will attempt to create a push subscription (for WebPush) or request a device token (for Safari WebsitePush) depending on the browser your visitor is using. If there is any problem with your the following callback function:

1
2
3
notificare.didFailToRegisterForNotifications = (error) => {
	//Handle this error accordingly
}

On the other end if your configuration is correct and a device is registered, it will trigger the following callback function:

1
2
3
notificare.didRegisterDevice = (device) => {
	//When triggered a device has been successfully registered
}

Please note that this callback method will also be trigger the very first time you instantiate the library assigning a device token to your browser, independently if you have invoked notificare.registerForNotifications().

If for any reason, the device registration fails, the following callback method will be triggered:

1
2
3
notificare.didFailToRegisterDevice = (error) => {
	//Handle error accordingly
}

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
notificare.registerDevice("MY_USER_ID", "MY_USER_NAME");

Although this is possible, it is not recommended. If you're going to use identifiers that are guessable or use personal data like an email. Due to the nature of javascript, doing this registration on the client-side is 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.

Override Device Language

By default we will automatically collect the language and region of a device based on the NSLocale of the device. For most cases this will be enough but for those cases where you would like to override the device language and region combination to a strict selection of languages, you can do so by invoking the following method:

1
2
3
4
5
notificare.updatePreferredLanguage("en-US").then((response) => {
	//Handle success
}).catch((e) => {
	//Handle error
});

Eventually you can always retrieve the preferred language by accessing the following property:

1
notificare.preferredLanguage;

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
notificare.fetchUserData().then((fields) => {
	console.log(fields);
}).catch((e) => {
	//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
notificare.updateUserData({
	firstname: "John",
	lastname: "Doe"
}).then((response) => {
	//Handle success
}).catch((e) => {
	//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
notificare.fetchDoNotDisturb().then((dnd) => {
	console.log(dnd);
}).catch((e) => {
	//Handle error
});

You can update the Do Not Disturb values for a device, using the following method:

1
2
3
4
5
6
7
8
notificare.updateDoNotDisturb({
	start: "01:00",
	end: "07:00"
}).then((dnd) => {
	console.log(dnd);
}).catch((e) => {
	//Handle error
});

Finally you will probably also need to eventually clear the Do Not Disturb period. To do that, simply use the method below:

1
2
3
4
5
notificare.clearDoNotDisturb().then((dnd) => {
	console.log(dnd);
}).catch((e) => {
	//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 subscribe a device for WebPush or Safari Website Push, you will also be able to unsubscribe. To do that, consider the following example:

1
2
3
4
5
...more code
button.addEventListener('click', (e) => {
	e.preventDefault();
	notificare.unregisterForNotifications();
});

Invoking this method will remove the subscription for web push notifications (if applicable) and assign a new token to the device. This will mean that you can still keep using all the other features of Notificare but obviously the user will not receive remote notifications anymore. You can at any point register for notifications again if you wish.