connector
Core library to subscribe and receive push notifications with UnifiedPush.
To receive notifications with UnifiedPush, users must have a dedicated application, a distributor, installed on their system.
This library requires Android 4.1 or higher.
Import the library
Add the dependency to the module build.gradle. Replace {VERSION} with the latest version.
dependencies {
// ...
implementation 'org.unifiedpush.android:connector:{VERSION}'
}Expose a receiver
You need to expose a receiver that extend MessagingReceiver and override the following methods:
class CustomReceiver: MessagingReceiver() {
override fun onMessage(context: Context, message: PushMessage, instance: String) {
// TODO: handle message, eg. to sync remote data or show a notification to the user
}
override fun onNewEndpoint(context: Context, endpoint: PushEndpoint, instance: String) {
// TODO: send new endpoint to the app server
}
override fun onRegistrationFailed(context: Context, reason: FailedReason, instance: String) {
// TODO: retry depending on the reason
}
override fun onUnregistered(context: Context, instance: String){
// TODO: ask to register to another distributor
}
}class CustomReceiver extends MessagingReceiver {
public CustomReceiver() {
super();
}
@Override
public void onMessage(@NotNull Context context, @NotNull PushMessage message, @NotNull String instance) {
// TODO: handle message, eg. to sync remote data or show a notification to the user
}
@Override
public void onNewEndpoint(@NotNull Context context, @NotNull PushEndpoint endpoint, @NotNull String instance) {
// TODO: send new endpoint to the app server
}
@Override
public void onRegistrationFailed(@NotNull Context context, @NotNull FailedReason reason, @NotNull String instance) {
// TODO: retry depending on the reason
}
@Override
public void onUnregistered(@NotNull Context context, @NotNull String instance) {
// TODO: ask to register to another distributor
}
}Edit your manifest
The receiver has to be exposed in the AndroidManifest.xml in order to receive the UnifiedPush messages.
<receiver android:exported="true" android:enabled="true" android:name=".CustomReceiver">
<intent-filter>
<action android:name="org.unifiedpush.android.connector.MESSAGE"/>
<action android:name="org.unifiedpush.android.connector.UNREGISTERED"/>
<action android:name="org.unifiedpush.android.connector.NEW_ENDPOINT"/>
<action android:name="org.unifiedpush.android.connector.REGISTRATION_FAILED"/>
</intent-filter>
</receiver>Request registrations
Interactions with the distributor are done with the UnifiedPush object.
Use user's default distributor
Users are allowed to define a default distributor on their system, because UnifiedPush distributors have to be able to process a deeplink.
When you set UnifiedPush for the first time on your application, you will want to use the default user's distributor.
From time to time, like every time you starts your application, you should register your application in case the user have uninstalled the previous distributor. If the previous distributor is uninstalled, you can fallback to the default one again.
Therefore, you can use tryUseCurrentOrDefaultDistributor to select the saved distributor or the default one when your application starts (when your main activity is created for instance).
When the distributor is saved, you can call registerApp to request a new registration. It has optional parameters, the following example uses messageForDistributor and vapid. You can use instance to bring multiple-registration support to your application.
If you want, you can use the library org.unifiedpush.android:connector-ui instead, it displays a dialog explaining why the OS picker is going to ask which application to pick.
import org.unifiedpush.android.connector.UnifiedPush
/* ... */
UnifiedPush.tryUseCurrentOrDefaultDistributor(context) { success ->
if (success) {
// We have a distributor
// Register your app to the distributor
UnifiedPush.registerApp(context, messageForDistributor, vapid)
}
}import static org.unifiedpush.android.connector.ConstantsKt.INSTANCE_DEFAULT;
import org.unifiedpush.android.connector.UnifiedPush;
/* ... */
UnifiedPush.tryUseCurrentOrDefaultDistributor(context, success ->{
if (success) {
// We have a distributor
// Register your app to the distributor
UnifiedPush.registerApp(
context,
INSTANCE_DEFAULT,
messageForDistributor,
vapid
);
}
});Be aware that tryUseDefaultDistributor starts a new translucent activity in order to get the result of the distributor activity. You may prefer to use LinkActivityHelper directly in your own activity instead.
Use another distributor
You will probably want to allow the users to use another distributor but their default one.
For this, you can get the list of available distributors with getDistributors.
Once the user has chosen the distributor, you have to save it with saveDistributor. This function must be called before registerApp.
When the distributor is saved, you can call registerApp to request a new registration. It has optional parameters, the following example uses messageForDistributor and vapid. You can use instance to bring multiple-registration support to your application.
If you want, the library org.unifiedpush.android:connector-ui offers a customizable dialog that request user's choice and register to this distributor.
import org.unifiedpush.android.connector.UnifiedPush
/* ... */
// Get a list of distributors that are available
val distributors = UnifiedPush.getDistributors(context)
// select one or ask the user which distributor to use, eg. with a dialog
val userDistrib = yourFunc(distributors)
// save the distributor
UnifiedPush.saveDistributor(context, userDistrib)
// register your app to the distributor
UnifiedPush.registerApp(context, messageForDistributor, vapid)import static org.unifiedpush.android.connector.ConstantsKt.INSTANCE_DEFAULT;
import org.unifiedpush.android.connector.UnifiedPush;
/* ... */
// Get a list of distributors that are available
List<String> distributors = UnifiedPush.getDistributors(context);
// select one or show a dialog or whatever
String userDistrib = yourFunc(distributors);
// the below line will crash the app if no distributors are available
UnifiedPush.saveDistributor(context, userDistrib);
UnifiedPush.registerApp(
context,
INSTANCE_DEFAULT,
messageForDistributor,
vapid
);Unsubscribe
To unsubscribe, simply call unregisterApp. Set the instance you want to unsubscribed to if you used one during registration.
It removes the distributor if this is the last instance to unregister.