Setup

Notes

• Make sure you have already created an Application before starting the integration process.
• If your company uses any type of firewall, you will have to allow the Incognia IP. Contact us to receive this information.

Android 12 Support

If your app targets Android 12, you must use our SDK only on versions 6.2 or superior.

Minimum requirements

First, check out if you fulfill the SDK minimum requirements.

Requirement	Recommended Version	Minimum Version
Minimum Android SDK version	Android API 16	Android API 16
Google Play Services Ads	17.+	17.+
Google Play Services Location	17.1+	17.+

Dependencies

Update the top-level build.gradle script of your project to include the Incognia maven repository:

allprojects {
  repositories {
      maven { url "https://repo.incognia.com/android/" }
      ...
  }
}

If your project uses Android Gradle Plugin version 7 or newer, you have to include the Incognia maven repository in the settings.gradle file instead:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        maven { url "https://repo.incognia.com/android/" }
        ...
    }
}

In your app-level build.gradle file, add the following dependencies.

Android X

dependencies {
  // Required
  implementation 'com.incognia:incognia:6.6.4'
   
  // Google Play Services
  implementation 'com.google.android.gms:play-services-location:17.0.0'
  implementation 'com.google.android.gms:play-services-ads-identifier:17.0.0'
}

After updating your app-level build.gradle, the project must be synced for the changes to take effect.

Update Android manifest

Add the following <uses-permission> tags inside the <manifest> tag of your AndroidManifest.xml file.

AndroidManifest.xml

<manifest>
  <!-- Required for connectivity access -->
  <uses-permission android:name="android.permission.INTERNET" />
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

  <!-- Required for location services -->
  <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
  <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

  <!-- Allows the SDK to restart itself after the device is rebooted -->
  <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>
</manifest>

To improve Incognia SDK behavior on the background, the following permission may also be added in the same place. Further information about location permissions can be found here. Please note that the current Google Play Store policy has requirements about how your app functionality relates to this permission.

AndroidManifest.xml

<manifest>
  <!-- Allows the SDK to collect location data while in background -->
  <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION"/>
</manifest>

There are a few optional permissions that the SDK may also use if available. If you are interested, more explanation about the manifest permissions can be found here.

Add Incognia's config file to your project

The Incognia SDK initialization relies on the presence of a incognia.xml file in the main/res/values directory of your project. To access the configuration file, go to Apps section on Incognia dashboard and download the configuration file.

The config properties semantics are explained here.

Initializing the SDK

Inside the onCreate method of your Application class, insert the following code to initialize the Incognia SDK.

Kotlin

import com.incognia.Incognia

class MyApplication : Application() {
  
    override fun onCreate() {
        super.onCreate()

        //Initializes the Incognia SDK     
        Incognia.init(this)
    }
}

Java

import com.incognia.Incognia;

public class MyApplication extends Application {

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

        //Initializes the Incognia SDK
        Incognia.init(this); 
    }
}

Tips

• For instructions on how to create your own implementation of the Application class, please check the official Android documentation.
• If you intend conditionally initialize the Incognia SDK, please check this section.

If the SDK was initialized properly, your Logcat output will contain the following logs.

Logcat

I/Incognia: Incognia 6.6.4 is running
I/Incognia: Incognia 6.6.4 is running
I/Incognia: Device Installation ID: <YOUR-DEVICE-INSTALLATION-ID>
I/Incognia:
╔══════════════════════════════════════════════════════════════════════════════════════════╗
║                                Incognia Diagnostics                                      ║
╠══════════════════════════════════════════════════════════════════════════════════════════╣
║ Requirements          ║ Status ║ Troubleshooting                                         ║
╔══════════════════════════════════════════════════════════════════════════════════════════╗
║ Wifi enabled          ║ Yes    ║                                                         ║
║ Location enabled      ║ Yes    ║                                                         ║
║ Internet available    ║ Yes    ║                                                         ║
║ Permissions granted   ║ Yes    ║                                                         ║
╚══════════════════════════════════════════════════════════════════════════════════════════╝

The table identifies the main elements required for Incognia to work properly. When a requirement is not met, a description is shown with information regarding what this requirement enables and what must be done for it to be satisfied.

Testing

After integrating the SDK, the wizard will wait for an event to be sent in order to validate that the integration was successful.

Request runtime permissions

The previous step started the Incognia SDK but your application still needs to request the location permissions (i.e., ACCESS_FINE_LOCATION and ACCESS_BACKGROUND_LOCATION) from the user in order to fully unlock the location capabilities of the SDK.

We recommend that the permissions are requested as shown in the Android documentation.

Attention

Without the Manifest.permission.ACCESS_FINE_LOCATION, most features will not be available. It is extremely important that the user is asked for permission and that the app has a relevant reason to do so. If you are targeting Android 12, you also must ask for Manifest.permission.ACCESS_COARSE_LOCATION. Asking for the Manifest.permission.ACCESS_BACKGROUND_LOCATION is optional but greatly recommended.

What's next?

From here, you can either complete the production integration with our APIs by using the Installation ID or follow the steps to test the Incognia solution with SDK-only integration. In this mode, you will receive access to a dashboard that displays Incognia's risk scores without needing to integrate the APIs.