Behavioral Data Collector - Web Application Integration

The web application integration enhances Vesta’s Device Fingerprinting and Behavioral Analysis tools to improve our risk and fraud assessments. This page describes how to incorporate field tagging and event tracking into your web application to provide additional details to our Behavioral Data Collector service. The example user flows describe how to use field tagging or events to collect data about specific elements of your application.

The Data Collector integration for web applications works on top of our REST API. The integration starts working as soon as a customer lands on your site, when you send a GET request to the GetSessionTags endpoint to obtain a WebSessionID that will identify your customer’s browsing session. See the API Specifications for details about the GetSessionTags operation.

Once you have obtained a session ID, use JavaScript embedded on each page of your site to track your user’s browsing. See the Session Tracking section below for sample JavaScript methods that you must embed on your pages.

Once you have set up your web application to work with our API, you will add field tags and event methods as described in the sections below.

Session Tracking

Session Tracking identifies the pages that your customer visits by using the WebSessionID that you obtained using the GetSessionTags API operation.

To implement Session Tracking, add the appropriate JavaScript from the sections below to the <head> section of each page of your site. The specific script that you need to add depends on your region and development environment: APAC or non-APAC, and sandbox or production.

When you run your application, you must set values for the following query parameters in the URL in the script:

  • AccountName - The Data Collector account name provided to you by your onboarding specialist.
  • WebSessionID - The web session ID that you obtained using the GetSessionTags API operation. The web session ID is generated each time a customer lands on your site and must be passed from page to page in the JavaScript above.

Copy the appropriate script from the sections below. You may want to set the URL in the src element using a variable to facilitate moving your application from the sandbox to the production environment.

APAC

Add the code in the sections below to the <head> section of each page on your site to implement Behavioral Data Collector in sandbox and production environments in APAC regions:

Sandbox

 <!-- Begin Sandbox Data Collector tags below -->
<script src="https://riskcsproxy.apac.vesta.io/DCCSProxy/Service/vdccs.js?AccountName=XXXX&WebSessionID=YYYY" async type=“text/javascript”></script>

Production

 <!-- Begin Production Data Collector tags below -->
<script src="https://collectorsvc.apac.vesta.io/DCCSProxy/Service/vdccs.js?AccountName=XXXX&WebSessionID=YYYY" async type=“text/javascript”></script>

Non-APAC

Add the code in the sections below to the <head> section of each page on your site to implement Behavioral Data Collector in sandbox and production environments in non-APAC regions:

Sandbox

 <!-- Begin Sandbox Data Collector tags below -->
<script src="https://riskcsproxy.ecustomersupport.com/DCCSProxy/Service/vdccs.js?AccountName=XXXX&WebSessionID=YYYY" async type=“text/javascript”></script>

Production

 <!-- Begin Production Data Collector tags below -->
<script src="https://collectorsvc.ecustomersupport.com/DCCSProxy/Service/vdccs.js?AccountName=XXXX&WebSessionID=YYYY" async type=“text/javascript”></script>

Field Tagging

To add field tags to your web app, set the ID attributes of the corresponding HTML elements on your page to the values defined in the Field Tagging section on the Data Collector Integrations page. The code below shows an example of how to incorporate field tags in a typical login form:

<form>
  <label for="username">Username:</label><br>
  <input type="text" id="LoginID" name="username"><br>
  <label for="password">Password:</label><br>
  <input type="text" id="Password" name="password">
</form>

Alternatively, you can set the ID attribute of the HTML element to any value and map your ID values to the field tag values defined by Vesta.

Events

Use the startEvent and finishEvent JavaScript methods to add event tracking to you web app. Vesta tracks events as either logical events or screen tracker events.

Logical Events

Logical events track a single action, like button clicks. Logical events start when you call the startEvent method and end automatically, when the action is complete. For example, if you want to track when a customer adds a product to the shopping cart, call vCustomer.startEvent(vCustomer.ADD_TO_CART); when the customer clicks the add to cart button. The event will end automatically once the product is stored in the cart, and Vesta will receive the details about your customer’s action.

Screen Tracker Events

Screen tracker events watch your customer’s behavior, related to some operation, over a period of time. Use the vCustomer.startEvent and vCustomer.finishEvent JavaScript methods to notify Vesta to track a user during a particular type of interaction.

NOTE: You must call the finishEvent method before starting another event. Vesta cannot track simultaneous events related to a single customer.

For example, to track text entry during login, call vCustomer.startEvent(vCustomer.EVENT_TAGS.LOGIN); when your customer activates the username or password field on your login screen. Then, call vCustomer.finishEvent(vCustomer.EVENT_TAGS.LOGIN); when the customer clicks the login button and the text entry fields lose focus.

Example User Flows

The user flows described below provide examples for how to implement Vesta’s fraud detection services in your web app. Some use cases can be implemented using field tagging or events. Other use cases may require you to use one or the other of the methods.

Customer Login and Logout

The customer login and logout case tracks how your customer interacts with login fields like account name and password. You can use field tagging, logical events, or screen tracker events to implement the login/logout tracking.

Field Tagging

To use field tagging to implement login tracking, set the ID attribute of your username and password text entry elements to "LoginID" and "Password". Vesta will begin tracking the customer’s login attempt as soon as the user name or password fields become active.

The sample HTML below shows an example login form with the field tagging id attributes set on the <input> elements:

<form>
  <label for="username">Username:</label><br>
  <input type="text" id="LoginID" name="username"><br>
  <label for="password">Password:</label><br>
  <input type="text" id="Password" name="password">
</form>

Logical Event

Call the vCustomer.startEvent(vCustomer.EVENT_TAGS.LOGIN_ATTEMPT); method when the customer activates the login ID or password field. Vesta will identify the end of the event when your app determines whether the login attempt was successful or unsuccessful.

Screen Tracker Event

Call the vCustomer.startEvent(vCustomer.EVENT_TAGS.LOGIN); method when the customer activates the login ID or password field. Then, call the vCustomer.finishEvent(vCustomer.EVENT_TAGS.LOGIN); method after your system processes the login request.

Forgot Password

The forgot password flow tracks your user’s behavior when resetting a password. You must implement the forgot password use case as a screen tracker event.

Call the vCustomer.startEvent(vCustomer.EVENT_TAGS.FORGOT_PASSWORD); method when the customer clicks the forgot password link in your application. Then, call the vCustomer.finishEvent(vCustomer.EVENT_TAGS.FORGOT_PASSWORD); after your application processes the password reset request.

Browsing, Shopping Cart, and Checkout

These cases track behavior as your customers view and select products to purchase.

Use a combination of logical events and field tracking to track customers behavior as they view product lists and details, add and remove products from their shopping carts, and decide to check out.

Vesta can track behavior related to browsing product lists and product details:

  • Product Lists - Start tracking behavior when your customer lands on one of your product list pages: vCustomer.startEvent(vCustomer.EVENT_TAGS.PRODUCTS_LIST);
  • Product Details - Start tracking behavior when your customer views a product details page: vCustomer.startEvent(vCustomer.EVENT_TAGS.PRODUCTS_DETAIL);

Be sure to call the corresponding finishEvent method when the customer leaves the page, and before starting another logical event.

While the customer browses, use field tagging or logical events to identify more granular behaviors that Vesta can analyze.

Field Tagging

Use field tagging to identify the following components of your application so that Vesta can analyze interactions with your search functions and shopping cart:

  • ProductSearch - The UI elements that customers use to search for products on your site.
  • AddToCart - The UI elements that customers use to add items to their shopping carts.
  • RemoveFromCart - The UI elements that customers use to remove items from their shopping carts.

See the list of field tags accepted by Vesta to identify the appropriate element ID values to set.

Logical Events

The same actions can be tracked using logical events. Call the following methods to identify events related to search and shopping cart interactions:

  • Search - Identifies when your customer searches for a product: vCustomer.startEvent(vCustomer.EVENT_TAGS.SEARCH);
  • Add to cart - Identifies when your customer adds an item to the shopping cart: vCustomer.startEvent(vCustomer.EVENT_TAGS.ADD_TO_CART);
  • Remove from cart - Identifies when your customer removes an item from the shopping cart: vCustomer.startEvent(vCustomer.EVENT_TAGS.REMOVE_FROM_CART);
  • Checkout - Identifies when your customer proceeds to the checkout screen: vCustomer.startEvent(vCustomer.EVENT_TAGS.PROCEED_TO_CHECKOUT);

Be sure to call the corresponding finishEvent method when your customer finishes the action.

Billing Details

During checkout, Vesta uses field tagging and logical events to track behavior as your customer enters billing details.

Field Tagging

Vesta supports field tagging for the following components of your application related to billing:

  • BillingFirstName - The first name on the payment card.
  • BillingLastName - The last name on the payment card.
  • BillingAddressLine1 - The first line of the billing address.
  • BillingAddressLine2 - The second line of the billing address.
  • BillingCity - The city portion of the billing address.
  • BillingRegion - The region portion of the billing address.
  • BillingPostalCode - The postal code portion of the billing address.
  • BillingCountryCode - The country code portion of the billing address.
  • PurchaseCardNumber - The card number.
  • PurchaseCardExpirationDateFull - The month and year of the card’s expiration date.
  • PurchaseCardExpirationDateMonth - The month portion of the card’s expiration date.
  • PurchaseCardExpirationDateYear - The year portion of the card’s expiration date.
  • PurchaseCardCVV - The card’s security code.

Logical Events

Call the following methods to tell Vesta when your customer begins the checkout process, enters payment details, and finalizes the order:

  • Checkout - Call this method when your customer lands on the checkout page: vCustomer.startEvent(vCustomer.EVENT_TAGS.CHECKOUT);
  • Payment Details - Call this method when your customer begins entering payment details: vCustomer.startEvent(vCustomer.EVENT_TAGS.PAYMENT_DETAILS);
  • Complete Order - Call this method when your customer clicks a button to complete the order: vCustomer.startEvent(vCustomer.EVENT_TAGS.COMPLETE_ORDER);

Be sure to call the corresponding finishEvent method when the event ends, and before starting another event.

Settings

Call the settings method to notify Vesta that your customer has entered the settings screen to make changes to account details:

  • Settings - vCustomer.startEvent(vCustomer.EVENT_TAGS.SETTINGS);

Be sure to call the corresponding finishEvent method when the customer leaves the settings page, and before starting another event.