Integration Guides

Fraud Android SDK

Guide for integrating your Forter Android SDK

Suggest Edits

This guide is for installing Forter's SDK for native Android applications! Note that you'll need a Forter portal account and your unique Forter credentials to complete an SDK integration. The steps below outline the high-level integration flow.

Step 1: Install the SDK

Forter SDK is available in Forter's private Maven repository.

Get Forter SDK via Maven

Gradle version 7.0 and above

In your root-level (project-level) Gradle settings file (<project>/settings.gradle), add the following repository to your dependencyResolutionManagement block:

maven {
    url "https://<forter-android-mobile-sdk-link>"
    credentials {
        username "<forter-user-name>"
        password "<forter-password>"
    }
}
Earlier Gradle versions

In your module (app-level) Gradle file (usually <project>/<app-module>/build.gradle.kts or <project>/<app-module>/build.gradle), add the following repository to your repositories block:

maven {
    url "https://<forter-android-mobile-sdk-link>"
    credentials {
        username "<forter-user-name>"
        password "<forter-password>"
    }
}

The credentials should be specified and are available within your Forter portal. These credentials aren't sensitive but we keep these private to avoid caching by bots and search engines.

Add the Forter SDK as a dependency

In your module (app-level) Gradle file (usually <project>/<app-module>/build.gradle.kts or <project>/<app-module>/build.gradle), add the following dependency:

implementation 'com.forter.mobile:fortersdk:3.0.1'
  • Note the latest version listed in the repo is the latest stable version

Step 2: Add required permissions

The Forter Android SDK requires internet access to operate. If you haven’t already included these permissions in your AndroidManifest.xml file, please add the following lines:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Step 3: Initiate the SDK ✨

Forter's Android SDK should be initialized from the main Application Context. If your app is not currently using an Application Class, please add one and register it in your app's Manifest.

Add the following lines to your application class's onCreate method.

String mobileId = ForterIntegrationUtils.getDeviceUID(this); 

// Get ForterClient instance and initiate it with the application context 
IForterSDK ftr = ForterSDK.getInstance();
ftr.init(this,
        AppConstants.FORTER_SITE_ID,
        mobileId
);

🔥 We recommend to initialize Forter's SDK with the UID retrieved from getDeviceUID method as it is a stable PII-compliant value 🔥

Register Lifecycle Callbacks

After initializing the SDK in the onCreate() method of your application class, please register ForterSDK callbacks. The callback registration process differs based on your ForterSDK version.

ForterSDK 3.0.0 and above

Register for token updates using the built-in token update listener. The token received here will be required for the Validation API and should be the value of the forterMobileUID attribute.

ForterSDK.getInstance().registerForterTokenListener(new ForterTokenListener() {
      @Override
      public void onForterTokenUpdate(@NonNull String forterMobileUID) {
           // Forter token updated
      }
});

ForterSDK versions below 3.0.0

For older SDK versions, register the Activity Lifecycle Callbacks after initialization:

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.ICE_CREAM_SANDWICH) {
    registerActivityLifecycleCallbacks(ftr.getActivityLifecycleCallbacks());
}

Send initial event

After initialization and callback registration, send your first tracking event:

forter.trackAction(TrackType.APP_ACTIVE); // for sending 'app active' event

Re-Review your onCreate method

@Override
public void onCreate() {
    super.onCreate();
    String mobileId = ForterIntegrationUtils.getDeviceUID(this);
    
    // Get ForterClient instance and initiate it
    IForterSDK ftr = ForterSDK.getInstance();
    ftr.init(this,
            AppConstants.FORTER_SITE_ID, // your unique Forter site ID
            mobileId // your device identifier
    );
    
    // Register for token updates (ForterSDK >= 3.0.0)
    ForterSDK.getInstance().registerForterTokenListener(new ForterTokenListener() {
        @Override
        public void onForterTokenUpdate(String forterMobileUID) {
            // Forter token updated
        }
    });

    // Start generic activity-based navigation tracking (ForterSDK < 3.0.0)
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.ICE_CREAM_SANDWICH) {
        registerActivityLifecycleCallbacks(ftr.getActivityLifecycleCallbacks());
    }

    // Send initial tracking event
    ftr.trackAction(TrackType.APP_ACTIVE);
}

Make sure you use your siteId found in your dedicated Forter portal from the appropriate environment and then initiate the SDK using the following command:

Step 4: Provide Your Own Unique Identifier (Optional) :person-with-pouting-face:

Forter's SDK requires a unique mobile device identifier to link the activity and behavioral data collected by the SDK to the specific device and user. This identifier should be:

  1. Specific to each device
  2. Does not mutate from a user's app session
  3. PII compliant

Forter recommends using the ANDROID_ID. To set the mobileUID use the following command:

ForterIntegrationUtils.getDeviceUID(this)

For Official Android Best Practices see the link here

Important If you are using ForterSDK version prior to 3.0.0, this value should correspond to the forterMobileUID field in the server-side Validation API's connectionInformation object. For version 3.0.0 and above, the value that should be sent in the Validation API is the one returned by the listener.

Casing While Forter's system has no casing preference, the mobileUID generated via the SDK must match the casing of the mobileUID that is passed to the Validation API at the time of transaction in order for Forter's system to correctly connect the SDK data to the backend, Validation API's data.

Step 5: Send Event Data 🏬

In order to keep our SDK as lightweight as possible, Forter SDK does not collect navigation and custom activity events by default. These events should be called on relevant screens and actions. For instance, if a user searches for an item in the app and then proceeds to select a specific color, size, customization, a navigation event should be called with the FTRSDKNavigationTypeSearch value. The method and type should only be called once and no additional details like size, color, brand, etc. need to be included.

Forter provides 2 methods for adding custom event:

  1. TrackAction - Actions performed by the user such as: removing items from cart, adding items to cart, logging into account, attempting to initiate a payment. The data included in this method can be a String or a Dictionary.
ForterSDK.getInstance().trackAction(TrackType.ADD_TO_CART, item_id); //  add to cart event syntax
  1. TrackNavigation - Events where there's a context change like: navigating to a different product page or search result.
ForterSDK.getInstance().trackNavigation(TrackType.NavigationTypeCheckout); // nav to checkout

Step 6: Test/View your mobile events 📈

Once you've integrated the mobile SDK in sandbox (using your sandbox SiteId), you can look up events being passed to Forter for a specific mobileUID using our Sandbox Mobile Events Viewer. This gives developers visibility into how Forter is receiving and storing mobile events.

Step 7: Include Forter token in backend and Forter API requests

Send the Forter token (or mobileUID if using SDK version prior to 3.0.0) generated by the Forter SDKs to your backend when an order is placed via your native mobile application.

This will allow Forter to connect behavioral and cyber data collected on the mobile applications to the order data sent from your backend. Merchants are in charge of how the token is passed and most will pass it securely via API request headers. In the case of native mobile app orders, make sure that the following fields are populated:

Step 8: Include UniqueId in your Forter API requests ✅

  1. orderType: "MOBILE", "iOS", or "ANDROID" depending on your OS ("MOBILE" can be used for either OS)
  2. forterMobileUID: This should be populated instead of the forterTokenCookie if your app is fully native including your checkout page. If you use a webview for the checkout page, please review our Webview Integration.
  3. mobileAppVersion: should reflect the version of the app the user is on

Example Android Request

{
  "orderId": "Example_android123",
  "orderType": "ANDROID",
  "timeSentToForter": 1415287568000,
  "checkoutTime": 1415273168,
  "connectionInformation": {
    "customerIP": "177.58.61.102",
    "userAgent": "v2023.5.2 (Debug), Android 9",
    "forterMobileUID": "2d43a0c77de616gggggafc6e5cd38b7b2581115e25_1yo2+SZsrbBEqfIWlUSVOA=="
  },
  "totalAmount": {
    "amountUSD": "99.95"
  }
  ...
}

Step 9: Deploy to Production 🚀

Merchants are in complete control of how and when they deploy Forter's SDK into their production environment. You'll work closely with your implementation team to ensure a seamless deployment of our SDK within your mobile app versions.

Updated about 1 month ago