Android SDK

Freedom ID

Introduction

Welcome to the Freedom ID SDK integration guide! This guide will help you smoothly integrate the Freedom ID SDK into your Android app, enabling secure authentication and user data permission management within the Freedom Holding ecosystem. Freedom ID serves as a single point of entry for users, ensuring top-level security and privacy while managing data permissions and accessing multiple services.

The Freedom ID SDK is available for both Android (API level 24 and above) and iOS platforms. This guide specifically covers the Android platform. Let's get started! 🚀

Getting Started

Prerequisites

Before you begin integrating the Freedom ID SDK into your Android app, ensure you have the following:

An Android app project with a minimum API level of 24.

An API key provided by Freedom Pay.

The Freedom ID SDK AAR file provided by Freedom Pay

❓ How to get API KEY and AAR?
In order to get your API KEY and AAR you need to contact Freedom Pay providing the following data:
ApplicationID
Signing Fingerprint from your Google Play Account

Installation Instructions

Automatically
You can add the AAR via Project Structure's Dependency Tab as specified in the official docs here.

Manually
Alternatively, you can use this method:

Place the freedom-id-sdk.aar in the libs directory of your app module. If the libs directory doesn’t exist, create it at the root of your app module (e.g., app/libs)

Add the AAR file as a dependency in the build.gradle file of your app module and settings.gradle

Sync the project

Usage

Initialize the SDK

To initialize the Freedom ID SDK, call the create method of the FreedomID class. This method requires two parameters:

The API key provided by Freedom ID.

The application context.

Authorize a User

To authorize a user, call the authorize method of the FreedomID class. This method initiates the authorization flow.
The authorize method takes three parameters:

The FragmentManager of the activity or fragment where the authorization flow will be displayed.

An array of DataGrants that the user needs to grant.

A callback function that will be invoked when the authorization flow completes.

The authorization process returns an AuthResult object, which can be either:

Success: Contains a GrantedProfile object.

Error: Specifies the type of error that occurred.

Here's an example:

Clear the SDK

To clear the SDK, call the clear method of the FreedomID class.
This method clears the SDK's internal state and releases any resources used during the authorization process.

Authorization Flow

App Initialization

When the user opens the app, it automatically checks if there are any accounts tied to their device.

Account Check

If an account exists: The user is navigated directly to the Home Screen, where their account(s) are displayed.

If no account exists: The user is taken to the Authentication Screen to log in. After successful authentication, the user is redirected to the Home Screen.

Authentication Screen Interaction

The user can log in using any of these methods:

Entering their phone number and receiving an OTP code via SMS.

Entering their email and password as credentials.

Entering their phone number and password as credentials.

Optionally, users can enable 2FA for additional security. To enable 2FA, they need to manage their settings in their Freedom ID account on the web at https://passport.freedompay.kz

Home Screen Interaction

On the Home screen, users see their account(s).

Users select an account for which they need to request data permissions and apply fingerprint

Request for Permissions

After selecting an account, the app presents the Permissions Request Screen.

Users review the requested permissions (e.g., access to specific user data).

User Decision

Permissions Granted: The host app is granted the requested permissions.

Permissions Denied: The app returns to the Home Screen or informs the user that permissions are needed to proceed.

Completion

Once permissions are granted, the user is notified of successful authorization, and the SDK communicates the result back to the host app.

Data Structures

DataGrants Structure

This enum represents a set of permissions that a host application can request from the SDK to grant access to specific profile data.
Each constant corresponds to a particular piece of user information, allowing the host app to selectively request access based on its needs.
Below is a table describing the different DataGrants available in the Freedom ID SDK:

Enum Constant	Value	Description
`READ_DATE_OF_BIRTH`	`read.data_of_birth`	Grants access to the user's date of birth
`READ_FIRSTNAME`	`read.firstname`	Grants access to the user's first name
`READ_LASTNAME`	`read.lastname`	Grants access to the user's last name
`READ_PATRONYMIC`	`read.patronymic`	Grants access to the user's patronymic
`READ_COUNTRY`	`read.country`	Grants access to the user's country
`READ_NATIONALITY`	`read.nationality`	Grants access to the user's nationality
`READ_GENDER`	`read.gender`	Grants access to the user's gender
`READ_IDENTIFIER`	`read.identifier`	Grants access to the user's identifier such as citizen's ID
`READ_PHONE`	`read.phone`	Grants access to the user's phone number
`READ_EMAIL`	`read.email`	Grants access to the user's email address
`READ_PHONES`	`read.phones`	Grants access to the user's phone numbers
`READ_EMAILS`	`read.emails`	Grants access to the user's email addresses

GrantedProfile Structure

The GrantedProfile data class represents a user's profile information that is accessible after the required read permissions have been granted by the host application via the SDK.

AuthResult Structure

The AuthResult is a sealed interface representing the result of an authentication process. It has two primary branches:

Success: Indicates a successful authentication with the granted user profile as its payload.

Error: Represents various types of errors that may occur during the authentication process. Each error type is modeled either as :

A data object for static cases

Or a data class for cases requiring additional information.

Table 1: `AuthResult`

Type	Details
`Error`	Describes various authentication errors.
`Success`	A successful result containing a GrantedProfile object.

Table 2: `Error` (Subtype of `AuthResult`)

Type	Details
`ParsingError`	Indicates an error during parsing.
`IncorrectApiKey`	Indicates an invalid API key.
`ComponentValidationError`	Represents a component validation error.
`DataProcessingError`	Indicates an error in data processing.
`UtilityError`	Represents a general utility error.
`TransmissionError`	Contains a TransmissionGrants object.
`Network`	Contains a NetworkError object.
`AccessDenied`	Indicates access denial.
`ConfigurationError`	Represents a configuration error.
`AuthError`	Indicates a general authentication error.
`Unknown`	Represents an unknown error type.
`UserCancelled`	Indicates that the user cancelled the operation.
`DataGrantsCannotBeEmpty`	Indicates that the data grants array is empty.

TransmissionErrors Structure

The TransmissionErrors enum defines a set of possible errors that can occur during the transmission of requests in an authentication or communication process.
Each error represents a specific issue related to the request's structure, identification, application integrity, or the process of sending and receiving requests.

Table: `TransmissionErrors`

Value	Details
`INCORRECT_REQUEST_STRUCTURE`	Indicates that the request structure is invalid or constructed incorrectly.
`IDENTIFICATION_ERROR`	Represents an issue with identifying the request sender.
`APP_INTEGRITY_ERROR`	Occurs when the application's integrity cannot be verified.
`AUTHENTICATION_FAILED`	Indicates a failure in authenticating the request or sender.
`REQUEST_SENDING_ERROR`	Represents an error that occurred while sending the request.
`REQUEST_RECEIVING_ERROR`	Represents an error that occurred while receiving the request.

NetworkError Structure

The NetworkError sealed interface defines a set of possible errors that may occur during network operations.
Each subtype of NetworkError represents a specific issue, such as connection failures, stream interruptions, or problems with request/response handling.

Table: `NetworkError`

Type	Description
`ConnectionError`	Indicates a failure to establish a network connection.
`StreamError`	Represents an issue with the data stream during transmission.
`CodeError`	Occurs when the response contains an unexpected or invalid status code.
`BodyError`	Indicates a problem with the response body, such as being incorrectly constructed or missing.
`UnknownError`	Captures any unspecified or unexpected network error.

Support

If you have questions or need help, feel free to reach out! 👋

Email: support@freedompay.kz

Freedom ID#

Introduction#

Getting Started#

Prerequisites#

Installation Instructions#

Usage#

Initialize the SDK#

Authorize a User#

Clear the SDK#

Authorization Flow#

App Initialization#

Account Check#

Authentication Screen Interaction#

Home Screen Interaction#

Request for Permissions#

User Decision#

Completion#

Data Structures#

DataGrants Structure#

GrantedProfile Structure#

AuthResult Structure#

Table 1: AuthResult#

Table 2: Error (Subtype of AuthResult)#

TransmissionErrors Structure#

Table: TransmissionErrors#

NetworkError Structure#

Table: NetworkError#

Support#

Freedom ID

Introduction

Getting Started

Prerequisites

Installation Instructions

Usage

Initialize the SDK

Authorize a User

Clear the SDK

Authorization Flow

App Initialization

Account Check

Authentication Screen Interaction

Home Screen Interaction

Request for Permissions

User Decision

Completion

Data Structures

DataGrants Structure

GrantedProfile Structure

AuthResult Structure

Table 1: `AuthResult`

Table 2: `Error` (Subtype of `AuthResult`)

TransmissionErrors Structure

Table: `TransmissionErrors`

NetworkError Structure

Table: `NetworkError`

Support