This article describes the nature and purpose of Darwinium's Javascript profiling.
- Read first: Darwinium Profiling Overview
- If CDN (Edge) Javascript profiling, see Inserting Darwinium JS Profiling
- If Javascript Tag profiling, see Tags Deployment.
Adding JavaScript Profiling to a Page
To use Darwinium Profiling, the JavaScript must be added to the page where Device Profiling is required. For example, a Login Screen before the user logs into their account, a shopping cart before the user clicks the "Complete Purchase" button.
This can be done in one of two ways:
a. CDN insertion into the page (Edge Deployment)
See main article Inserting Darwinium profiling on Edge
Darwinium Edge can inject Profiling into a page automatically as it is being loaded from the CDN.
The instruction to inject Profiling is configured as part of the journey.yaml file in the Darwinium Portal. That is the file that specifies the routes that Darwinium will be invoked on and forms the instructions that create and push the logic to the Edge Workers on your CDN.
A a new Journey Step with a trigger on the host and url of the desired page. Note: make sure the Method is set to GET.
To perform the injection, we must use a HTML/XML Path Body Rule within Data Mappings.
Navigate to the Data Mappings for the Step. Select Response and then Select Body Mappings, as we want the Device Profiling javascript to be injected into the HTTP response body that is delivered back to the web browser.
Set Body Type to "Regular" and set the Body Rule to "With HTML/XML Path". Next click the "+" button to add a new XPath Body Rule.
Set the XPath to either "/html/body" or "/html/head" depending on the desired location of the Device Profiling (Please refer to Location of Darwinium Device Profiling below for more information).
When setting the operation "Inject Darwinium Profiling"
Note: The actual javascript that will be injected is loaded to your Workflow ; under fpjs > dwn_profiling.js.
b. Manually adding to page (Tags)
See Tags Deployment
If not using an Edge deployment, the JavaScript can be hosted and retrieved via a JS Tag, with profiling started and collected manually.
Within the HEAD section of the HTML document:
<html>
<head>
<script type="text/javascript" src="https://myexample.com/dwn_profiling.js"></script>
</head>
<body>
</body>
</html>
OR within the BODY section of the HTML document:
<html>
<head>
</head>
<body>
<script type="text/javascript" src="https://myexample.com/dwn_profiling.js"></script>
</body>
</html>
Once the HTML page has loaded, then Darwinium Profiling can be accessed from within Javascript.
Below is a simple working example intended to illustrate the mechanics required to implement Darwinium Profiling in an easy to understand manner.
The example does not follow best practices and how a real world implementation may look.
<body>
<script type="text/javascript" src="https://myexample.com/dwn_profiling.js"></script>
<script type="text/javascript">
let profilingInstance = null;
const handleSubmit = (e) => {
e.preventDefault();
profilingInstance.collect().then((profileBlob) => {
// Add your logic to submit to your backend server here.
// For example, you can use the fetch API to send the profileBlob to your backend server,
// along with any form field values
// Note: use try/catch to ensure fallback submit if profilingInstance not loaded.
const form = document.createElement('form');
form.name = document.querySelector( "form[id='myform']" );
const hiddenField = document.createElement('input');
hiddenField.type = 'hidden';
hiddenField.name = 'profile-blob';
hiddenField.value = profileBlob;
form.appendChild(hiddenField);
document.body.appendChild(form);
form.submit();
})
}
function start_dwn_profiling() {
profilingInstance = dwn.start({
geo_location_enabled: false, //capture geolocation data, true triggers popup
mouse: true, // capture mouse biometrics
key_bm: //key biometrics: each of these is a selector for an input field
//that you wish to profile, and a Darwinium context of what the field is.
[{selector: 'input[name="custname"]', context: 'FIRST_NAME'},
{selector: 'input[name="custemail"]', context: 'EMAIL'} ] })
// profiling has started
}
document.addEventListener('DOMContentLoaded', function() {
start_dwn_profiling();
document.querySelector("form[id='myform']").onsubmit = handleSubmit;
}, false);
</script>
</body>
Location of Darwinium JS Profiling
HTML documents (commonly called "Web Pages" or simply "Pages") consist of a Head and Body section, either of which can contain Darwinium Profiling.
Head
Placing Profiling inside the Head section of the document means that JavaScript will be loaded along with any other contents of the Head section BEFORE the Body section of the Page is loaded. This means that all of the Profiling will be loaded and active inside the Web Browser before the page or "Website" has loaded.
Pros
The amount of device data collected is maximized, allowing for deeper, more accurate decisions and models.
Cons
The end user will experience a small delay (milliseconds) in the loading of the page, which is typically measured as "Perceived Page Load Latency" and can be subject to variance as internet traffic is constantly fluctuating.
Body
Placing Profiling inside the Body section of the document means that Profiling JavaScript will be loaded in parallel along with the contents of the Body which usually make up the main page. This minimises any page loading latency that may be noticed by the end user as the page is rendered by the browser while the Profiling JavaScript is loaded.
Pros
Minimal interference to user experience of the end user.
Cons
Reduced time to collect device data means the chance of the end-user completing a particular action is increased.
Summary
In places where speed matters most (e.g home page) or browsing a shopping site, Head is not a good choice. However for infrequent user actions such as transitioning from Shopping Cart to Checkout, listing an item for sale in an auction site or marketplace or even updating account details are all infrequent user actions where milliseconds of latency can be tolerated in order to prevent fraud and abuse.
Consideration: Cookies
Darwinium requires two main cookies to operate:
- Session cookie: This cookie is used to influence the
journey_idwithin Darwinium. It should persist only for the length of the user's web session. - Device cookie: This cookie is used to influence the
profiling.device.identifier. It should persist on user's browser across sessions.
Darwinium can either directly generate and manage these as part of profiling, or you can name cookies for session and device that you already use on your site for Darwinium to inspect.
The choice of whether to allow Darwinium to generate these and their properties, or to reference existing ones by name is in the journey.yaml file, under > Configuration > Cookies
- Generate: Important toggle, if True, Darwinium will generate new cookies of this name, with properties defined. If false, will attempt to find and read existing cookie of this name
- Name: Either name of an existing cookie in your application to read, or name of cookie that will be generated
- Scope: Does this cookie refer to session or device tracking
- Max age: (if Darwinium generating) seconds to persist the cookie for. Empty will default to session expiry.
- Same site: (if Darwinium generating) sets the Same Site property of the cookie. Option will vary depending on security and domains Darwinium is profiling against. Defaults to None.
- Domain: (if Darwinium generating) sets to Domain property of the cookie. Value to use will vary depending on security and domains Darwinium is profiling against. Defaults to same as target domain