SDK

Device Registration

In this guide we will dive deeper into how you should handle the device registration.

Before you can send notifications to your Cordova app you will need to register the device with Notificare. By default our library will automatically assign a non-push device token whenever you invoke the launch() method for the first time. This will then trigger the deviceRegistered event, as shown below:

Notificare.on('deviceRegistered', function(data) {
    //At this point you will have a non-push device which will allow you to use all the feature of Notificare, except remote notifications
});
Notificare.on('deviceRegistered', (data) => {
    //At this point you will have a non-push device which will allow you to use all the feature of Notificare, except remote notifications
});

To actually register a device with APNS (remote notifications) you will need to invoke the following method:

Notificare.registerForNotifications();
await Notificare.registerForNotifications();

Whenever you invoke this method, your app will receive an APNS device token and prompt the user with the permission dialog to receive alerts, sounds and badge. At the same time we will automatically register an anonymous device independently if the user accepts it or not. This will also trigger the deviceRegistered event, as shown below:

Notificare.on('deviceRegistered', function(data) {
    //At this point you will have a push device
});
Notificare.on('deviceRegistered', (data) => {
    //At this point you will have a push device
});

Because these tokens can change at any time you need to make sure the device registration happens every time your apps launch. The library will automatically discern if the registration should be skipped, in case nothing changes, or if it should actually update device in case a new device token is assigned. To handle this you will want to implement something like this in the ready event:

Notificare.on('ready', function(data) {
    Notificare.isRemoteNotificationsEnabled(function(status) {
        if (status) {
            Notificare.registerForNotifications();
        }
    });
});
Notificare.on('ready', async (data) => {
    const enabled = await Notificare.isRemoteNotificationsEnabled();
});

Whenever users are prompted with the dialog permission to receive alerts, sounds and badge, independently if they accepted or not, the following event will be triggered:

Notificare.on('notificationSettingsChanged', function(granted) {
    if (granted) {
        //User allowed alerts, sounds and badges
    }
});
Notificare.on('notificationSettingsChanged', (granted) => {
    if (granted) {
        //User allowed alerts, sounds and badges
    }
});

You can also at any point in your app, request your app's notification settings by invoking the following method:

Notificare.fetchNotificationSettings(function(settings) {
    //Handle settings
}, function(error) {
    //Handle error
});
const settings = await Notificare.fetchNotificationSettings();

This will give you all the information you need to know about your user's notification permissions.

You can also quickly know if a user has granted permission for alerts, sounds and badge by invoking the following method:

Notificare.isAllowedUIEnabled(function(granted) {
    //Handle success
}, function(error) {
    //Handle error
});
const allowed = await Notificare.isAllowedUIEnabled();

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 (and user has a valid session) or when the user signs in. When that is the case, you will can invoke the following:

//Note the pseudo code MyAuthClass which should be your own property that holds the user information
Notificare.registerDevice(MyAuthClass.userID, MyAuthClass.userName, function(device) => {
    //Handle success
}, function(error) {
    //Handle error
});
//Note the pseudo code MyAuthClass which should be your own property that holds the user information
await Notificare.registerDevice(MyAuthClass.userID, MyAuthClass.userName);

When you authenticate users, you will also have the need to anonymize the device whenever a user signs out. This can be done by using the method below:

Notificare.registerDevice(null, null, function(result) {
    //Handle success
}, function(error) {
    //Handle error
});
await Notificare.registerDevice(null, null);

Override Device Language

By default we will automatically collect the language and region of a device based on the locale 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:

Notificare.updatePreferredLanguage("be-NL", function(result) {
    //Handle success
}, function(error) {
    //Handle error
});
await Notificare.updatePreferredLanguage("be-NL");

Eventually you can always retrieve the preferred language by invoking the following method:

Notificare.fetchPreferredLanguage(function(result) {
    //Handle success
}, function(error) {
    //Handle error
});
const language = await Notificare.fetchPreferredLanguage();

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 (make sure you call it after the ready event):

Notificare.fetchUserData(function(result) {
    //Handle success
}, function(error) {
    //Handle error
});
const userData = await Notificare.fetchUserData();

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

// Where fields must be an array of objects retrieve from fetchUserData()
Notificare.updateUserData(fields, function(result) {
    //Handle success
}, function(error) {
    //Handle error
});
// Where fields must be an array of objects retrieve from fetchUserData()
await Notificare.updateUserData(fields);

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:

Notificare.fetchDoNotDisturb(function(result) {
    //Handle success
}, function(error) {
    //Handle error
});
const dnd = await Notificare.fetchDoNotDisturb();

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

Notificare.updateDoNotDisturb({
    start: "01:00",
    end: "07:00"
}, function(result) {
    //Handle success
}, function(error) {
    //Handle error
});
await Notificare.updateDoNotDisturb({
  start: '01:00',
  end: '07:00'
});

And eventually if you want to clear any Do Not Disturb values from this device, you can use the method below:

Notificare.clearDoNotDisturb(function(result) {
    //Handle success
}, function(error) {
    //Handle error
});
await Notificare.clearDoNotDisturb();

Disable Notifications

It is also possible to disabled remote notifications and unregister from APNS. To do that use the following method:

Notificare.unregisterForNotifications();
await Notificare.unregisterForNotifications();

Doing this will remove the device from APNS and remote notifications will no longer be sent or received. When this method is invoked, we will automatically register a device identifier that although will never receive remote notifications, you will still maintain the same user profile, inbox messages and enjoy all the other services your plan supports. You can at anytime request a re-register with APNS if you wish to.

Un-launch Notificare

Finally, it is also possible to completely remove all data for a device, both locally in your app and remotely in our servers. To do that, use the following method:

Notificare.unlaunch();
await Notificare.unlaunch();

After invoking this, all the device's data will be destroyed and cannot be undone. Also, invoking any other method in Notificare will fail and the only way to start using the SDK again, is by invoking its counterpart, the launch method.