How to Invoke the Device Data Collector into Mobile Apps using the Android Kotlin SDK

September 07, 2023 22:07

If you have not completed the initial integration step, refer to How to Integrate the Device Data Collector into Mobile Apps using Android Gradle or How to Integrate the Device Data Collector into Android Applications using the Library JAR depending on your integration type.

This guide is for step two of a Kotlin Android Application implementation of the Kount SDK. This guide provides instructions on how to add the SDK into the application and have it collect information about the device. You must send a sessionID back to your servers in order to use it to make Kount API calls related to this device/transaction.

Implementation Instructions

To enable INTERNET access so the collector can transmit information back to Kount and Location Collection support to detect devices in suspicious locations, add the following permissions to your application’s XML under the <manifest> tag:
```
    <manifest>
        ....
        <uses-permission android:name="android.permission.INTERNET" />
        <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
        <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
        <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
        <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    </manifest>
```
Note: While preferred, not all apps are approved in the app store to use the ACCESS_FINE_LOCATION. If your app has been rejected for having this permission, replace ACCESS_FINE_LOCATION (uses GPS) with ACCESS_COARSE_LOCATION (uses cellular triangulation).
There are two ways to enable Analytics support:

For customers who do not use a custom application class:
Enable Analytics Collection support by adding the following to your application’s AndroidManifest.xml under the <application> tag. Refer to the code example below:
```
      <application
        android:name="com.kount.api.analytics.KountAnalyticsApplication"
        ...>
        ...
      </application>
      
```

For customers who use custom application class:
Enable Analytics Collection support by adding Application.ActivityLifecycleCallbacks to your application class. Refer to the code example below:

Application.ActivityLifecycleCallbacks

          import com.kount.api.analytics.AnalyticsApplication
          import com.kount.api.analytics.enums.EventEnums
          
          class CustomerApplication :Application(),Application.ActivityLifecycleCallbacks {
            override fun onCreate() {
              AnalyticsApplication.init()
              registerActivityLifecycleCallbacks(this)
              super.onCreate()
            }
            
            override fun onActivityCreated(activity: Activity, savedInstanceState: Bundle?) {
            }
            
            override fun onActivityStarted(activity: Activity) { 
              AnalyticsApplication.registerKountEvents(EventEnums.EVENT_STARTED, activity)
            }
            
            override fun onActivityResumed(activity: Activity) {
              AnalyticsApplication.registerKountEvents(EventEnums.EVENT_RESUMED, activity)
            }
            
            override fun onActivityPaused(activity: Activity) {
              AnalyticsApplication.registerKountEvents(EventEnums.EVENT_PAUSED, activity)
            }
            
            override fun onActivityStopped(activity: Activity) {
              AnalyticsApplication.registerKountEvents(EventEnums.EVENT_STOPPED, activity)
            }
            override fun onActivitySaveInstanceState(activity: Activity, outState: Bundle) {
            }
            
            override fun onActivityDestroyed(activity: Activity) {
            }
          }

In the main activity of your application, you will need to initialize the collector and assign the <MERCHANT_ID> you received from Kount. Optionally, you can provide a sessionID if you need to generate your own (if not, the SDK will generate one for you). You must send this sessionID back to your servers in order to make calls to the Kount API (see the Kount API section below). Add the following initialization in your MainActivity:

AnalyticsCollector.collectDeviceDataForSession(this, { sessionID - //success block}, { sessionID, error - //error block})

This starts standard DDC. You can add the functionality for onSuccess and onFailure of DDC in the success and error blocks. For example, you can get DDC Collection Status by calling AnalyticsCollector.getCollectionStatus(). Make sure to call this method after user selecting allow/deny in the location permission dialog because to capture Location data in the first session, we have to give location access before starting collection.

This method is called at three places in the below sample code to fulfill the requirement above.

AnalyticsCollector.collectDeviceDataForSession

        import com.kount.api.analytics.AnalyticsCollector
…
        
class MainActivity : AppCompatActivity(), ActivityCompat.OnRequestPermissionsResultCallback {
    private var deviceSessionID= ""
    private var KEY_UUID= "UUID"
            
    override fun onCreate(savedInstanceState: Bundle?) {
        ...
                    
        AnalyticsCollector.setMerchantId()
                    
        //This turns the alpha collections on(true)/off(false). It defaults to true
        AnalyticsCollector.collectAnalytics(true)
                    
        //For production need to add AnalyticsCollector.ENVIRONMENT_PRODUCTION
        AnalyticsCollector.setEnvironment(AnalyticsCollector.ENVIRONMENT_TEST)
                    
        if (savedInstanceState == null) {
            /** If you want to pass in a self generated sessionID(or one given
              to you by your servers) you can set it here instead of generating a UUID using the code below.
              Make sure you set session ID only one time in a user session by saving it in the savedInstanceState. 
              An example to create a sessionID is below.
            **/
            deviceSessionID = UUID.randomUUID().toString().replace('-','')
            AnalyticsCollector.setSessionId(deviceSessionID)
        } else {
            deviceSessionID = savedInstanceState.getString(KEY_UUID)!!
            AnalyticsCollector.setSessionId(deviceSessionID)
        }
                    
        //Request location permission for Android 6.0 & above
        if (Build.VERSION.SDK_INT = Build.VERSION_CODES.M) {
        Utils.requestLocationPermission(this)// refer step 4
        } else {
          AnalyticsCollector.collectDeviceDataForSession(this, { sessionId -
                Log.d("TAG", "success completed with sessionId $sessionId")
                Log.d("TAG", "DDC STATUS is :" + AnalyticsCollector.getCollectionStatus()?.name)
            }, { sessionId, error -
                Log.d("TAG", " failed with sessionId $error, $sessionId")
                Log.d("TAG", "DDC STATUS is :" + AnalyticsCollector.getCollectionStatus()?.name)
            })
        }
                  
        ...
        }
        // To maintain same sessionId even after screen rotation
        override fun onSaveInstanceState(outState: Bundle) {
        super.onSaveInstanceState(outState)
        outState.putString(KEY_UUID, deviceSessionID)
    }
                    
}

Your MainActivity should implement ActivityCompat.OnRequestPermissionsResultCallback and override method

onRequestPermissionsResult(requestCode, permissions,
    grantResults)

as provided below:

    override fun onRequestPermissionsResult(requestCode: Int, permissions: Array <out String>, grantResults: IntArray) {
  if (requestCode == AnalyticsCollector.REQUEST_PERMISSION_LOCATION) {      
     AnalyticsCollector.collectDeviceDataForSession(this, { sessionId -
       Log.d("TAG", "success completed with sessionId $sessionId")
       Log.d("TAG", "DDC STATUS is :" + AnalyticsCollector.getCollectionStatus()?.name)
     }, { sessionId, error -
       Log.d("TAG", " failed with sessionId $error, $sessionId")
       Log.d("TAG", "DDC STATUS is :" + AnalyticsCollector.getCollectionStatus()?.name)
     })
  }
  super.onRequestPermissionsResult(requestCode, permissions, grantResults)
  }

To support Location Collection in Android API 23 and above, add the following permissions to your main activity, onCreate method:

    if (ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED) {
  if (ActivityCompat.shouldShowRequestPermissionRationale(activity, Manifest.permission.ACCESS_FINE_LOCATION)) {
     ActivityCompat.requestPermissions(activity, arrayOf(Manifest.permission.ACCESS_FINE_LOCATION), AnalyticsCollector.REQUEST_PERMISSION_LOCATION)
  } else {
     ActivityCompat.requestPermissions(activity, arrayOf(Manifest.permission.ACCESS_FINE_LOCATION), AnalyticsCollector.REQUEST_PERMISSION_LOCATION)
  }
} else {
  AnalyticsCollector.collectDeviceDataForSession(this, { sessionId -
     Log.d("TAG", "success completed with sessionId $sessionId")
     Log.d("TAG", "DDC STATUS is :" + AnalyticsCollector.getCollectionStatus()?.name)
  }, { sessionId, error -
     Log.d("TAG", " failed with sessionId $error, $sessionId")
     Log.d("TAG", "DDC STATUS is :" + AnalyticsCollector.getCollectionStatus()?.name)
  })
}

Almost all Kount API calls require your Kount assigned merchantID and a sessionID. You must send the sessionID created earlier back to your servers. This can be done at any time prior to the Kount API calls being made (from your servers to ours). For example, if you are using Kount Control and plan to evaluate logins, you could include the sessionID along with the users login credentials to your servers. This sessionID is accessible as a global variable.
```
   
    …
    val sessionId = AnalyticsCollector.getSessionId()
    // TODO add sessionId in posting to server here
    …
    
```
Build and run.

Note: Compilation Problems? If android:allowbackup attribute is false in your <application> tag, add tools:replace="android:allowBackup" to your application tag.

Optional Additions

Changing your sessionID

If you need to change your sessionID for any reason (like a user logs out and then tries to login as someone else) you can set a new sessionID:

     
    // OPTIONAL SESSION_ID SECTION
    val deviceSessionID = UUID.randomUUID().toString()
    AnalyticsCollector.setSessionId(deviceSessionID)
    // END OPTIONAL SESSION_ID SECTION

Login session tracking

If you are using the Analytics collector and tracking login events, you can pass the value after a login event completes. To track login session data, add the following after the login attempt has completed:

Successful logins: AnalyticsCollector.trackLoginEvent(true)

Unsuccessful logins: AnalyticsCollector.trackLoginEvent(false)

Standard device data collection process

Calling AnalyticsCollector.collectDeviceDataForSession(this, {sessionID -> //success block}, {sessionId, error -> //error block}) starts the Standard DDC collection. Device data collection happens once in a user session. When DDC completes its collection, data will be sent to server.

Android devices from Version 6 onwards has runtime permission feature (Where application user can allow/deny location access permission). In order to make SDK collect location data in the first user session, we have to call the above method once the process of requesting runtime permissions is done. Refer steps four and five for the sample code.

Device data collection status tracking

If you are using the Analytics collector and want to know the status of the Device data collection, you can use the below method. Whenever you call this method, it returns the collection status of DDC collector at that point of time. Use this line of code in those methods which executes After onCreate() method because we are calling the Collector in onCreate() (refer to steps 3, 4, and 5). You can also use this in Activities/Fragments which executes after your main activity.

val status = AnalyticsCollector.getCollectionStatus()
//if status is FAILED call status.getError() to get Error details.
        if (status == DeviceDataCollector.CollectionStatus.FAILED) {
            status.getError()
        }

This method returns one of the below values:

INPROGRESS: When collection is started and collectors are running in the background for device information collection.
FAILED: When Datacollector fails to capture/send the device data. Possible causes for this failure are No network, Invalid Merchant ID, Invalid Session ID, and Runtime failures.
COMPLETED: When DataCollector completes its collection and send data to Server.
NOT_STARTED: When DataCollector SDK is not initialized, calling AnalyticsCollector.collectDeviceDataForThisSession(this, { sessionId -> //success block }, { sessionId, error -> //error block }) will do the initialization, only one time in application session.

Was this article helpful?

0 out of 0 found this helpful