📱Android Programming
Last updated
Last updated
These instructions assume that you will likely be adding the AuthenticAction™ SDK to a project within one of the common IDE, such as Android Studio. Also, the instructions in this section assume a development methodology leveraging Gradle build configuration to declare inclusion of the applicable AuthenticAction™ archive dependencies.
Note: If your application development build tools do not include the use of Gradle, it will be the responsibility of the developer to appropriately declare build inclusion of the AuthenticAction™ SDK archive files appropriate for the build methodology being used.
Note: These instructions assume that you will likely be adding the AuthenticAction™ SDK to an Android project within one of the common IDE, such as Android Studio.
You can import AuthenticAction™ SDK into your project by manually importing *.arr files downloaded from a file repository. Details of the repository will be shared with you by IronVest.
Note: The filename, shown as “<collector-release>.aar”, may have a formal release naming, following the convention, “ivaasdk.x.x.x.aar”, where “x.x.x” indicates the major version, subversion, and revision of the SDK. If more than one file was provided, put all the files in the same folder.
Edit your projects module-level application ‘gradle’ file. Add the following line to declare the import of the aar file:
Edit your gradle build file to add the lines below to declare the necessary dependencies:
For the dependencies above it's important to specify the version of the 3rd party library that is actually in use by your application to avoid versions collision
The AuthenticAction™ SDK includes a process known as the “collector agent” which, when instantiated, provides a simple means of monitoring user interaction and activity related to your application without requiring extensive programming on your part. Collector agent provides you with an option to start biometric session to protect sensitive areas of your application with user's biometrics. You can control whether and where to show camera preview in the background. Collector agent exposes API to submit custom events (for example in cases when the input is not collected automatically by the collector agent). In this section you can learn how to achieve that.
This section describes:
How to declare and initialize the collector agent
How to set and update Customer Session ID (CSID), User ID (UID) and Context
How to display camera preview during biometric auth session
How to start and stop biometric authentication during specific activity
How to submit custom events
Make sure your project has an Application class like (and it is declared in Manifest file). Declare the following variables inside Application class of your app. Customer ID (CID) and Base URL to be provided by Ironvest specifically for your AuthenticAction™ instance:
Assign and initialize SDK inside onCreate() callback of Application class. If Client Session ID (CSID) & UserID are available here from the application lifecycle perspective, you can use this opportunity to set the initial values. Usually CSID and UserID are available when a users is already authenticated and logged-in into your service.
Client Session ID (CSID) & UserID are used to correlate the activity to a specific user and user's session. Identifying the user is necessary to be able to perform biometric authentication, while assigning user activity to a particular session is needed for session validation and follow-up investigation. These values may change throughout the application lifecycle and need to be updated accordingly to reflect the changes to the SDK. Context designates a particular activity performed by the user and is useful for correct and intuitive data representation. All these values can be set at once or separately, depending on the application state and needs.
Start by declaring collectorAgent variable inside the relevant Activity / Fragment class of your application:
Set the values inside onCreate() method of that Activity / Fragment class
To display the preview of the camera, first add the following camera preview UI element to the xml file of the activity:
(NOTE: you can adjust the layout width and height to fit preferred UI)
Next, declare the following variables inside of your Activity class:
Then, add the following code inside of the onCreate() method of your Activity class:
CollectorCameraPreview supports multiple customization options, which is controlled via xml attributes or respective functions/properties.
Supported starting version0.0.65 (2024-06-1) and above
Preview customization: preview scale type (fit, fill, etc.), camera preview fade in/out animation duration.
Overlay customization: custom color or image resource, scale type, bounds adjustments, visibility strategy (always visible or follow actual camera preview visibility)
Supported starting version0.0.71 (2024-07-1) and above
You can now decide whether to keep the last captured frame in the preview after biometric capture is stopped or leave it blank. See preview_isDisplayLastFrameEnabled option below
The following example explicitly demonstrates all custom xml attributes with their default values:
Start authentication:
Stop authentication:
The following is an example of how to start authentication automatically on switching back to the client app from device Settings (following permissions adjustment):
Optionally, authentic action can be named with actionID, thus can be configured remotely with different capture frequency if matches server configuration.
Supported starting version 0.0.59 (2024-05-1) and above
Since 0.0.75 (2024-10-01)
Since 0.0.76 (2024-10-02) startAuth and stopAuth functions are thread-safe
The startAuth function returns an AuthStartTask object, which allows you to track the task's state. By adding a listener, the task will notify you of intermediate signals (e.g., waiting for configuration completion, initialising the camera, etc.) and terminal signals (success, cancel, failure).
Only one task can be active at a time. Any attempt to start a new AuthenticAction™ flow will cancel the ongoing task.
Or:
The task can also be converted into a Flow (asFlow) or used within a coroutine as a suspend function (await). However, when used as a coroutine, the task will only receive the terminal signal.
As flow:
As coroutine:
The task also supports cancellation. Cancelling a task is equivalent to calling CollectorAgent.get().stopAuth(). The latter, by the way, also triggers the cancellation signal for the ongoing task.
There are overloaded methods for startAuth. By default, startAuth relies on the setOnAuthCompletedListener callback (i.e., when the SDK setup is completed). Therefore, any attempts to call startAuth before the SDK initialisation is complete will result in the task's immediate completion with a terminal signal.
However, your application may want to delay the start of the AuthenticAction™ until the ongoing SDK setup is complete. To achieve this, call startAuth with the awaitAuthSetup parameter set to true. This changes the task's behaviour (only if the SDK setup is incomplete): instead of terminating, the task will receive intermediate signals. This provides an alternative approach to starting startAuth without relying on the setOnAuthCompletedListener.
However, if the ongoing SDK setup fails due to network connectivity issues, the task will receive a terminal signal. To mitigate this, an additional parameter, awaitAuthSetupNetworkConnection, can be set along with awaitAuthSetup. This further modifies the task's behaviour: instead of receiving a terminal signal, a network failure will result in an intermediate signal. The SDK will automatically retry the setup and resume the task. Keep in mind that without a network connection, the task may remain active indefinitely.
To submit external input events that are not collected automatically by the Collector library please use the following SDK function:
Since 0.0.73 (2024-09-10)
Single SDK instance is suffice for the most usage scenarios. However, SDK supports an ability to clear current instance. This might be useful for advanced scenario, when SDK is used only in limited application scope. To clear existing instance simply perform the following functions:
Do not attempt to use instance of CollectorAgent after cleanup. These attempts result in errors. SDK re-initialisation steps are required before using CollectorAgent again.
Jetpack Compose full support is coming soon. In the current version automatic collection and reporting of the form field values may not perform correctly. You're encouraged to use custom fields collection API in that case.
The SDK generates logs throughout its execution. The logs are being written to logcat. Please refer to the Android Studio documentation for how to review and retrieve these logs.
Debug information (logs) can be controlled via:
In case you are experiencing issues when building release application using SDK's .aar files you might need to isolate each .aar file into separate modules, as shown in a figure 2 below.
Additionally create build.gradle file for each isolated module and paste the following content, adjusting actual .aar file name ("auth-sdk-release.aar" in this example):
Optionally, in multi-module project it is a good practice to create separate android module that declares isolated modules as api dependencies along with the list of dependencies of the section "Manual importing of the Android Archive Repository (“aar”) File" (step 2). This approach centralises all SDK components in one place, making it clear and reusable.
The SDK requires various permissions to perform correctly. The following permissions are required:
Take pictures and record video
Device location
The optimal app design should explain how these permissions are utilized and inform the users to enable them.
By default CollectorCameraPreview has a 50% transparent white overlay, which suits most scenarios. However, if you need a clear image with no overlay, you can remove it either in XML or programmatically.
