Android SDK

Installation

Forter3DS SDK supports installation via Maven

Requirements

Minimum version: Android 5.1 (API level 22)

Step 1: Add to Maven

• If the Gradle version is 7.0 and above:
  Inside your app's settings.gradle, append the following repository, provided below, to your dependencyResolutionManagement block.

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        ...
        maven {
            url "https://mobile-sdks.forter.com/android"
            credentials {
                username "<username-provided-by-forter>"
                password "<password-provided-by-forter>"
            }
        }
    }
}

• If the Gradle version is earlier than 7.0:
  Inside your app's build.gradle, append the following repository, provided below, to your repositories block.

repositories {
    ...
    maven { url 'https://maven.google.com' }
    maven {
        url "https://mobile-sdks.forter.com/android"
        credentials {
            username "<username-provided-by-forter>"
            password "<password-provided-by-forter>"
        }
    }
}

NOTE: Specify and commit the credentials to your Git. Note that these credentials are not sensitive, but we keep them private to prevent bots and search engines from accessing the repository.

Step 2: Add the Forter3DS SDK dependency

Add the Forter3DS SDK as a dependency to your app's build.gradle file under the dependencies block. Use the dependency provided below.

implementation 'com.forter.mobile:forter3ds:2.0.1@aar'

implementation("com.forter.mobile:forter3ds:2.0.1")

Step 3: Manifest Permissions

Additionally, the Forter3DS SDK requires the common permission: Internet. This permission is typically required by many applications and components. If you have not already included it in your permissions list, please add to your manifest file.

<!-- Forter3DS SDK permissions -->
<uses-permission android:name="android.permission.INTERNET" />

Initializing the SDK

The init method is utilized to configure and set up the SDK, ensuring its readiness to handle transactions effectively

The SDK must be initialized from the main Application Context. If your app is not currently using an Application class, please add one and register it in the manifest.

Signature

fun init(
    context: Context,
    config: Forter3DSConfig,
    callback: IForter3DSInitCallback?
)

Parameters

• context: An instance of the Android Context class, typically the application context.
• config: An instance of Forter3DSConfig containing configuration parameters for the SDK initialization.
• callback: An optional callback of type IForter3DSInitCallback to receive initialization status notifications.

Forter3DSConfig class

The Forter3DSConfig class encapsulates configuration parameters required for initializing the SDK. It includes the following parameters:

• merchantId: Represents the unique identifier assigned to the merchant within the application. It typically aligns with the site ID unless a PSP necessitates distinct IDs per merchant.
• siteId: The site ID associated with the merchant account.
• defaultCustomization: Customization options for the default theme.
• darkCustomization: Customization options for the dark theme.
• monochromeCustomization: Customization options for the monochrome theme.
• shouldLoadTestServers: A boolean flag indicating whether to load test servers during initialization. Should be enabled only on testing environment.

IForter3DSInitCallback Interface

The IForter3DSInitCallback interface defines callback methods to notify the client application of the initialization status. It includes the following methods:

• onInitializationSucceeded(): Invoked when the SDK initialization is successful.
• onInitializationFailed(): Invoked when the SDK initialization fails.

Usage

val context: Context = applicationContext
val config = Forter3DSConfig.Builder()
    .setMerchantId("your_merchant_id")
    .setSiteId("your_site_id")
if (BuildConfig.DEBUG) {
    config.loadTestServers()
}

Forter3DS.getInstance().init(context, config.build(), object : IForter3DSInitCallback {
    override fun onInitializationSucceeded() {
        // Handle successful initialization
    }

    override fun onInitializationFailed() {
        // Handle initialization failure
    }
})

FTR3DSCustomization class

The FTR3DSCustomization class provides customization options for the UI elements in the native challenge screen. It allows developers to customize buttons, labels, text boxes, and toolbars to match the design and branding requirements of their application.

• setButtonCustomization: Customizes background color, corner radius and text color.
• setLabelCustomization: Customizes font size, text color and font.
• setTextBoxCustomization: Customizes border color, border width and corner radius.
• setToolbarCustomization: Customizes background color, button text and header text.

To create an instance of FTR3DSCustomization, simply use its default constructor and apply the required customizations:

val customization = FTR3DSCustomization().apply {
    val button = FTR3DSButtonCustomization()
    button.setBackgroundColor("#FF7C72")
    setButtonCustomization(button, FTR3DSButtonType.SUBMIT)
    val label = FTR3DSLabelCustomization()
    label.setHeadingTextFontSize(40)
    setLabelCustomization(label)
}

Do Challenge if Needed

This method is called by the merchant's app with the managed order token obtained from the backend. If a WebView challenge is presented, the method also requires a presenting Activity for displaying the challenge UI and a ActivityResultLauncher that will receive the challenge result. If a native challenge is presented, the method requires a presenting Activity for displaying the challenge UI and a callback that will receive the challenge result.

To initiate the doChallengeIfNeeded function, provide the managedOrderToken received from the backend (see Order API.

fun doChallengeIfNeeded(
    activity: Activity?,
    launcher: ActivityResultLauncher<FTR3DSChallengeParams>,
    token: String,
    callback: IForter3DSChallengeCallback
)

Parameters

• activity: The activity responsible for presenting the challenge UI.
• launcher: The launcher that will receive the WebView challenge result.
• token: The managed order token obtained from the merchant's backend.
• callback: The callback for the native challenge result.

IForter3DSChallengeCallback interface

The IForter3DSChallengeCallback interface provides callback methods for handling challenge results during the 3DS authentication process.

Callback Methods

• onChallengeFinished: Invoked when a challenge is successfully completed. Receives a JSONObject with an encoded challenge result.
• onChallengeFail(): Invoked when a challenge fails.
• onChallengeSkipped(): Invoked when a challenge is skipped.

📘

Note: All callback methods are executed on the main thread.