Android SDK

Suggest Edits

Integration

Minimum Supported Version required: Android 5.1 (API level 22)

  1. Add to Maven

    1. 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 "forter-android-sdk"
                password "HvYumAfjVQYQFyoGsmNAefGdR84Esqig"
            }
        }
    }
}

    2. 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 "forter-android-sdk"
            password "HvYumAfjVQYQFyoGsmNAefGdR84Esqig"
        }
    }
}

    3. NOTES: 
      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.

  2. Add the Forter3DS SDK as a 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-android:1.1.1@aar'

  3. Manifest Permissions
    Additionally, the Forter3DS SDK requires two common permissions: "internet access" and "read phone state." These permissions are typically required by many applications and components. If you have not already included them in your permissions list, please add them to your manifest file.

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

Initialization

The Application Class

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.

  1. Instantiation - You can obtain an instance of the Forter3DS object by calling Forter3DS.getInstance. This call generates a singleton object for the Forter3DS object.

  2. Initialization - To initialize the Forter3DS SDK, add the code provided on the right (Java / Kotlin) to the onCreate method of your application class.

  3. Debugging (Optional) - To assist with troubleshooting and root cause analysis in the event of an error, it is recommended to enable dev logs by adding the code provided on the right.

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

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

Forter3DS.getInstance().setDevLogsEnabled(true);

Create Transaction

Upon completion of the Init stage, Forter can collect the necessary data to create an FTRTransaction object.

To create the object, utilize the createTransaction method to create an FTRTransaction object which contains the data required for the server in order to create a transaction.

Arguments

  • dsId: the specific directory identifier, retrieved from the init call made to the server.
  • version: 3DS version, retrieved from the init call made to the server.

Usage

  • In 3DS1 flow - the directory server identifier is not required
  • In 3DS2 flow - both parameters are required

Return Value

createTransaction method returns a FTRTransaction object which contains the properties seen on the right.

These parameters are required for creating a challenge in 3DS2 flows if needed. In the case of 3DS1, all the fields will be null.

The following parameters should be used to create the threeDSMobileAppSDKData object in Adaptive Auth Transaction API call, which is usually called from the server:

  • sdkEncData: A string that represents the encrypted device data.
  • sdkAppID: The 3DS SDK uses a secure random function to generate the App ID in UUID format. This ID is unique and is generated during installation and update of the app.
  • sdkEphemeralPubKey: Returns the SDK Ephemeral Public Key. For each transaction the createTransaction method will generate a fresh ephemeral key pair and this property will hold the public key component as a String representation.
  • sdkTransID: Returns the SDK transaction ID. For each transaction the createTransaction method will generate a transaction ID in UUID format.
  • sdkReferenceNumber: A string that represents the SDK reference number.

The 3DS server expects these parameters to be encoded with base64. To convert this object to the required format, use toBase64 method.

NOTE: When making the doChallenge call, the acsTransId, threeDSServerTransId, and version parameters are mandatory (if this is the required flow). It's crucial to pass these parameters "as is" without any parsing when calling the doChallenge method.

While it's recommended to get these parameters from your server before calling doChallenge, it's advised not to store them locally. This approach helps ensure that the most up-to-date parameters are used in the doChallenge call.

Do Challenge

If Forter's decision is to decline the transaction and a verification is required, a challenge flow must be initiated. To do so, the app should call the doChallenge method.

Parameters

The doChallenge method requires the parameters provided below, with the mandatory params for each version marked with ✅ and optional values marked with '?'.

Notes:

  • activity argument passed is the Android activity instance that invoked doChallenge
  • delegate argument passed is the object that will implement the Forter3DSDelegate protocol callback methods

Return Value

doChallenge method does not return any value

Callbacks

Callback object must be implemented for notifying the app about the challenge status:

  1. onChallengeFinished: This callback will be called in case the challenge is completed
  2. onChallengeFail: This callback will be called in case the challenge failed
   Forter3DS.getInstance().doChallenge(
      this, 
      "2.1.0", 
      "a1-b2-c3-d4", 
      "null", 
      "null", 
      transaction, 
      "nds-internal-acs-approval", 
      "eyJhbGciO...", 
      "e8c73cba-9a93-4359-9152-be43363a017f", 
      "b4e8c35a-ad7f-41c6-8efd-616e4ee65479", 
      applicationContext, 
      this@CheckoutActivityKotlin
)

Updated 6 months ago