*[Offline QR Code Factor](#offline-qr-code-factor)
*[TOTP Factor](#totp-factor)
*[Session Information](#session-information)
## <a id="basic-integration" />Basic integration
## Basic integration
We will describe the steps to integrate the FuturaeKit SDK into your Android project. We are going to assume that you are using Android Studio for your development.
### <a id="get-futuraekit-sdk-for-android-via-maven" />Get FuturaeKit SDK for Android via Maven
### Get FuturaeKit SDK for Android via Maven
The *preferred* way to get the FuturaeKit SDK fro Android is through maven and the Futurae private repository.
To do so add the following lines to your `build.gradle` file:
...
...
@@ -56,7 +58,7 @@ dependencies {
Of course, make sure to specify the correct version number.
### <a id="get-futuraekit-sdk-for-android-via-maven" />Get FuturaeKit SDK for Android Manually
### Get FuturaeKit SDK for Android Manually
Alternatively, *although discouraged*, you can download the latest SDK from the [releases](https://git.futurae.com/futurae-public/futurae-android-sdk/tags), or clone this repository directly.
This repository also contains a simple demo app to show how the SDK can be integrated.
...
...
@@ -90,7 +92,7 @@ allprojects {
![][gradle-project]
### <a id="add-permissions" />Add permissions
### Add permissions
Please add the following permissions, which the FuturaeKit SDK needs, if they are not already present in your AndroidManifest.xml file:
```
...
...
@@ -106,7 +108,7 @@ Please add the following permissions, which the FuturaeKit SDK needs, if they ar
```
### <a id="basic-setup" />Basic setup
### Basic setup
We recommend using an android [Application][android_application] class to initialize the SDK. If you already have one in your app already, follow these steps:
Firstly, in your `Application` class find or create the `onCreate` method and add the following code to initialize the FuturaeKit SDK:
...
...
@@ -119,7 +121,6 @@ public class AppMain extends Application {
// overrides
@Override
publicfinalvoidonCreate(){
super.onCreate();
FuturaeClient.launch(this);
...
...
@@ -143,18 +144,18 @@ Secondly, in your `res/values` folder make sure to create a file `futurae.xml` w
**Note**: Initializing the FuturaeKit SDK like this is `very important`. Replace `{FuturaeSdkId}` and `{FuturaeSdkKey}` with your SDK ID and key.
### <a id="build-your-app" />Build your app
### Build your app
Build and run your app. If the build succeeds, you should carefully read the SDK logs in the console.
### <a id="r8-proguard" />R8 / ProGuard
### R8 / ProGuard
If you are using R8 or ProGuard to obfuscate your app, you need to include the proguard rules of the [futurae.pro](https://git.futurae.com/futurae-public/futurae-android-sdk/-/blob/master/FuturaeDemo/app/proguard/futurae.pro) file. See the [build.gradle](https://git.futurae.com/futurae-public/futurae-android-sdk/-/blob/master/FuturaeDemo/app/build.gradle) file of the FuturaeDemo app, as an example on how to do this.
## <a id="features" />Features
### <a id="callbacks" />Callbacks
## Features
### Callbacks
The SDK methods that perform API calls use callbacks as the feedback mechanism. These calls expect an object of the `FuturaeCallback` interface as an argument:
```java
publicinterfaceFuturaeCallback{
...
...
@@ -163,7 +164,7 @@ public interface FuturaeCallback {
}
```
### <a id="uri-schemes" />URI Schemes
### URI Schemes
The SDK is able to handle URI scheme calls, which can be used to either **enroll** or **authenticate** users.
Once your activity has been set up to handle the URI scheme call intents, get the intent data in the `onCreate()` method of your activity, which contains the URI that should be passed in the SDK, using the `handleUri()` method:
...
...
@@ -183,7 +184,7 @@ FuturaeClient.sharedClient().handleUri(uriString, new FuturaeCallback() {
**Note**: In case you attempt an authentication with a URI scheme call, and this authentication includes extra information to be displayed to the user, you must retrieve this information from the server and include it in the authentication response; see section [Session Information](#session-information) for details on how to do that.
Your app must be set up to receive Firebase Cloud Messaging (FCM) push notifications from our server. You can choose to receive and handle these notifications yourself, or alternatively you can use the existing infrastructure provided in the SDK. You can find more information on how to setup FCM push notifications for your app in the [Firebase Cloud Messaging Developer Guide](https://firebase.google.com/docs/cloud-messaging/).
In order to be able to receive FCM notifications, you need to specify the Firebase Messaging service inside the application section of your Manifest:
...
...
@@ -197,18 +198,18 @@ In order to be able to receive FCM notifications, you need to specify the Fireba
For this purpose, you can either use the one included in the SDK (`com.futurae.sdk.messaging.FTRFcmMessagingService`), or write your own. This service overrides two important methods:
The first one is invoked whenever a new FCM push token has been generated for the app; it is important to register this token with the Futurae backend in order to continue receiving push notifications. The `FTRFcmMessagingService` implements this functionality.
The second one is invoked whenever a new push notification (or cloud message) is received by the app. The `FTRFcmMessagingService` then processes this message and invokes the SDK accordingly.
The `FTRFcmMessagingService` is responsible for registering the app's FCM token to the Futurae server. This is important for the server to be able to issue FCM notifications for your app. The provided service handles this, however if you need to, you can write your own or extend the existing one.
If you are implementing **your own FCM notification handling**, you should register the FCM token to the Futurae server every time it changes. The call that registers the FCM token to the Futurae server is `registerPushToken()`, and it is necessary every time the FCM token is generated or is changed by FCM.
...
...
@@ -228,7 +229,7 @@ FuturaeClient.sharedClient().registerPushToken(fcmToken, new FuturaeCallback() {
});
```
#### <a id="fcm-listener-service" />FCM Listener Service
#### FCM Listener Service
The `FTRFcmMessagingService` receives FCM push notifications and handles them, according to the actions dictated by the Futurae server. You can use or extend the service provided by the SDK, or write your own. There are two distinct push notification types issued by the Futurae server: **Aprove** or **Unenroll**.
In case you want to process and handle the FCM notifications without using `FTRFcmMessagingService`, you must use the following code in order to process and handle the notifications sent by the Futurae server, inside the implementation of your own `FirebaseMessagingService` subclass:
...
...
@@ -242,7 +243,7 @@ public void onMessageReceived(RemoteMessage message) {
}
```
#### <a id="local-intents" />Local Intents
#### Local Intents
Once a Futurae FCM notification has been handled, the SDK will notify the host app using **local broadcasts**. The app should register a broadcast receiver for these intents and react accordingly. There are three distinct Intents that the notification handlers might send in a local broadcast:
*`INTENT_GENERIC_NOTIFICATION_ERROR`: Indicates that an error was encountered during the processing or handling of a FCM notification.
*`INTENT_APPROVE_AUTH_MESSAGE`: Indicates that a Push Notification Authentication has been initiated.
The Futurae Authentication Platform, uses QR Codes for different operations:
- Enroll a device for a user (online)
- Authenticate a user or transaction (online)
- Authenticate a user or transaction (offline)
The Futurae SDK supports all these functionalities. The business App can have different flows for supporting the needed functionality, or condense all QR Code operations in one. The Futurae SDK provides a handy method to identify on the fly which type of QR Code the user has scanned:
To enroll a user, you must call the `enroll()` method, using a valid code obtained by scanning an enrolment QR Code. For example, you can use a QR Code Reader Activity to scan a code and obtain the result:
To get a list of all enrolled accounts, call the following method:
```java
...
...
@@ -361,11 +384,11 @@ FuturaeClient.sharedClient().getAccountsStatus(userIds, new FuturaeResultCallbac
For each account, a list of active sessions will be returned, and each session includes a `session ID` to proceed with the authentication.
### <a id="auth-user" />Authenticate User
### Authenticate User
To authenticate (or reject) a user session, depending on the authentication factor, you can use the following methods: **QR Code Factor**, or **Push Notification Factor**.
#### <a id="qrcode-auth" />QR Code Factor
To authenticate with the QR Code Factor, scan the QR Code provided by the server and pass its contents to the following method:
#### Online QR Code Factor
To authenticate with the Online QR Code Factor, scan the QR Code provided by the server and pass its contents to the following method:
@@ -380,9 +403,9 @@ FuturaeClient.sharedClient().approveAuth(qrCodeString, new FuturaeCallback() {
});
```
**Note**: In case you attempt an authentication with a QR Code, and this authentication includes extra information to be displayed to the user, you must retrieve this information from the server and include it in the authentication response; see section [Session Information](#session-information) for details on how to do that.
**Note**: In case you attempt an authentication with an Online QR Code, and this authentication includes extra information to be displayed to the user, you must retrieve this information from the server and include it in the authentication response; see section [Session Information](#session-information) for details on how to do that.
When a Push Notification Factor session is initiated on the server side, the server will send a push notification to the app, where the user should approve or reject the authentication session. The notification is received and handled by the SDK, which in turn will send a local broadcast (see `INTENT_APPROVE_AUTH_MESSAGE`[above](#local-intents)), so that the app can perform any required actions. For example, the app might want to display a prompt to the user so that they can approve or reject the session.
The intent contains an object that describes the authentication session as an extra. This object contains the User ID and the Session ID, which are required for sending the authentication outcome to the server:
...
...
@@ -396,7 +419,7 @@ Once the outcome of the authentication has been decided by the app, it should be
**Note**: In case you attempt an authentication via push notification, and this authentication includes extra information to be displayed to the user, you must retrieve this information from the server and include it in the authentication response; see section [Session Information](#session-information) for details on how to do that.
The user might choose to reject the authentication session. Additionally, in case the session has not been initiated by the user, they might also choose to report a fraudulent authentication attempt back to the server. In this case, use the following method:
```java
booleanreportFraud=false;// Set to true to report a fraudulent attempt
...
...
@@ -429,7 +452,20 @@ FuturaeClient.sharedClient().rejectAuth(userId, sessionId, reportFraud, new Futu
});
```
#### <a id="totp-auth" />TOTP Factor
#### Offline QR Code Factor
The Offline QR Code Factor does not require any internet connection on the user's phone, to function.
To authenticate with the offline QR Code Factor, scan the QR Code provided by the server and display the relevant information to the user. If the user approves the authentication or transaction request, generate the 6-digit confirmation number that the user needs to enter in the browser:
**Note**: In case you attempt an authenticaiton with an Offline QR Code, and this authentication includes extra information to be displayed to the user, you can retrieve this information from the QR Code itself:
The TOTP Factor can be used for offline authentication, as there is no requirement for an internet connection in the app. To get the current TOTP generated by the SDK for a specific user account, call the following method:
@@ -439,7 +475,7 @@ int remainingSeconds = totp.getRemainingSecs(); // The remaining seconds of val
As seen in this example, the `nextTotp()` method returns an object that contains the TOTP itself, but also the remaining seconds that this TOTP will be still valid for. After this time, a new TOTP must be obtained by the SDK.
#### <a id="session-information" />Session Information
#### Session Information
For a given session, either identified via a `session ID` (e.g. received by a push notification) or a `session Token` (e.g. received by a QRCode scan), you can ask the server for more information about the session:
```java
...
...
@@ -482,7 +518,7 @@ public class FuturaeClient {
}
```
##### <a id="auth-extra-info" />Authentication with extra information
##### Authentication with extra information
In case it exists, you can retrieve the extra information that the user needs to review while authenticating by calling the following method on the `SessionInfo` object: