Add and integrate our Android SDK

Upgrading from version 2.1.28 to 4.0.0

Please click here if you want to see the integration guide for version 4.0.0.

All data stored by the old SDK will automatically be migrated, so the developers do not need to worry.

Integration

This guide will walk you through getting our SDK integrated with your app. Please make sure you've already generated your Firebase credentials and have checked the prerequisites.

Add Pushologies sdk to your project. Add the Jitpack publishing url to the repositories block of your gradle file depending upon your needs,
- In settings.gradle

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
        repositories {
            ...
            maven { url "https://jitpack.io" }
        }
}

In project level build.gradle

allprojects {
    repositories {
        ...
        maven { url "https://jitpack.io" }
    }
}

In app level build.gradle

repositories {
    ...
    maven { url "https://jitpack.io" }
}

Add PushSDK dependency in your app level build.gradle

dependencies {
    implementation 'com.pushologies.PushSDKLite:<VERSION>'
}

Note: You need to add -keep class com.pushologies.** { *; } to your ProGuard rules file in case you are using it.

Since this SDK uses Firebase Cloud Messaging (FCM) for push notifications, initialise the Firebase SDK if you have not already initialised. See Setup FCM Client Android App
Extend your Android Application from PushSDKApplication. ex: class <Your Application class> : PushSDKApplication()
Initialise the PushSDK

PushSDK.init(
    context = this, disableUserLocationTracking = false,
    enableGeoFencing = true, requestLocationPermissions = false
)
    .setSecretKey(<PUSH SDK API KEY>)
    .setServerKey(<PUSH SDK API SECRET>)
    .build()

Note:

PushSDK.init() will throw PushSDKException if Pushologies server API key and secret are not set.
Please make sure to request for the Location permission from your app for location related notification behaviour to work.

Optionally you can set the following parameters during PushSDK initialisation

PushSDK.init(
    context = this, disableUserLocationTracking = false,
    enableGeoFencing = true, requestLocationPermissions = false
)
    .setSecretKey(<PUSH SDK API KEY>)
    .setServerKey(<PUSH SDK API SECRET>)
    .setAppVersion(BuildConfig.VERSION_NAME)
    .setDebug(true)
  	.setCustomerId(<Your Customer Id>)
    .setColor(Color.MAGENTA)
    .setSmallIcon(R.drawable.ic_stat_ic_notitication)
    .setDownloadOption(ConnectivityMode.ALL)
    .build()

setAppVersion(appVersion : String) to set the current version of your app. This will be displayed in the dashboard for analytics.
setDebug(enable:Boolean) to enable debug mode. This provides more logs on the console, disable this on production builds
setColor(color: Int) to customize the notification banner title text color based on your brand
setSmallIcon(iconId: Int) & setLargeIcon(icon: Int) can be used to configure small and large icon of notification banner
setDownloadOption(connectivityMode: ConnectivityMode) is used to configure the SDK to use the connectivity type specified to download the content, if that connection is not available content will not be downloaded. You can use following enum values
setCustomerId(customerId: String) is to set the customer Id to know which client is using the app

enum class ConnectivityMode {
    ALL,
    WIFI,
    MOBILE,
    MOBILE_ROAMING,
    MOBILE_NO_ROAMING
}

Set Firebase token in PushSDK

FirebaseMessaging.getInstance().token.addOnCompleteListener(OnCompleteListener { task ->
        if (!task.isSuccessful) {
            Log.w(TAG, "Fetching FCM registration token failed", task.exception)
            return@OnCompleteListener
        }

        // Get new FCM registration token
        val token = task.result
        token?.let {
            PushSDK.setFCMToken(it)
        }
    })

Add the service that extends FirebaseMessagingService as per Step 3 to your app. Add the following code to that service

class SampleFirebaseMessagingService : FirebaseMessagingService() {

    override fun onMessageReceived(remoteMessage: RemoteMessage) {
        if (remoteMessage.data.isNotEmpty()) {
            PushSDK.handleNotification(
                remoteMessage.data["root"].toString(),
                remoteMessage.data["replacements"].toString()
            )
        }
    }
}

Now you are all set to receive the Pushologies notifications

Additional integration steps

To display the content that downloaded with the last received notification use this API.
```
PushSDK.launchVideo(activity: Activity)
```
Optionally you can retrieve the downloaded content and the meta data of the last received notification using following API

PushSDK.getContents(object: PushSDKContentListener{  
    override fun onContentAvailable(contents: ArrayList<HashMap<String, String>>?) {  
       /*
           ["name" : "file_name",
           "path" : "file_path",
           "expiry" : "ttl",
           "metadata":"your_meta_data"]
       */
    }  
})

PushSDK.getContents(new PushSDKContentListener() {  
    @Override  
  public void onContentAvailable(@Nullable ArrayList<HashMap<String, String>> contents) {  
          /*
           ["name" : "file_name",
           "path" : "file_path",
           "expiry" : "ttl",
           "metadata":"your_meta_data"]
       */
    }  
});

To work with tags, you need to use following APIs
- To create a tag use the API below, Note that a tag is created only if it doesn't exist on the portal already, if it exists it just subscribes your device to that tag. You can use tags to create segments, and target your devices subscribed to those tags. Note that currently we only support creating of one tag at time, so if you want to create multiple tags you will need to call this API multiple times
  fun createTag(tag: String, apiCompletionHandler: APICompletionHandler)
- To delete the tag use the API below. Please note that it doesn't delete the tag on the portal, it just unsubscribes your device from that tag.
  fun deleteTag(tag: String, apiCompletionHandler: APICompletionHandler)
- Example code

PushSDK.createTag(tag) { error ->
    showCreateTagResult(error)
}

 PushSDK.deleteTag(tag) { error ->
    showDeleteTagResult(error)
}

PushSDK.createTag("tag", error -> {
    showCreateTagResult(error);
    return;
});

PushSDK.deleteTag("tag", error -> {
    showDeleteTagResult(error);
    return;
});