SDK

Device Registration

In this guide we will dive deeper into how you should handle the device registration. When you launch() Notificare, the device will be registered as a non-push device.

When a successful device registration takes place, we will emit an intent. If you have configured a custom intent receiver as mentioned in the Implementation page, you can receive those intents by overriding the onDeviceRegistered() method from NotificareIntentReceiver.

class CustomIntentReceiver : NotificareIntentReceiver() {

    override fun onDeviceRegistered(context: Context, device: NotificareDevice) {

    }
}

You can also check the details of the currently registered device.

Notificare.device().currentDevice

The onReady() method in NotificareIntentReceiver will also be called when all Notificare modules has been launched, including a successful device registration.

Additionally, you can verify whether Notificare is ready at any point by calling Notificare.isReady or listen to the onReady event anywhere in your code by adding a Notificare.OnReadyListener as described below.

class MainActivity : AppCompatActivity(), Notificare.OnReadyListener {

    override fun onCreate(savedInstanceState: Bundle?) {
        // more code ...

        Notificare.addOnReadyListener(this)
    }

    override fun onDestroy() {
        // more code ...

        Notificare.removeOnReadyListener(this)
    }

    // region Notificare.OnReadyListener

    override fun onReady(application: NotificareApplication) {

    }

    // endregion

}

Register as a user

By default, a device is registered as an anonymous user. However, 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 tell the library you want to register as a specific user.

Notificare.device().register(
    userId = "7f42bedc-d74b-4c64-a5cf-76bcc5130b05",
    userName = "John Doe",
    callback = object : NotificareCallback<Unit> {
        override fun onSuccess(result: Unit) {

        }

        override fun onFailure(e: Exception) {

        }
    }
)

After that, the device will remain registered with that userId / userName until you explicitly register it as anonymous. Depending on the way you authenticate users, you might want to check the logged in state on launch (in the onReady) and change it if necessary. Forcing registration as anonymous can be best achieved by setting userId and userName to null.

Notificare.device().register(
    userId = null,
    userName = null,
    callback = object : NotificareCallback<Unit> {
        override fun onSuccess(result: Unit) {

        }

        override fun onFailure(e: Exception) {

        }
    }
)

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.device().updatePreferredLanguage("en-US", object : NotificareCallback<Unit> {
    override fun onSuccess(result: Unit) {

    }

    override fun onFailure(e: Exception) {

    }
})

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

Notificare.deviceManager.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:

Notificare.device().fetchUserData(object : NotificareCallback<NotificareUserData> {
    override fun onSuccess(result: NotificareUserData) {

    }

    override fun onFailure(e: Exception) {

    }
})

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

val userData: NotificareUserData = mapOf(
    /* your properties here */
)

Notificare.device().updateUserData(userData, object : NotificareCallback<Unit> {
    override fun onSuccess(result: Unit) {

    }

    override fun onFailure(e: Exception) {

    }
})

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 when it should not receive notifications. You can use this functionality in your app settings 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.device().fetchDoNotDisturb(object: NotificareCallback<NotificareDoNotDisturb?> {
    override fun onSuccess(result: NotificareDoNotDisturb?) {

    }

    override fun onFailure(e: Exception) {

    }
})

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

Notificare.device().updateDoNotDisturb(dnd, object : NotificareCallback<Unit> {
    override fun onSuccess(result: Unit) {

    }

    override fun onFailure(e: Exception) {

    }
})

Test Devices

It is possible to enable devices to be registered as test devices. This allows you to perform a wide range of tests in our dashboard by simply scanning a QR Code. In order to enable this functionality, the following steps are mandatory.

First you need to add the following URL scheme to your app's AndroidManifest.xml:

<activity android:name=".MainActivity">

    <!-- ... existing intent filters    -->

    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />

        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <data
            android:host="${notificareAppId}.applinks.notifica.re"
            android:pathPrefix="/testdevice"
            android:scheme="https" />
    </intent-filter>

</activity>

Where ${notificareAppId} must be replaced by your own app identifier (you can find that in Settings > Configure App).

When dealing with a multi-environment application, you may want to consider using your build.gradle to configure the manifestPlaceholders.

Then inside the intent handling routine in your MainActivity, you will need to handle possible intents to that URL scheme.

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    // more code ...

    if (intent != null) handleIntent(intent)
}

override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    // more code ...

    if (intent != null) handleIntent(intent)
}

private fun handleIntent(intent: Intent) {
    if (Notificare.handleTestDeviceIntent(intent)) {
        Log.d(TAG, "Test device intent handled.")
        return
    }

    // more code ...
}

The method will return true if the intent could be parsed as a Test Device registration intent. If it returns false, this means you should process the intent yourself.