Android Push Library

Android Push Library

Overview

The Android Push Library is intended to deliver ENGAGE® content from an Android mobile application securely to an ENGAGE-enabled device. The Library provides the secure functionality to Push ENGAGE content by using an OAuth authentication scheme and setting the provided clientId and clientSecret in the pushlib-config.json file of the host app.

Library Version History

Pre-Integration Steps

📘

First Orion will provide the following during pre-integration:

clientId/clientSecret - identity credentials used to retrieve a valid Access Token for securely pushing ENGAGE content

First Orion Artifactory Credentials - required for accessing the Maven repository in which the Push Library is published in the First Orion artifact repository

*pushlib-config.json - configuration file for the host app to communicate with the ENGAGE platform

📘

Integration Customers will provide First Orion:

Communication - notify the First Orion team as soon as possible if the ENGAGE-enabled host app will be an Android application so First Orion can deliver all required configurations

Skills Required

• Java/Kotlin
• Android
• Gradle + Groovy

System Requirements

• Android Studio
• Gradle 4.0+
• Java 1.8+
• Host app written in native Android language
  • Java
  • Kotlin

🚧

Cross-Platform Compatability

Cross-platform frameworks are not supported or compatible with the ENGAGE SDK

Host App Requirements

• Android API level >= 14 (Android 4.4+)
• Written in Java or Kotlin

Level of Effort

📘

Testing the Library integration steps will take roughly 20 min and will require:

• Update of configuration file with Credentials and Service Provider UUID

• Push ENGAGE content from device using Service Provider approved aNumber to ENGAGE-enabed bNumber device

• Check Contact created on ENGAGE-enabled bNumber

• Make phone call to device using aNumber that was pushed to ENGAGE-enabled bNumber device

Resolve Library Dependencies

The ENGAGE Push Library is published in the First Orion artifact repository. Credentials to access the repository will be provided by First Orion before integration efforts begin.

❗️

These artifact repository credentials:

• should be securely stored
• should never be checked into a source code repository
• should be appropriately retrieved during integration and app build processes

Configure build.gradle

Consuming the library requires configuration in the host apps build.gradle file in the same manner as adding any ordinary Android dependency.

Edit Top-Level build.gradle File

1. Add the following maven{} repository closure inside the buildscript.repositories{} closure.

maven (
  url "https://firstorion.jfrog.io/firstorion/fo-libs-release-external/"
  credentials (
    def artifactoryPropertiesFile =
rootProject.file("artifactory.properties”)
    def artifactoryProperties = new Properties()
    artifactoryProperties.load(new
FilelnputStream(artifactoryPropertiesFile))

  username = artifactoryProperties[’username•) // The user name
  password = artifactoryProperties[’password’) // The password
    }
}

2. Include JFrog BuildInfo dependency on the classpath in the buildscript{} dependencies{} closure.

classpath "org.jfrog.buildinfo:build-info-extractor-gradle:4.9.8"

3. Include the Artifactory Gradle plugin.

apply plugin: "com.jfrog.artifactory"

4. Add the artifactory{} closure to resolve the Android Push Library.

artifactory {
  contextUrl = "https://firstorion.jfrog.io/firstorion/"
  resolve {
    repository (
      repoKey = 'fo-libs-release-external'
      def artifactoryPropertiesFile =
rootProject.file("artifactory.properties”>
      def artifactoryProperties = new Properties()
      artifactoryProperties.load(new
FilelnputStream(artifactoryPropertiesFile))

    username = artifactoryProperties(’username'J // The user name
    password = artifactoryProperties(’password'] // The password
    maven = true
    }
  }
}

Edit App-Level build.gradle File

1. Add the Android Push Lib dependency in the dependencies{} closure.

implementation 'com.firstorion.engage:pushlib:1.0.0' //Push Lib dependency

2. Once added, click the Sync now link in Android Studio for the host app to consume the library.

📘

Please reach out to the First Orion integration team with any issues consuming the library

Setting Artifactory Credentials

When setting the First Orion Artifactory credentials, the best practice is to set the values in a properties file, which will be ignored by the host app source code management and will not be checked into a source code repository.

In the project root:

• Create a properties file named artifactory.properties in the project root using the two fields listed below
• Insert the values of your First Orion Artifactory credentials

username=external-user
password=9zqcvu8desy

The build.gradle file will be responsible for reading the credentials in order to securely connect to the First Orion artifact repository.

❗️

Storing the artifactory.properties File

It is unsafe to store the artifactory.properties containing credentials file into a source code repository

Configure pushlib-config.json

The pushlib-config.json file is the main configuration point permitting communication with the ENGAGE platform. The only step is to place the configured file in the assets/ directory of the host app. First Orion will provide an accurate and configured file before integration efforts begin.

PushLib initializes itself once the application begins and will read the configuration file pushlib-config.json in the assets folder. If an error occurs during this process, the error message PushLibConfigException will be generated.

Example pushlib-config.json

{

  "baseurl": "https ://api.fo-engage.com",

  "clientld" : ”260sbphxbihix3zfel4199zt2k",

  "clientSecret” :"u9pkzfravmcurjgksuswzp931dfztfaq6tn8gbt4jq6x8hfxnd",
  "serviceProvideruuid": "084d4d4f-ef79-4294-a875-73991882a897”

}

pushlib-config.json Fields

The following items are the required core configuration parameters.

Library Usage

The ENGAGE Push Library will allow your Enterprise’s Android app to securely deliver ENGAGE content to ENGAGE-enabled apps. After configuring the pushlib-config.json file with the First Orion provided details, the library will be auto-initialized by adding the dependency to your project's build.gradle file.

Initialize PushLib

Once the Push Lib is added to a project's build.gradle file and successfully retrieved from the First Orion Artifactory, it is automatically initialized at the same time the host app is initialized.

Retrieve Content Provider List

Retrieve Content Provider List is a function that will provide a list of Content Providers (contentProviderUuids) with additional Preferred Content details (preferredContentUuids) when Preferred Content is set for a Content Provider associated with the Service Provider. The preferredContentUuid is used in the Push Content function to deliver ENGAGE content.

The Retrieve Content Provider List is not a required function but provides flexibility when a Service Provider needs the ability to retrieve a list of Content Providers and associated Preferred Content to Push.

fun getContentProviderList(callback: ContentProviderCallback)

Parameters

contentCallback Example

private val contentCallback = object : ContentProviderCallback {
  override fun onContent»Received(contents: List<ContentProviderData>) {
    listAdapter.submitList(contents)
  }
  override fun onError(error: PushLibError) {
    // Show error message
 }
}

Success

If the Content Provider list retrieval was successful, the onContentReceived() callback will be triggered and the ContentProviderData object will be present.

ContentProviderData Object

Error

If the Content Push was unsuccessful, the onError() callback will be triggered.

Example Message

PushLib.getContentProviderList(contentCallback)

Push Content

Pushing ENGAGE content to enabled devices is the core functionality of the library. To deliver ENGAGE content to a device, the pushContent() function should be called with the appropriate parameters.

fun pushContent (
  bundle: ContentPushBundle,
  callback: ContentPushCallback
)

Parameters

ContentPushBundle Object

Detail of ENGAGE content being pushed to device, including aNumber and bNumber.

PushContentCallback Example

private val pushContentCallback = object : Content PushCallback {
  override fun onContentPushed() {
    // show success message
  }
  override fun on Error (error: PushLibError) {
    // show error message
  }
}

Success

If the content was successful, the onContentPushed() callback will be triggered.

Error

If the Content Push was unsuccessful, the onError() callback will be triggered.

Example

PushLib.pushContent(
  ContentPushBundle (
    programUuid, //nullable
    contentProviderUuid, //can be null, if sending programUuid
    bNwnber,
    ttlInSeconds,
    maxWaitDuration,
    keepAfterCall,
    customText,
    Numbers
  ),
  pushContentCallback
)

PushLib Network Error Handling

There are five different error cases that the host app may receive from PushLib. All error classes defined are children of the Kotlin sealed class PushLibError. This class has two parameters: code: Int and message: String.