Device Registration

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

Before you can send notifications to your Flutter app you will need to register the device with Notificare. By default our plugin 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.onEventReceived.listen((NotificareEvent event) {
    if (event.name == "deviceRegistered") {
        //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();

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.onEventReceived.listen((NotificareEvent event) {
    if (event.name == "deviceRegistered") {
        //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.onEventReceived.listen((NotificareEvent event) async {
    if (event.name == "ready") {
        if (await notificare.isRemoteNotificationsEnabled()) {
            notificare.registerForNotifications();
        }
    }
});

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.onEventReceived.listen((NotificareEvent event) {
    if (event.name == "notificationSettingsChanged") {
        NotificareNotificationSettingsChangedEvent notificationSettingsChangedEvent = event.data as NotificareNotificationSettingsChangedEvent;
        if (notificationSettingsChangedEvent.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:

try {
    NotificareNotificationSettings settings = await notificare.fetchNotificationSettings();
    //Handle Success
} catch(e){
    //Handle Error
}

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:

bool granted = await notificare.isAllowedUIEnabled();

Register as a user

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:

try {
    //Note the pseudo code MyAuthClass which should be your own property that holds the user information
    NotificareDevice response = await notificare.registerDevice(MyAuthClass.userID, MyAuthClass.userName);
    //Handle Success
} catch(e){
    //Handle Error
}

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:

try {
    NotificareDevice response = await notificare.registerDevice(null, null);
    //Handle Success
} catch(e){
    //Handle Error
}

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:

try {
    await notificare.updatePreferredLanguage("be-NL");
    //Handle Success
} catch(e){
    //Handle Error
}

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

try {
    String response = await notificare.fetchPreferredLanguage();
    //Handle Success
} catch(e){
    //Handle Error
}

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):

try {
    List<NotificareUserData> response = await notificare.fetchUserData();
    //Handle Success
} catch(e){
    //Handle Error
}

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

try {
    //Where fields must be an array of objects retrieved from fetchUserData()
    List response = await notificare.updateUserData(fields);
    //Handle Success
} catch(e){
    //Handle Error
}

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:

try {
    NotificareDeviceDnD response = await notificare.fetchDoNotDisturb();
    //Handle Success
} catch(e){
    //Handle Error
}

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

try {
    NotificareDeviceDnD response = await notificare.updateDoNotDisturb({start: "01:00", end: "07:00"});
    //Handle Success
} catch(e){
    //Handle Error
}

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

try {
    await notificare.clearDoNotDisturb();
    //Handle Success
} catch(e){
    //Handle Error
}

Disable Notifications

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

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:

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.