SDK

Device Registration

In this guide we will dive deeper into how you should handle the device registration. By default, 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(device: NotificareDevice) {

    }
}
class CustomIntentReceiver extends NotificareIntentReceiver {

    @Override
    protected void onDeviceRegistered(@NotNull NotificareDevice device) {

    }
}

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

Notificare.deviceManager.currentDevice
Notificare.INSTANCE.getDeviceManager().getCurrentDevice();

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

}
public class MainActivity extends AppCompatActivity implements Notificare.OnReadyListener {

    @Override
    public void onCreate(@Nullable Bundle savedInstanceState) {
        // more code ...

        Notificare.INSTANCE.addOnReadyListener(this);
    }

    @Override
    protected void onDestroy() {
        // more code ...

        Notificare.INSTANCE.removeOnReadyListener(this);
    }

    // region Notificare.OnReadyListener

    @Override
    public void onReady(@NotNull NotificareApplication application) {

    }

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

        }

        override fun onFailure(e: Exception) {

        }
    }
)
Notificare.INSTANCE.getDeviceManager().register("7f42bedc-d74b-4c64-a5cf-76bcc5130b05", "John Doe", new NotificareCallback<Tab>() {
    @Override
    public void onSuccess(Unit result) {

    }

    @Override
    public void onFailure(@NotNull Exception e) {

    }
});

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.deviceManager.register(
    userId = null,
    userName = null,
    callback = object : NotificareCallback<Unit> {
        override fun onSuccess(result: Unit) {

        }

        override fun onFailure(e: Exception) {

        }
    }
)
Notificare.INSTANCE.getDeviceManager().register(null, null, new NotificareCallback<Unit>() {
    @Override
    public void onSuccess(Unit result) {

    }

    @Override
    public void onFailure(@NotNull Exception e) {

    }
});

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

    }

    override fun onFailure(e: Exception) {

    }
})
Notificare.INSTANCE.getDeviceManager().updatePreferredLanguage("en-US", new NotificareCallback<Unit>() {
    @Override
    public void onSuccess(Unit result) {

    }

    @Override
    public void onFailure(@NotNull Exception e) {

    }
});

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

Notificare.deviceManager.preferredLanguage
Notificare.INSTANCE.getDeviceManager().getPreferredLanguage();

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.deviceManager.fetchUserData(object : NotificareCallback<NotificareUserData> {
    override fun onSuccess(result: NotificareUserData) {

    }

    override fun onFailure(e: Exception) {

    }
})
Notificare.INSTANCE.getDeviceManager().fetchUserData(new NotificareCallback<Map<String, String>>() {
    @Override
    public void onSuccess(Map<String, String> result) {

    }

    @Override
    public void onFailure(@NotNull Exception e) {

    }
});

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

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

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

    }

    override fun onFailure(e: Exception) {

    }
})
Map<String, String> userData = new HashMap<>();
/* your properties here */

Notificare.INSTANCE.getDeviceManager().updateUserData(userData, new NotificareCallback<Unit>() {
    @Override
    public void onSuccess(Unit result) {

    }

    @Override
    public void onFailure(@NotNull Exception e) {

    }
});

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.deviceManager.fetchDoNotDisturb(object: NotificareCallback<NotificareDoNotDisturb?> {
    override fun onSuccess(result: NotificareDoNotDisturb?) {

    }

    override fun onFailure(e: Exception) {

    }
})
Notificare.INSTANCE.getDeviceManager().fetchDoNotDisturb(new NotificareCallback<NotificareDoNotDisturb>() {
    @Override
    public void onSuccess(NotificareDoNotDisturb result) {

    }

    @Override
    public void onFailure(@NotNull Exception e) {

    }
});

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

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

    }

    override fun onFailure(e: Exception) {

    }
})
NotificareDoNotDisturb dnd = new NotificareDoNotDisturb(
    new NotificareTime("23:00"),
    new NotificareTime("08:00")
);

Notificare.INSTANCE.getDeviceManager().updateDoNotDisturb(dnd, new NotificareCallback<Unit>() {
    @Override
    public void onSuccess(Unit result) {

    }

    @Override
    public void onFailure(@NotNull Exception e) {

    }
});

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>
        <action android:name="android.intent.action.VIEW" />

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

        <!-- ... existing schemes   -->

        <data android:scheme="test.nc${notificareAppId}" />

    </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 ...
}
@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // more code ...

    Intent intent = getIntent();
    if (intent != null) handleIntent(intent);
}

@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    // more code ...

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

private void handleIntent(@NonNull Intent intent) {
    if (Notificare.INSTANCE.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.