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

Version

Date

Changes

1.0

15-July-2020

Initial release for ENGAGE Android Client Push Library

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

Task

Skillset

Time of Effort

Configure build.gradle to resolve Push Library dependencies and read properties file containing credentials

Gradle + Groovy

15 min

Place library configuration file in appropriate location

Java

5 min

Integrate and initialize Push Library

Java + Android/Kotlin

5 min

📘

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
    }
}
  1. Include JFrog BuildInfo dependency on the classpath in the buildscript{} dependencies{} closure.
classpath "org.jfrog.buildinfo:build-info-extractor-gradle:4.9.8"
  1. Include the Artifactory Gradle plugin.
apply plugin: "com.jfrog.artifactory"
  1. 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
  1. 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.

Field

Type

Description

baseUrl

String

Base URL for communicating with ENGAGE platform

clientId

String

Identity credentials used for retrieving Auth Token

clientSecret

String

Identity credentials used for retrieving Auth Token

serviceProviderUuid

String

Service Provider UUID associated with integration customer and business pushing ENGAGE content

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

Field

Type

Description

callback

Callback

Callback interface when getContentProviderList() is called

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

Field

Type

Description

contentProviderUuid

String

Unique value representing the program created in the Portal

preferredContentUuid

String

Unique value representing preferred content program created in the Portal. If this value is returned as all zeros, the entry is not considered preferred content

contentProviderName

String

Name of the Preferred Content program configured in the Portal

preferredContentName

String

Name of the Preferred Content program configured in the Portal

isPreferredContentSet

Boolean

Determines if content is considered preferred

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

Field

Type

Description

bundle

ContentPushBundle()

Details of ENGAGE content being pushed to device

callback

Callback

Callback interface when ContentPushCallback() is called

ContentPushBundle Object

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

Field

Type

Required

Description

programUuid

String

No

Unique value representing Program being delivered to ENGAGE-enabled device
If programUuid, must send contentProviderUuid

contentProviderUuid

String

No

Unique value representing Content Provider and associated Preferred Content (must set on Content Provider) being delivered to ENGAGE-enabled device

bNumber

String

Yes

Device number that will display program content when call is received after a successful Push
Must be E.164 format

ttlSeconds

Integer

No

Duration, in seconds, for content to live on the device following a successful content Push
Default is 3600
Recommended value: 960 seconds
First Orion best practice: set the TTL to 16 minutes

maxWeightDuration

Integer

No

Max wait time, in seconds, for response from the device, to the handset, to pushing content
Recommended value: 10 seconds

keepAfterCall

Boolean

No

Set if content should be kept on device after call.
Default is false
First Orion best practice: do not keep content on the device after a call or a successful push

customText

String

No

Custom text sent to bNumber and displayed during call
Recommended value: 20 char
First Orion best practice: maximum of 20 char as messages over 20 char may not display correctly on all devices

aNumbers

List

Yes

Originating numbers calling a bNumber. aNumbers must be previously uploaded to the Branded Communication Content Portal
List of up to 5,000 aNumbers in E.164 format
Cannot send UUID

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.

Error Class Name Condition Parameters
PushLibError.PlatformError Will only be returned in the ContentPushCallback.onError() when PushLib.pushContent() is called
Defines errors that are received from the PlatformError
Example error cases would be:
  • bNumber is not active
  • Maximum wait duration exceeded
  • Handset did not respond
  • etc.
  • Code: 202
  • Message: Error message from the platform
  • Response: Response from platform
PushLibError.NetworkFailure Can be seen when 4XX or 5XX http responses are received after a function call
  • Code: http response code
  • Message: Error message explaining the error
  • Response: Response from platform
PushLibError.InvalidToken Can be seen only when the library tries to referesh token but fails
Current step can be retried when this error is seen
  • Code: -1
  • Message: "Token is invalid"
  • Response: Same as message
PushLibError.Exception Sent when an Exception is caught on a functional call
  • Code: -2
  • Message: Exception message "Unknown Error" if no message found
  • Response: Same as message
PushLibError.InvalidRequest Sent when/if the fields given in ContentPushBundle are wrong
Can only be seen in the ContentPushCallback.onError() when PushLib.pushContent() is called
Based on the faulty field, code and message will be different
  • Code: -3
  • Message: "There must be at least one aNumber"
  • Response: "Empty aNumbers"
  • Code: -4
  • Message: "Invalid aNumber format"
  • Response: "Invalid aNumber"
  • Code: -5
  • Message: "Invalid bNumber"
  • Response: "Invalid bNumber"
  • Code: -6
  • Message: "Invalid UUID format"
  • Response: "Invalid UUID"

Did this page help you?