iOS Push Library

iOS Push Library

Overview

The iOS Push Library is intended to securely deliver ENGAGE® content from an iOS 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 Authorization Token for securely pushing ENGAGE content

First Orion Artifactory Credentials – required for accessing the CocoaPods 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 Customer will provide First Orion:

Communication – notify the First Orion team as soon as possible if the ENGAGE-enabled host app will be an iOS application so First Orion may deliver all required configuration

Skills Required

• Apple Developer Portal
• Linux
• Swift
• Xcode
• CocoaPods

System Requirements

• MacOS
• Ruby >= 2.0
• CocoaPods >= 1.10
• CocoaPods Plugin to work with Artifactory >= 1.0.5
• Xcode >= 10
• Swift 4 or 5

Host App Requirements

• iOS 10.x or higher
• Ability to link Apple Dynamic Frameworks
• Swift (4 or 5) or Objective-C
• Provisioning Profiles
  • Host App

🚧

Cross-Platform Compatability

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

See the Cross-Platform Framework section for more detail

Host App Impact

• SDK size: ~1mb
  • Less if Bitcode-enabled
• Content push data usage: 100kb or less

Level of Effort

Configure pushlib-config.json

The pushlib-config.json file defines the configuration settings that enable network communication with the ENGAGE platform. The only step required is to include this file in the main target of the host app Xcode project. First Orion will provide you with a configuration file before integration efforts begin.

Example pushlib-config.json

{
    "test": {
 	      "pushLibHost" : "api.fo-engage.com",
        "clientId" : "2256njcldf6u6dh4r55gc06huz",
        "clientSecret" :"97hieqqt5eip53ir92he9aa23ji1dhau9uts0do6pi4lbhqgoojd",
        "serviceProviderUuid": "13f68f49-39e5-48de-9e4a-1b6e259e10a5",
        "keychainAccessGroup": "X3RCY6K2JW.com.firstorion.engage.pushlib"
    },
    "production": {
        "pushLibHost" : "api.fo-engage.com",
        "clientId" : "2256njcldf6u6dh4r55gc06huz",
        "clientSecret" :"97hieqqt5eip53ir92he9aa23ji1dhau9uts0do6pi4lbhqgoojd",
        "serviceProviderUuid": "f5cfc9ca-5968-45a0-b2a5-69a0ebe4beb7",
        "keychainAccessGroup": "X3RCY6K2JW.com.firstorion.engage.pushlib"
    }
 }

pushlib-config.json fields

The following fields are the required configuration parameters in the config file.

🚧

NOTE

There are two objects, test and production, that each contain all of these fields. These define the separate configurations for each environment of Push Library.

Xcode Application Setup

The required Xcode configuration and impact is minimal. The most important step is ensuring that the host app has the Keychain Sharing capability properly configured.

Keychain Sharing

ENGAGE Platform requires a way to map requests made via PushLib to a particular device.

PushLib handles this by creating a unique identifier for the device, sending the identifier generated during the authentication request, before making other requests to the platform. This allows devices to leverage the library’s core functionality. The identifier needs to be unique and unchanging, even if the host app containing PushLib is deleted and reinstalled. For this reason, it is permanently stored in the Keychain.

Setting Up Keychain Sharing Capability

The Keychain Sharing capability must be enabled for PushLib to access the Keychain. Specifically, a Keychain Group must be added that will match the Bundle Identifier of the main target.

In Xcode, go to the project viewer that lists the targets of the app and choose the main target. Navigate to the Signing & Capabilities tab, then click on + Capability to add a capability. Search for Keychain Sharing in the window that appears and select it.

After selecting Keychain Sharing, it will appear as a new section in the Signing & Capabilities view. Under the list of Keychain Groups, which at this point should be empty, click the + button to add a new Keychain Group.

Xcode should automatically create a Keychain Group with the same name as the Bundle Identifier in the same target. You may copy-paste the Bundle Identifier into the Keychain Groups entry field.

Confirm the Keychain Group matches the Bundle Identifier:

Verifying PushLib Config File for Keychain Access

After the correct Keychain Group has been added, check the pushlib-config.json file’s keychainAccessGroup field (for each environment). The string value for this field should be a combination of the TeamId (not the Team name), which is set as the Team in the Xcode target, and the Keychain Group.

One way to find the TeamId is to check-in Apple Developer. Another way is to search the workspace for DEVELOPMENT_TEAM. This setting is found in the Build Settings tab in the project target view. The plain value, which is equivalent to the TeamId, is shown in the search result in the search bar on the left.

Once the TeamId value has been determined, verify that the keychainAccessGroup field is correct.

It is constructed as shown in this example:

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

The suggested and preferred way to resolve the ENGAGE SDK dependencies is to access the binary from the First Orion Artifactory, which is a CocoaPod package. This particular method requires setting the correct system configurations to authenticate against Artifactory.

CocoaPod >=1.10 Requirement

The required CocoaPods version must be 1.10 or above to support the ENGAGE SDK which is compiled as an XCFramework.

Required Prerequisites

Ruby >= 2.0 installed

• CocoaPods >= 1.9 installed
• CocoaPods Artifactory Plugin >= 1.4 installed

Configure First Orion Artifactory

Install CocoaPods Artifactory Plugin

$ gem install cocoapods-art

Add First Orion Repository

To resolve ENGAGE pods, add First Orion repo to client

$ pod repo-art add cocoapods-local
"https://firstorion.jfrog.io/firstorion/api/pods/fo-cocoapods-external"

Authentication

To authenticate, please add the credentials to the client .netrc file

machine firstorion.jfrog.io
login <USERNAME>
password <PASSWORD>

Configure Podfile

Resolve Pods

Add First Orion repo to Podfile

plugin 'cocoapods-art', :sources => [
 'fo-cocoapods-external'
]

Configure ENGAGE Pods

Add ENGAGE pod to Main Application target

platform :ios, '10.0'
use_frameworks!
plugin 'cocoapods-art', :sources => [
 'cocoapods-local'
]
target 'PushLibGoldCopy' do
 pod 'EngagePushLib', '= 1.0.0'
end

Install Pods

$ pod install

Troubleshooting CocoaPods

When working with CocoaPods, it is sometimes necessary to remove the local Pod repo and to re-sync. This may need to be done occasionally when new SDK releases become available and the client’s local CocoaPods repo needs to re-sync. The following steps outline the removal of the First Orion Pod repo from the client and re-syncing.

Remove Pods from Artifactory Repo

$ pod repo-art remove cocoapods-local

Remove Local CocoaPods References

$ rm -rf ~/.cocoapods/repos/cocoapods-local

Remove CocoaPod Cache, not always required

$ pod cache clean --all 

Deintegrate Cocoapod, not always required

$ pod deintegrate 

Re-add First Orion CocoaPods Repo

$ pod repo-art add cocoapods-local
"https://firstorion.jfrog.io/firstorion/api/pods/cocoapods-local"

Install Pods from Podfile

From the project’s main directory – pod install could also be used

$ pod update

Push Library Usage

Import PushLib

In any source file that uses PushLib, the line import EngagePushLib must be included in the import statements for that file.

Initialize PushLib

Before the iOS application can securely deliver ENGAGE content to an ENGAGE-enabled device, the Push Library must be configured by the app. This is best accomplished in the AppDelegate class:

func application(_ application: UIApplication, didFinishLaunchingWithOptions
launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
// ... your app's other initialization logic
    PushLib.shared.configurePushLib(forEnvironment: .test) {
optionalPushLibError in
PushLib.shared.configurePushLib(forEnvironment: .test) { optionalPushLibError
in
            if let pushLibError = optionalPushLibError {
                switch pushLibError {
                case .notConfigured:
                    self.handleNotConfigured()
                case .configurationFailure(let _, let webResponse):
                    self.handleConfigurationFailure(webResponse: webResponse)
                case .deviceIdMissing:
                    self.handleDeviceIdMissing()
                case .deviceIdGenerationFailure:
                    self.handleDeviceIdGenerationFailure()
                case .deviceIdStorageFailure:
                    self.handleDeviceIdStorageFailure()
                case .deviceIdRetrievalFailure:
                    self.handleDeviceIdRetrievalFailure()
                default:
                    print("Unexpected PushLibError case encountered:
\(pushLibError.localizedDescription)")
               }
            } else {
                print("Push Library configuration succeeded.")
            }
        if let pushLibError = optionalPushLibError {
            print("Push Library configuration failed:
\(pushLibError.localizedDescription)")
        } else {
            print("Push Library configuration succeeded.")
        }
    }

The usage of Push Lib’s configurePushLib function is as follows:

The configurePushLib function reads pushlib-config.json, using the values for the environment specified as the forEnvironment parameter, to set up the PushLib. It also requests an authorization token from ENGAGE to use in later network requests. Once completed, and if optional parameter has been selected, it calls completion.

🚧

The following PushLibError cases may occur within this function:

notConfigured
configurationFailure
deviceIdMissing
deviceIdGenerationFailure
deviceIdStorageFailure
deviceIdRetrievalFailure

PushLibEnvironment

The environment in which to use the Push Library. An enum type.

PushLibError

PushLibError is a custom Swift Error type and is therefore an enum type.

PushLibWebResponse

Represents the API response received from a request that did not succeed.

PushLibPlatformResponse

Represents the API response received from a request to send a content push that was attempted and failed to send the push.

Retrieve Content Provider List

When the iOS app needs to get the list of accessible content providers, it may call the
getContentProviders function and used as shown:

PushLib.shared.getContentProviders { result in 
        switch(result) {
                case .success(let contentProviders):
                print("Successfully retrieved \(contentProviders.count) content
provider(s).")
                case .failure(let pushLibError):
      switch pushLibError {
                case .notConfigured:
                    self.handleNotConfigured()
                case .configurationFailure(let _, let webResponse):
                    self.handleConfigurationFailure(webResponse: webResponse)
                case .deviceIdMissing:
                    self.handleDeviceIdMissing()
                case .deviceIdRetrievalFailure:
                    self.handleDeviceIdRetrievalFailure()
                case .contentProviderError(let _, let webResponse):
                    self.handleContentProviderError(webResponse: webResponse)
                default:
                    print("Unexpected PushLibError case encountered:
\(pushLibError.localizedDescription)")
                }
        }
}

🚧

The following PushLibError cases may occur within this function:

notConfigured
configurationFailure
deviceIdMissing
deviceIdRetrievalFailure
contentProviderError

ContentProvider

A content provider, which can be retrieved from the getContentProviders function.

Content

Content of a content provider.

Push Content

When the iOS app needs to push content, it can call the sendPush function as shown:

do {
  let pushProperties = try PushProperties(aNumbers: [”+15016543210",
  ”+15011234567”], bNumber: "+15013334444")
  PushLib.shared.sendPush(withProperties: pushProperties,
programContentUuid: ”521863c3-2f10-37a2-7bcd-b268012f09a4",
contentProviderUuid:	) { optionalPushLibError in

if let pushLibError = optionalPushLibError {
  // handle any error from PushLib.shared.sendPush
  switch pushLibError {
  case .notConfigured
    self.handleNotConfigured()
  case .configurationFailure(let _, let webResponse)
    self.handleConfigurationFailure(webResponse: webResponse)
  case .deviceIdMissing
    self.handleDeviceldMissing()
  case .deviceldRetrievalFailure
    self.handleDeviceldRetrievalFailure()
  case .sendPushNetworkError(let _, let webResponse)
    self.handleSendPushNetworkError(webResponse: webResponse)
  case .sendPushPlatformError(let _, let platformResponse)
    self.handleSendPushPlatformError(platformResponse:
platformResponse)
  default:
    print("Unexpected PushLibError case encountered:
  \ (pushLibError.localizedDescription)")
  }
    } else {
      print("Pushing Content succeeded.”)
    }
  }

} catch {
  // handle any error thrown by PushProperties.init
  guard let pushLibError = error as? PushLibError else {
    print("Unexpected error encountered: \(error)")
    return
}
switch pushLibError {
case .aNumberFormatError
  handleANumberFormatError()
case .bNumberFormatError
  handleBNumberFormatError()
default:
  print("Unexpected PushLibError case encountered:
  \ (pushLibError.localizedDescription)")

   }
}

PushProperties

Properties that define a push.

📘

See Glossary for further definition of terms