Android Push Library

Android Push Library


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

1.015-July-2020Initial 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

TaskSkillsetTime of Effort
Configure build.gradle to resolve Push Library dependencies and read properties file containing credentialsGradle + Groovy15 min
Place library configuration file in appropriate locationJava5 min
Integrate and initialize Push LibraryJava + Android/Kotlin5 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 ""
  credentials (
    def artifactoryPropertiesFile =
    def artifactoryProperties = new Properties()

  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 = ""
  resolve {
    repository (
      repoKey = 'fo-libs-release-external'
      def artifactoryPropertiesFile =
      def artifactoryProperties = new Properties()

    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 in the project root using the two fields listed below
  • Insert the values of your First Orion Artifactory credentials

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


Storing the File

It is unsafe to store the 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 ://",

  "clientld" : ”260sbphxbihix3zfel4199zt2k",

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


pushlib-config.json Fields

The following items are the required core configuration parameters.

baseUrlStringBase URL for communicating with ENGAGE platform
clientIdStringIdentity credentials used for retrieving Auth Token
clientSecretStringIdentity credentials used for retrieving Auth Token
serviceProviderUuidStringService 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)


callbackCallbackCallback interface when getContentProviderList() is called

contentCallback Example

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


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

ContentProviderData Object

contentProviderUuidStringUnique value representing the program created in the Portal
preferredContentUuidStringUnique value representing preferred content program created in the Portal. If this value is returned as all zeros, the entry is not considered preferred content
contentProviderNameStringName of the Preferred Content program configured in the Portal
preferredContentNameStringName of the Preferred Content program configured in the Portal
isPreferredContentSetBooleanDetermines if content is considered preferred


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

Example Message


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


bundleContentPushBundle()Details of ENGAGE content being pushed to device
callbackCallbackCallback interface when ContentPushCallback() is called

ContentPushBundle Object

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

programUuidStringNoUnique value representing Program being delivered to ENGAGE-enabled device
If programUuid, must send contentProviderUuid
contentProviderUuidStringNoUnique value representing Content Provider and associated Preferred Content (must set on Content Provider) being delivered to ENGAGE-enabled device
bNumberStringYesDevice number that will display program content when call is received after a successful Push
Must be E.164 format
ttlSecondsIntegerNoDuration, 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
maxWeightDurationIntegerNoMax wait time, in seconds, for response from the device, to the handset, to pushing content
Recommended value: 10 seconds
keepAfterCallBooleanNoSet 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
customTextStringNoCustom 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
aNumbersListYesOriginating 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


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


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


  ContentPushBundle (
    programUuid, //nullable
    contentProviderUuid, //can be null, if sending programUuid

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"