Android SDK

Device ID

Introduction

Welcome to Device ID SDK, a reliable solution for device identification and fingerprinting across your applications. This SDK provides a comprehensive set of tools to uniquely identify devices, track usage patterns, and enhance security measures through advanced device recognition techniques.

The Device ID SDK allows you to generate and manage persistent device identifiers that remain consistent across user sessions, application updates, and in various network conditions. By utilizing Device ID SDK, you can create a more secured and personalized experience for your users.

Installation Instructions

1. Prepare directory

Make sure to create a libs folder in your app module if it doesn't exist.

2. Unzip archive

Place contents of the provided ZIP archive in the libs folder.

3. Add repositories

4. Add dependency

Add the following lines to your app module's build.gradle.kts file:

5. Add packaging options

To ensure proper inclusion of native libraries (.so files) when building your app, add the following to your build.gradle.kts file:

6. Sync the project

Note on Version Conflicts

To avoid dependency version conflicts, we recommend explicitly managing all versions of dependencies used by the SDK and your project. Below is a list of libraries used by the FreedomID SDK along with their versions.
Make sure your project dependencies are aligned with these versions to ensure compatibility:

Library	Version
org.jetbrains.kotlin:kotlin-reflect	1.9.23
androidx.compose:compose-bom	2024.12.01
androidx.compose.material3:material3	Managed by BOM
androidx.compose.ui:ui-tooling-preview	Managed by BOM
androidx.lifecycle:lifecycle-runtime-compose	2.7.0
androidx.activity:activity-compose	1.9.0
com.google.accompanist:accompanist-systemuicontroller	0.28.0
androidx.biometric:biometric	1.1.0
androidx.preference:preference	1.2.1

Parameter Collection and Permissions

The Device ID SDK collects various device parameters to generate accurate fingerprints. Some of these parameters require specific permissions to be granted by the user. Additionally, certain parameters that were previously accessible without permissions may require explicit permissions on newer Android versions.

The Device ID SDK is designed to gracefully handle cases where permissions are not available, continuing to function even without any permission listed in Potential Required Permissions, though identification confidence may be reduced. Each permission may affect identification strength differently, but the Device ID SDK will automatically adapt its identification methods based on available permissions.
To ensure optimal functionality, please review the following section carefully.

Potential Required Permissions

The Device ID SDK may utilize any of the following permissions depending on your configuration:

⚠️ Warning: Some of the permissions listed below may lead to Google Play Store rejection, privacy concerns, and reduced user trust. Please review Permission Usage Risk Assessment and justify each permission carefully before implementation.

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
  <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
  <uses-permission android:name="com.google.android.providers.gsf.permission.READ_GSERVICES"/>
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  <uses-permission android:name="android.permission.QUERY_ALL_PACKAGES" />
  <uses-permission android:name="android.permission.READ_PHONE_STATE" />
  <uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
</manifest>

Permission Usage Risk Assessment

Critical Risk

REQUEST_INSTALL_PACKAGES: Allows your app to request installing other packages. Likely to cause app rejection due to security concerns, limited to app stores and device management apps, and triggers manual review processes.

High Risk

QUERY_ALL_PACKAGES: Allows querying information about all installed applications. Google Play restricted since Android 11, requires explicit justification, and is rarely approved for general-purpose applications.

READ_PHONE_STATE: Allows access to phone state and identity. Privacy-sensitive permission that requires clear justification, often rejected when used for tracking or analytics purposes.

Medium Risk

ACCESS_FINE_LOCATION: Allows precise location access. Requires core functionality justification, heavily restricted for background usage, must provide clear user benefit, and requires explicit privacy policy coverage.

READ_GSERVICES: Allows reading from Google services. Raises review flags due to being unusual

Usage

Device ID Initialization

To initialize the Device ID SDK, call the create method of the DeviceID class. This method requires one parameter:

An Android context.

Request ID Generation

Note on Type Alias
Throughout the following documentation, RequestId will be referenced as a distinct type. Please be aware that RequestId is implemented as a Kotlin type alias for String.

To generate RequestId, call the getRequestID method of the DeviceID class. This method obtains a unique identifier RequestId that will track the fingerprinting transaction through the system.
The getRequestID method takes one parameter:

A callback function that is invoked when you attempt to generate RequestId.

The process returns an IdentifierResult<RequestId> IdentifierResult Structure object, which can be either:

Success: Contains a RequestId

Error: Specifies the type of error that occurred.

Cleared: SDK's internal state has been cleared.

Here's an example:

Clear the SDK

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

Data Structures

IdentifierResult Structure

General Description

The IdentifierResult is a sealed interface representing the result of the RequestId generation process. It has three primary branches:

Success: Indicates that RequestId has ben generated successfully with RequestId as its parametric payload.

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

a. A data object for static cases

b. Or a data class for cases requiring additional information.

Cleared: Represents a clean state where identification data has been reset in the SDK.

Table 1: `IdentifierResult<T>`

Type	Details
`Cleared<Nothing>`	Implies, that the SDK has been cleared
`Error<Nothing>`	Describes various errors that could happen during `RequestId` generation process.
`Success<T>`	A successful result containing `RequestId`

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

Type	Details
`IdentificationError`	Contains a IdentificationErrors Structure object.
`VerificationError`	Indicates that the verification process failed.
`NotInitializedYet`	Represents a state where the SDK has not been properly initialized before use.
`InvalidDataError`	Indicates that provided data is corrupted, incomplete, or does not match expected formats.
`Unknown`	Represents an unknown error type.

IdentificationErrors Structure

General Description

The IdentificationErrors enum defines a set of specific error conditions that can occur during various stages of the identification process, from receiving and validating requests to processing session data and handling expired credentials.

Table: `IdentificationErrors`

Value	Details
`SESSION_PROCESSING_ERROR`	Occurs while initializing or managing the user session.
`INCORRECT_REQUEST_STRUCTURE`	Indicates that the request structure is invalid or constructed incorrectly.
`DATA_PROCESSING_ERROR`	Occurs during the processing of the provided data
`REQUEST_VALIDATION_ERROR`	Occurs when the input data fails to meet backend rules.
`REQUEST_RECEIVING_ERROR`	Represents an error that occurred while receiving the request.
`EXPIRED_DATA_ERROR`	Indicates that the data provided in the request has exceeded its validity period or timestamp and is no longer accepted by the system.

Support

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

Email: support@freedompay.kz

Device ID#

Introduction#

Installation Instructions#

1. Prepare directory#

2. Unzip archive#

3. Add repositories#

4. Add dependency#

5. Add packaging options#

6. Sync the project#

Note on Version Conflicts#

Parameter Collection and Permissions#

Potential Required Permissions#

Permission Usage Risk Assessment#

Critical Risk#

High Risk#

Medium Risk#

Usage#

Device ID Initialization#

Request ID Generation#

Clear the SDK#

Data Structures#

IdentifierResult Structure#

General Description#

Table 1: IdentifierResult<T>#

Table 2: Error (Subtype of IdentifierResult)#

IdentificationErrors Structure#

General Description#

Table: IdentificationErrors#

Support#

Device ID

Introduction

Installation Instructions

1. Prepare directory

2. Unzip archive

3. Add repositories

4. Add dependency

5. Add packaging options

6. Sync the project

Note on Version Conflicts

Parameter Collection and Permissions

Potential Required Permissions

Permission Usage Risk Assessment

Critical Risk

High Risk

Medium Risk

Usage

Device ID Initialization

Request ID Generation

Clear the SDK

Data Structures

IdentifierResult Structure

General Description

Table 1: `IdentifierResult<T>`

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

IdentificationErrors Structure

General Description

Table: `IdentificationErrors`

Support