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.0@aar'

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 Forter3DS 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.

To initialize the Forter3DS SDK, call the init from the onCreate method of your application class with the required params.

public void onCreate(Bundle savedInstanceState) {
     super.onCreate(savedInstanceState);
     setContentView(R.layout.filters);
     // initialize Forter3DS
     Forter3DS.getInstance().init(this.applicationContext, config, callback);
}

override fun onCreate(savedInstanceState: Bundle?) {
     super.onCreate(savedInstanceState)
     setContentView(R.layout.checkout_activity)
     // initialize Forter3DS
     Forter3DS.getInstance().setup(this.applicationContext)
}

/**
 * Initializes the Forter 3DS SDK.
 *
 * @param context The context required for initializing the SDK.
 * @param config The configuration object containing merchant and site IDs, along with customization options.
 * @param callback The callback to be notified of initialization success or failure.
 */
fun init(context: Context, config: Forter3DSConfig, callback: IForter3DSInitCallback?)

Further documentation for Forter3DSConfig and IForter3DSInitCallback can be found within the SDK.

Do Challenge if Needed

To initiate the doChallengeIfNeeded function, provide the managedOrderToken received from the backend (see Order API. This function handles the challenge process, displaying it if required, and otherwise continuing with the transaction.

/**
 * Perform a managed order challenge if needed.
 *
 * This method is called by the merchant's app with the managed order token obtained from the backend.
 * If 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 Native challenge is presented the method requires a presenting Activity for display the challenge UI and a callback that will receive the challenge result.
 *
 * @param activity   The activity responsible for presenting the challenge UI.
 * @param launcher   The launcher that will receive the webView challenge result.
 * @param token      The managed order token obtained from the merchant's backend.
 * @param callback   the callback for the native challenge result
 */
fun doChallengeIfNeeded(
    activity: Activity?,
    launcher: ActivityResultLauncher<FTR3DSChallengeParams>,
    token: String,
    callback: IForter3DSChallengeCallback
)

Callbacks

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

/**
 * callback method for a completed challenge
 * @param challengeResponse JSONObject with encoded challenge result. {PaRes: String}
 */
fun onChallengeFinished(challengeResponse: JSONObject?)

/**
 * callback method for a failed challenge
 */
fun onChallengeFail()

/**
 * callback method for a skipped challenge
 */
fun onChallengeSkipped()