Get started
There are two approaches available for integrating your application with AppFlow
- Docs first - Follow this guide which will explain all the relevant AppFlow concepts and allow you to set up the application gradually
- Code first - Jump to the quick guide to get your application integrated with AppFlow, allowing you to interact with it and other applications before you dive into detailed documentation
Dependencies
As of AppFlow 2.2.4, all AppFlow artifacts are published to Github Packages instead of jcenter
. This is due to JFrog shutting down jcenter.
Add the below entry to your repositories
closure in the root build.gradle
file. Note that unfortunately Github requires authentication for programmatic access of public packages (see this thread for details on this issue). This means that you must authenticate with a Github username and generate a PAT (personal access token) in order to access the dependencies as per below. If you or your organisation don't already have a Github account, you can sign up for one here.
maven {
name = "AEVI-AppFlow"
url = uri("https://maven.pkg.github.com/aevi-appflow/*")
credentials {
username = <your Github username>
password = <your Github personal access token with `read:packages` enabled>
}
}
AppFlow artifacts version 2.2.3 and earlier will still be available via jcenter
up until 1st of February 2022.
The AppFlow APIs are built with Java 8 which means your application must compile with Java 8. Please see the official Android docs for how to compile/target Java 8.
Payment Flow Service API
Add the dependency listing below in the dependencies section of your build.gradle
file in order to integrate the Payment Flow Service API
.
implementation 'com.aevi.sdk.pos.flow:payment-flow-service-api:<version>'
API Constants
The AppFlow APIs themselves are designed to facilitate communication between applications via a defined set of data structures. They are however decoupled from what the values or content of these data structures are, in order to keep them as flexible and configurable as possible. Instead, the data values are defined in this documentation and provided as constants via a separate library.
The constants library is stored in a separate repo. You can find the latest version details and view the defined data constants there.
To include these in your project use
implementation `com.aevi.sdk.flow:api-constants:<version>'
Sample Code
The documentation will refer to relevant sections of the samples. The Payment Service Sample
is our open source payment application sample that has two purposes;
- To provide a basic application developers can use in flows to process payments
- To provide code examples of how to interact with the
Payment Flow Service API
as a payment application
You can find the source code for the sample here, but it is usually more productive to clone the repo instead and work with the code in Android Studio.
API Overview
For details please see the API Overview
Application guidelines
The following guidelines should be followed when you implement your application to work well with AppFlow and to provide a seamless and consistent experience for the merchant.
ProGuard
If you are using proguard to obfuscate your application you will need to ensure that the AEVI classes are not processed as AppFlow makes use of JSON serialisation and deserialisation for API models.
-dontwarn com.aevi**
-keep class com.aevi** { *; }
This can be done simply by including the following in your ProGuard file
Permissions
All communication between applications in a flow is sent as JSON which means the data between applications can be sent over any channel. By default the Android implementation of AppFlow will use the Android Messenger
to send and receive messages. This means message sizes are limited to the size set by the Android Binder limit (usually max 1 MB). To avoid this issue AppFlow can be configured (via a configuration provider) to send messages over a Websockets
instead.
Whether AppFlow uses Android Messenger or Websockets is down to the runtime configuration of FPS.
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
As Websockets are network based, all applications developed for AppFlow must request these permissions in the manifest.
Application lifecycle
Due to the service-based architecture, any activities called throughout the flow are all created in separate tasks. See the Android docs for more info on tasks. All your activities will be started with the Intent.FLAG_ACTIVITY_NEW_TASK
flag set.
This means there is no way of leaving a flow "stack" and coming back to it later in a traditional Android sense.
FPS does provide certain controls to the merchant to resume/skip/cancel applications and it is important that you implement your applications in a way that plays well with these controls.
It is up to you how to manage user interactions (back / home) and lifecycle events like onStop()
and onDestroy()
based on what suits your application use case best. There are however a few things to consider.
As mentioned above, FPS does give merchants the option to resume or skip an application via notification controls. This means that if the user presses back or home from your application, and you don't send back an API response due to this, your app may be receive an event asking it to resume the UI.
If your application is performing sensitive and crucial processing of some form, it is recommended that you take the following approach;
- Override
onBackPressed()
in the activity and show a message if merchant tries to press it during this processing - Ensure the processing itself is carried out independent of the activity - i.e in a service separate from the API service (which may be created for each request), or in a separate thread in the API service. Use the activity only as a way to interact with the merchant, not to process anything important or keep important state.
- Send back a response and wrap up all processing upon an
onStopped()
callback
If your application does not perform any form of processing and doesn't keep state, the simplest approach is to not do anything as part of being stopped or destroyed, and simply restart the activity upon resume events.
Manifest flags
<activity
...
android:excludeFromRecents="true"
android:resizeableActivity="false"/>
All activities that are launched inside a flow must define these flags inside the activity
tag.
This will ensure the activities leave no trace once they are finished, which is important for the flow. In addition, it stops merchants from accidentally splitting the screen into multiple activities when using the application.
Animations / Transitions
In order to make AppFlow as smooth as possible, it is recommended that any flow service activities disable enter/exit animations/transitions. Any activity started via the stage models will already have the Intent.FLAG_ACTIVITY_NO_ANIMATION
flag set, but for exit animations the activities need to call overridePendingTransaction(0, 0)
after calling finish()
(or ideally, overriding finish()
and doing it there).
Next steps
At this point you we hope you have a good understanding of how AppFlow works and have a basic integration completed.
Problems? Questions?
If you are having any problems or questions, please check out our support pages.
Learn more about AppFlow
You can explore the full AppFlow documentation here.