Android destination SDK for IBM Cloud Event Notifications service Version 0.2.0

Android destination client library to interact with various IBM Cloud Event Notifications Service.

Table of Contents

• Prerequisites
• Installation
  • Gradle
• Using the SDK
• Questions
• Issues
• Open source @ IBM
• Contributing
• License

Overview

The IBM Cloud Event Notifications Service Android destination SDK allows developers to register for FCM destiantion of Event Notifications service in IBM cloud.

Service Name	Artifact Coordinates
Event Notifications Service	com.ibm.cloud:eventnotifications-destination-android:0.2.0

Prerequisites

• An IBM Cloud account.
• An Event Notifications Instance
• An IAM API key to allow the SDK to access your account. Create one here.

Installation

The current version of this SDK is: 0.2.0

Each service's artifact coordinates are listed in the table above.

The project artifacts are published on the public Maven Central artifact repository. This is the default public repository used by maven when searching for dependencies. To use this repository within a gradle build, please see this link.

To use the Event Notifications Android destination SDK, define a dependency that contains the artifact coordinates (group id, artifact id and version) for the service, like this:

Gradle

compile 'com.ibm.cloud:eventnotifications-destination-android:0.2.0'

Using the SDK

SDK Methods to consume

• Installation
• Initialize SDK
  • Include SDK with Gradle
    • Initialize SDK
• Register for notifications
  • Receiving notifications
  • Unregistering from notifications
• Event Notifications destination tags subscriptions
  • Subscribe to tags
  • Retrieve subscribed tags
  • Unsubscribe from tags
• Notification options
  • Adding custom DeviceId for registration
  • Sending Delivery Status for notifications

Installation

Include SDK with Gradle

Configure the Module level build.gradle and Project level build.gradle files.

1. Add the following dependencies to your Project level build.gradle file.

   buildscript {
   	repositories {
   	        google()
                   mavenCentral()
   	}
   	dependencies {
   	  classpath "com.android.tools.build:gradle:7.0.3"
         classpath 'com.google.gms:google-services:4.3.10'
   	}
   }
   allprojects {
        repositories {
   	  google()
         mavenCentral()
   	}
   }

2. Add SDK dependency to your Module level build.gradle file.

   dependencies {
   	........
       implementation platform('com.google.firebase:firebase-bom:29.0.0')
       implementation 'com.google.firebase:firebase-messaging'
       implementation 'com.ibm.cloud:sdk-core:9.15.0'
   
       implementation 'com.ibm.cloud:eventnotifications-destination-android:0.2.0'
       .......
   }

   Note: Use the latest build tools (API 33). The minimum support version of android SDK is Android 5.1(API Level 22).

3. Add the Google Play services dependency to your Module level build.gradle file at the end, after the dependencies{.....}:

   apply plugin: 'com.google.gms.google-services'
   

4. Configure the AndroidManifest.xml file. Refer the example here. Add the following permissions inside application's AndroidManifest.xml file.

   <uses-permission android:name="android.permission.INTERNET"/>
   <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
   <uses-permission android:name="android.permission.WAKE_LOCK" />
   

5. Add the Firebase Cloud Messaging (FCM) intent service filters for the REGISTRATION event notifications:

       <service android:name="com.ibm.cloud.eventnotifications.destination.android.ENPush" android:exported="true" >
           <intent-filter>
               <action android:name="com.google.firebase.INSTANCE_ID_EVENT" />
           </intent-filter>
       </service>

6. Add the google-services.json in Android application module root directory. For more information on how to add this file, see Setup the SDK on FCM.

Initialize SDK

Initialize the sdk to connect with your Event Notifications service instance.

import com.ibm.cloud.eventnotifications.destination.android.ENPush;

String instanceGUID = "<instance_guid>>";
String destinationID = "<instance_destination_id>";
String apiKey = "<instance_apikey>";

ENPush enPush = ENPush.getInstance();
enPush.setCloudRegion(ENPush.REGION_US_SOUTH); // Set your region

enPush.initialize(getApplicationContext(),instanceGUID,destinationID, apiKey);

• region : Region of the Event Notifications Instance.
• ENPush.REGION_US_SOUTH
• ENPush.REGION_UK
• ENPush.REGION_SYDNEY
• ENPush.REGION_FRANKFURT
• ENPush.REGION_MADRID

Register for notifications

Use the ENPush.registerDevice() API to register the device with FCM destination in Event Notifications service.

The following options are supported:

• Register without userId:

   //Register Android devices
   enPush.registerDevice(new ENPushResponseListener<String>() {
   	
   	@Override
   	public void onSuccess(String deviceId) {
   	   //handle successful device registration here
   	}
  
   	@Override
   	public void onFailure(ENPushException ex) {
   	   //handle failure in device registration here
   	}
   });

• Register with UserId. For userId based notification, the register method will accept one more parameter - userId.

   // Register the device to Event Notifications
   enPush.registerDeviceWithUserId("userId",new ENPushResponseListener<String>() {
   	
   	@Override	
   	public void onSuccess(String deviceId) {
   		//handle successful device registration here
   	}
  
   	@Override	
   	public void onFailure(ENPushException ex) {
   		//handle failure in device registration here
   	}
   });

The userId is used to pass the unique userId value for registering for Event notifications.

Receiving notifications

To recieve notification when app is in foreground, implement onMessageReceived of FirebaseMessagingService. Refer the sample app for example usage.

Unregistering from notifications

Use the following code snippets to un-register from Event Notifications.

enPush.unregister(new ENPushResponseListener<String>() {
	
	@Override
	public void onSuccess(String s) {
		// Handle success
	}

	@Override
	public void onFailure(ENPushException e) {
		// Handle Failure
	}
});

Note: To unregister from the UserId based registration, you have to call the registration method. See the Register without userId option in Register for notifications.

Event Notifications destination tags subscriptions

Subscribe to tags

The subscribe API will subscribe the device for a given tag. After the device is subscribed to a particular tag, the device can receive notifications that are sent for that tag.

Add the following code snippet to your Android mobile application to subscribe to a list of tags.

// Subscribe to the given tag
enPush.subscribe(tagName, new ENPushResponseListener<String>() {
	
	@Override
	public void onSuccess(String arg) {
		System.out.println("Succesfully Subscribed to: "+ arg);
	}

	@Override
	public void onFailure(ENPushException ex) {
		System.out.println("Error subscribing to Tag1.." + ex.getMessage());
	}
});

Retrieve subscribed tags

The getSubscriptions API will return the list of tags to which the device is subscribed. Use the following code snippets in the mobile application to get the subscription list.

// Get a list of tags that to which the device is subscribed.
enPush.getSubscriptions(new ENPushResponseListener<List<String>>() {
	
	@Override
	public void onSuccess(List<String> tags) {
		System.out.println("Subscribed tags are: "+tags);
	}

	@Override
	public void onFailure(ENPushException ex) {
		System.out.println("Error getting subscriptions.. " + ex.getMessage());
	}
})

Unsubscribe from tags

The unsubscribeFromTags API will remove the device subscription from the list tags. Use the following code snippets to allow your devices to get unsubscribe from a tag.

// unsubscibe from the given tag ,that to which the device is subscribed.
push.unsubscribe(tagName, new ENPushResponseListener<String>() {
	
	@Override
	public void onSuccess(String s) {
		System.out.println("Successfully unsubscribed from tag . "+ tag);
	}

	@Override
	public void onFailure(ENPushException e) {
		System.out.println("Error while unsubscribing from tags. "+ e.getMessage());
	}	
});

Notification options

Adding custom DeviceId for registration

To send DeviceId use the setDeviceId method of ENPushNotificationOptions class.

	ENPushNotificationOptions options = new ENPushNotificationOptions();
	options.setDeviceid("YOUR_DEVICE_ID");

Note: Remember to keep custom DeviceId unique for each device.

Sending Delivery Status for notifications

You can send notification status (SEEN/OPEN) back to Event Notifiation service, implement sendStatusEvent function to use this.

Based on when notification was received by intercepting the notification, you can send back SEEN and when its opened you can send back OPEN.

To use this function example is given below

For status open -

ENPush.getInstance().sendStatusEvent("en_nid", ENStatus.OPEN, listener);

For status seen -

ENPush.getInstance().sendStatusEvent("en_nid", ENStatus.SEEN, listener);

Multidex support prior to Android 5.0

Versions of the platform prior to Android 5.0 (API level 21) use the Dalvik runtime for executing app code.

1. Add the following in your gradle file,

android {
...
   defaultConfig{
    ....
      multiDexEnabled true
    ....
   }
...
}
...
dependencies {
  .....
  compile 'com.android.support:multidex:1.0.1'
  ....
}

2. In the manifest.xml file add teh following, A

<application 
    android:name="android.support.multidex.MultiDexApplication"

Troubleshooting

Application crashes when register a device on android v6.0

Fix: Issue is in Android 6 and it is version specific. Please update the build.gradle file under app with below code.

dependencies {
	........
	implementation('com.google.guava:guava') {
		version { strictly '29.0-android' }
	}
	........
}

Questions

If you are having difficulties using this SDK or have a question about the IBM Cloud services, please ask a question at Stack Overflow.

Issues

If you encounter an issue with the project, you are welcome to submit a bug report. Before that, please search for similar issues. It's possible that someone has already reported the problem.

Open source @ IBM

Find more open source projects on the IBM Github Page

Contributing

See CONTRIBUTING.

License

The IBM Cloud Event Notifications Service Android destination SDK is released under the Apache 2.0 license. The license's full text can be found in LICENSE.