Get started

There are two approaches available for integrating your application with AppFlow

1. Docs first - Follow this guide which will explain all the relevant AppFlow concepts and allow you to set up the application gradually
2. 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;

1. To provide a basic application developers can use in flows to process payments
2. 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.