Behavioral Data Collector - iOS Project Integration

This page describes how to integrate Vesta’s iOS SDK into your iOS app project. During the integration, you will perform the following actions:

Import the Library - Add Vesta’s libraries to your project.
Initialize the Data Collector - Call the data collector start method to begin tracking your user’s behavior.
Provide Location Data - If you choose to track your user’s location, send Vesta the latitude and longitude from the device.
Implement Field Tagging and Event Tracking - Add tags to the UI elements of your application, and add event methods to buttons and screens so that Vesta can watch them for indications of fraud.

Download the Libraries

If the Enable Bitcode setting in your project’s Build Settings is set to Yes, as shown in the image below, click here to download the required Behavioral Data Collector files for your iOS project.

Otherwise, click here to download the required Behavioral Data Collector files for iOS projects that do not use Bitcode.

Import the Library

Import the library into your project in order the begin using the Vesta methods.

The steps below describe how to add the library files to your project:

Add the library to the project target where you want to use it. Be sure to select the “Copy items if needed” option. The image below shows how to import the library to a project called CustomerJourney:
Confirm that the framework was properly added to your project and select “Embed & Sign” from the options in the Embed column, as shown in the image below:

Now that the SDK in included in your project, you must set it up to initialize when your app launches.

Initialize the Data Collector

Initialize the Data Collector at the beginning of your app flow so that it can report the data that it tracks to Vesta. To initialize the Data Collector, call the DataCollector.default.start() method from within a function that you define. Call your function as soon as your app launches and pass the following parameters to the start() method:

Parameter Name	Description	Type
WebSessionID	The WebSessionID used for vSafe apps. Send a POST request to the `GetSessionTags` endpoint to obtain a WebSessionID.	String
LoginID	The user’s LoginID.	String
SandboxEnabled	Identifies whether you are using the sandbox environment for both vSafe and DataCollector services: * true - Use the sandbox environment. * false - Use the production environment. Your application must be approved by Vesta before moving to production.	Boolean

The code below provides an example of how to initialize the data collector using the DataCollector.default.start() method:

import DataCollector

func initializeDataCollectorService() {
	// Previously obtained webSessionID<String> from the vSafe GetSessionTags API call

	DataCollectorService.default.start(withSessionKey: webSessionID, loginID: "CustomerJourney-LoginID", sandboxEnabled: true) { (success) in
		if success {
            print("DataCollector service initialized successfully")
		}
	}
}

The completion handler will return true if the initialization was successful and false if there were errors.

Provide Location Data

If you choose to track your customer’s location, use the DataCollectorService.default.sendLocationData() method to send the latitude and longitude values from your user’s device to Vesta. Vesta uses the location data to augment our fraud detection and risk analysis. Tracking location data is optional. If you choose not to track location, proceed to the Implement Field Tagging section.

The table below defines the parameters that you must pass to the DataCollectorService.default.sendLocationData() method:

Parameter Name	Description	Type
latitude	The latitude value obtained from your customer’s device.	Double
longitude	The longitude value obtained from your customer’s device.	Double

The code below provides and example of how to call the sendLocationData() method:

import DataCollector

func sendLocationToDataCollectorService() {
	// Previously obtained latitude<Double> from CoreLocation
	// Previously obtained latitude<Double> from CoreLocation

	DataCollectorService.default.sendLocationData(latitude: latitude, longitude: longitude) { (success) in
		if success {
            print("Location sent successfully")
		}
	}
}

Implement Data Collector

Our iOS integration supports different ways to implement tracking depending on the type of UI element:

Text Fields - Use field tagging to track text entry elements by subclassing the TrackingTextfield class from the UITextField class.
Buttons - Use the TrackingButton class to track button tap events in your app.
Active Screens - Use the EventsTrackerViewController class to track the screens that your customer views and when the app moves from the background to the foreground on your user’s device.

Text Fields

Implement field tagging in your application using Interface Builder or directly in your code by setting the fieldTag property of your TrackingTextField objects. Field tagging identifies the text entry fields that Vesta will watch to collect behavioral data. Field tagging is described in detail on the Data Collector Integrations page.

Interface Builder

To use Interface Builder to implement field tagging, follow the steps below for each of the UITextField objects in your application that you intend to track.

Open the Identity Inspector for the UITextField object that you want to tag.
Set the class of the UITextField to TrackingTextField, and set the Module to DataCollector as shown in the image below.
Open the Attributes Inspector for the UITextField object. You will see Identifier and Field Tag properties, which are defined by the the TrackingTextField subclass.

Alert: If you do not see the custom attributes in the Attributes Inspector, follow the steps in the Known Errors section below to define the fields manually.
Set the fieldTag value in the Attributes Inspector, as shown in the image below. The value that you set for fieldTag must correspond to one of the values provided by Vesta in the list of tracked fields.

Known Issues

Occasionally, Interface Builder will not display the custom properties of the TrackingTextField in the Attributes Inspector. Follow the steps below to define them manually:

Define any necessary information in the Connections Inspector first. If you do not define the connections first, setting the class in the Identity Inspector may cause the connections to disappear from the list, and you will not be able to set them. The image below shows the typical properties of the connections inspector:
Open the Identity Inspector, set the class to TrackingTextField, and set the Module to DataCollector.
Click the + button at the bottom of the Identity Inspector to add a User Defined Runtime Attribute.
Add the runtime attributes shown in the image below:

Code

The information in this section describes how to set the fieldTag property on your TrackingTextField classes using code. Using code to implement field tagging is easier and less likely to cause bugs than using the Interface Builder. Follow the steps below for each of your TrackingTextField objects to implement field tagging in your code:

Set the fieldTag property of the TrackingTextField object.
Access the enum values of the TrackingTextField object and cast them to their string rawValue.

The code below shows an example of tagging the username and password fields as LoginID and Password:

import DataCollector 

// You can use any default or convenience initializer
 
let emailTextField = TrackingTextField()
let passwordTextField = TrackingTextField()
         
emailTextField.fieldTag = FieldTags.LoginID.rawValue
passwordTextField.fieldTag = FieldTags.Password.rawValue

Buttons

To track button taps in your app, subclass TrackingButton from the UIButton class in Interface Builder or directly in your code.

Interface Builder

To use Interface Builder to implement field tagging, follow the steps below for each of the UIButton objects in your application that you intend to track.

Open the Identity Inspector for the UIButton object that you want to tag.
Set the class of the UIButton to TrackingButton, and set the Module to DataCollector as shown in the image below.

Alert: If any options disappear from the Connections Inspector after setting the class and module in the Identity Inspector, you must set your connections first. Follow the steps in the Known Issues section below.

Known Issues

Occasionally, options will disappear from the Connection Inspector after setting the class in Interface Builder. If this happens, follow the steps below to define your connections before defining the TrackingButton class:

Define any necessary information in the Connections Inspector. The image below shows the typical properties of the connections inspector:
Open the Identity Inspector, set the class to TrackingTextField, and set the Module to DataCollector as described in the Interface Builder section above.

Code

To implement data collector for buttons using code, you must set the trackingAction property to one of the values defined in the ButtonTrackingAction.swift enum.

The code below shows an example of setting trackingAction property on a login button:

import DataCollector 

class LoginViewController: UIViewController {
    
    @IBOutlet private weak var loginButton: TrackingButton!

    override func viewDidLoad() {
        super.viewDidLoad()

		loginButton.trackingAction = .LoginAttempt

If you are creating buttons using default or convenience initializers, you can assign the trackingAction property as shown in the code below:

let signUpButton = TrackingButton()
signUpButton.trackingAction = .SignUp

Active Screens

Setting up data collector to track the active screen lets Vesta analyze your customers’ behavior as they browse your app or activate it from the background. Follow the steps below to implement screen tracking:

Subclass your UIViewController from the EventsTrackerViewController class.
Override the screenTag property and return a value defined in the ScreenTags.swift enum.

The code below provides an example of how to implement screen tracking:

import DataCollector 

class LoginViewController: EventsTrackerViewController {
    
    @IBOutlet private weak var loginButton: TrackingButton!

	override var screenTag: ScreenTags {
        return .Login
    }

    override func viewDidLoad() {
        super.viewDidLoad()

		loginButton.trackingAction = .LoginAttempt
	}
}

Logs

When working with the Data Collector framework, logs are disabled by default. You can enable logs for each of the objects described in the sections above by setting the showLogs static variable to true. For TrackingTextField objects, you can enable and disable logs on a per object basis. The code below shows how to enable logs using the different approaches:

import DataCollector

// Enables logs for DataCollectorService
DataCollectorService.showLogs = true

// Enables logs for this TrackingTextField
let trackingTextField = TrackingTextField()
trackingTextField.showLogs = true

// Enables logs for ALL TrackingTextField instances (bypasses instance showLogs var)
TrackingTextField.showLogs = true