Fraud Android SDK

Guide for integrating your Forter Android SDK

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

Inside your project's settings.gradle file, append the following repository to your repositories block under dependencyResolutionManagement:

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

Inside your project's build.gradle file, append 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

Inside your application's build.gradle file add your Forter SDK dependency in the dependencies block:

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

Step 2: Add required permissions

Forter's Android SDK uses the common internet access permission. Even if you just started developing your app you've probably already added those permissions to your manifest. If you haven't, please add the following lines to your manifest file:

<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, // Include your unique Forter site ID
        mobileId // Use our / provide your existing device identifier
);

🔥 The existing Android Device ID value is recommended as the value to pass to the getDeviceId method as it is a stable PII-compliant value 🔥

Register Lifecycle Callbacks

After initiating the Forter SDK, from your application class's onCreate method, please register our built-in activity lifecycle callbacks:

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

Send your App Active Event

After initiating the SDK and registering the Activity Lifecycle callbacks, send your first track to Forter's servers by calling the trackAction event. --> note the exact method is only available in our portal documentation

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

Re-Review your onCreate method

@Override
public void onCreate() {
    super.onCreate();

     // Use our / provide your existing device identifier
    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 // Provide your mobile device Unique ID
    );

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

    // Send the 'app active' 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 The value retrieved as. the DeviceIUID ("mobileUID") should be sent in the backend API requests as the value for the connectionInformation.forterMobileUID key. backend API requests

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 mobileUID in backend and Forter API requests

Send the mobileUID 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 mobileUID 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"
  },
  "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.