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

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

  1. There are two ways to enable Analytics support:
    1. 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>
            
    2. 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) {
                  }
                }
                
  2. 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:

    Calling AnalyticsCollector.collectDeviceDataForSession will start Standard DDC collection. 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(<MERCHANT_ID>)
                        
                        //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 using colde like this.
                            Otherwise the AnalyticsCollector will generate one for you. Make sure
                            you set session ID only one time in a user session. To do so set
                            your sessionID 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)
                        }
                        
                        ...
                        }
                        // To maintain same sessionId even after screen rotation
                        override fun onSaveInstanceState(outState: Bundle) {
                        super.onSaveInstanceState(outState)
                        outState.putString(KEY_UUID, deviceSessionID)
                    }
                        
            }
            
  3. 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)
            }
        super.onRequestPermissionsResult(requestCode, permissions, grantResults)
        }
        
  4. 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(activity)
        }
        
  5. 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
        …
        
  6. 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) 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:

  1. INPROGRESS: When collection is started and collectors are running in the background for device information collection.
  2. 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.
  3. COMPLETED: When DataCollector completes its collection and send data to Server.
  4. NOT_STARTED: When DataCollector SDK is not initialized, calling AnalyticsCollector.collectDeviceDataForThisSession(this) will do the initialization, only one time in application session.
Was this article helpful?
0 out of 0 found this helpful