Tags Deployment

In a Darwinium Tags deployment, a profiling instance is added directly to the page(s) and follow up API calls to Darwinium are performed to make decisions and receive data back.
The profiling tags approach may be used in conjunction with Edge deployments, or as a standalone solution.

Profiling

1. Darwinium JS tags are added on a specific page

2. profiling start function invoked on page load. This performs fingerprinting of the user device, connection, behavioural biometrics and more.

3. profiling continues to run until user performs an action (like hitting submit), profiling collect function is called

4. The collect function produces a profileBlob, which should be passed to your back-end, ready to include in the Darwinium Event API step

API call (event capture)

1. To execute a risk assessment, the Darwinium Event API is then called from your back-end.

2. The profileBlob is included in header named dwn-profiling on the API call.

3. Full data is returned in the API response body in JSON format, including risk scores and signals

4. The event forms a row of data in the Darwinium Portal

Step 1 - Setup the Profiling URL

The first step involves ensuring Darwinium JS profiling tags are delivered on a subdomain URL of your site.
It is done from within your Darwinium Portal

1. In the Darwinium Marketplace tab of the Workflows Editor, locate "Darwinium profiling (Tag only - no proxy)" and click install. This will install several files in your node's repo. The key file used is dwn_profiling_tag.snippet

2. Activate the snippet in your journey by opening the journey, navigating to Configuration and clicking Add Snippet. Click ... and locate dwn_profiling_tag.snippet

3. Add a Tag Profiling Step to your journey, using the left-hand sidebar:

The Tag Profiling step has several customizations that enable flexible deployment and allow you to choose which features are included. Reducing the number of features included can help to reduce the size of the file delivered to your end-user and optimize performance. A complete deployment with all features enabled has a footprint of approximately 90kb.

At minimum you should provide a value for Host - if you are using this feature as part of your existing edge deployment, this will align with the hostname used in your other steps. SSL will be automatically configured based on your existing CDN vendor settings.

If you have nominated a non-edge deployment, Darwinium will coordinate a subdomain: eg. aps.yourhost.com for this to be hosted.
You will need to provide an SSL certificate to Darwinium that aligns with the domain name.

5. Build and Deploy the journey from within Darwinium to make the profiling step live

You can test the profiling tags are working by going to https://aps.yourhost.com/yourlistenurl.js
If deployed, it should be delivering the Darwinium profiling javascript.

Step 2 - Create API Step(s)

For each unique event that you wish to add custom decisioning on, you should create and deploy API steps in your journey. Assign appropriate event types for each of these and whatever rules and additional decisioning logic you see fit.

For example, if you are looking to profile Logins and Payments, add API steps called Login and Payment respectively.
See Creating and Editing Journeys,  Creating and Editing Steps

Step 3 - Implement Tags on your Application Frontend

Darwinium tag only API interface

a. Add the script to your page

Your application will need to import the tags from your Profiling Tags Step. The most straightforward means of doing this is to add it as a script tag to your application's head.

Be sure to replace "https://aps.yourhost.com/yourlistenurl.js" with your Host and your Listen URL values you specified in the Step 1.

<script type="text/javascript" src="https://aps.yourhost.com/yourlistenurl.js"></script>

b. Create a new Profiling Instance

Next, instruct Darwinium to start profiling. Typically you should do this when your page loads (in the case of a simple page), or when a point of interest (such as a form appearing) is presented to the end user.

// On page load
let 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: '#grid-first-name', context: 'FIRST_NAME'},
    {selector: '#grid-last-name', context: 'LAST_NAME'},
    {selector: '#grid-password', context: 'PASSWORD'},
    {selector: '#grid-city', context: 'ADDRESS_STREET3'}
  ]
})

• The selector string values (eg. in example #grid-first-name) should be replaced with CSS selectors of inputs on your site page

• The context values (eg. in example FIRST_NAME) should be replaced by sensible choices from the fixed keyboard context list

• The characters in context value are case insensitive, e.g. first_name, First_Name, FIRST_NAME are all accepted

You can create as many profiling instances as you'd like. They will continue to collect Biometric data until told to stop.  It is often preferable to start/stop instances as actions occur on your front end experience.

c. Collect profiling data and pass it to your application backend

You will want to provide the intelligence gathered by profiling when an action such as a form submit occurs onto your backend, where it can be passed to Darwinium's API steps for further decisioning. In the following example we will intercept a submit button call and send that to our backend.

As a best practice, Darwinium profiling should always been stopped during the collection of sensitive data that is not being used in conjunction with Darwinium decisioning. For example, if Darwinium is implemented for Register and Login but not card payments, then profiling should be stopped

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.
  });
}

d. tryCollect() same as collect() but it will response profiling data straight away

tryCollect() will response whatever collected profiling data and response it immediately, it wouldn’t wait for all profiling finished.

let profilingBlob = profilingInstance.tryCollect()
// 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

e. (Optionally) Stop Profiling

You can collect profiling data from the same instance as many times as needed. If you no-longer wish to use it, you can release the instance using:

profilingInstance.stop();

Step 4 - Call the Darwnium API step from your application backend

See Calling the Darwinium API

On your backend, make a call to your node's Darwinium API step.

The details and formatting of API url, headers and body can be obtained using the API helper on your step.

• the profiling blob from step 3 should be included as a header named dwn-profiling

Below is a NodeJS example of an API call to a mock call to a node API:

//Darwinium's API uses Mutual TLS for authentication. You can generate a new certificate and key pair
//in the darwinium portal
const httpsAgent = new https.Agent({
  cert: CERT, 
  key: KEY,
  ca: CA,
  passphrase: DWN_API_PASSPHRASE,
  rejectUnauthorized: false
})

const DWN_API_URL = "https://<my-node>.node.darwinidentity.com:9443/api/event/<journeyname>/<stepname>"

//get your profiling blob (and any other data) from the request made byt your frontend
//this will vary from implementation-to-implementation
const {firstName, lastName, city, state, zip, profilingBlob, password} = request.body;

//Add any additional data (such as names, addresses, phone numbers, logins) that 
//you wish to be included in Darwinium's decisioning process
//Note: the journey editor provides an API helper that can help you to construct 
// this object. Click "Help me to construct an API call to this step" in the 
// summary tab of your api step
let data = JSON.stringify({
  "identity": {
    "ACCOUNT": {
      "name": {
        "first": firstName,
        "last": lastName
      },
      "address": {
        "HOME": {
          "state": state,
          "city": city,
          "zip_post_code": zip
        }
      }
    }
  }
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: DWN_API_URL,
  headers: { 
    'Accept': 'application/json', 
    'dwn-profiling': profilingBlob, 
    'Content-Type': 'application/json'
  },
  data : data,
  httpsAgent: httpsAgent
};

let response = await axios.request(config)
//do something with your Darwinium API response
console.log(response.data)

Content Security Policy Considerations

Although Darwinium serves all Javascript from your domain, it also utilizes calls to other domains in order to maximize device intelligence gathering.

If you are using the

connect-src

directive in your Content Security Policy, we encourage you to add the following domains to this list in order to maximize threat detection and prevent error messages from appearing in your users' browsers:

aps.<yourhost>.com
aps.wowscale.com
ats.wowscale.com
*.dxf.wowscale.com

Benefits of Darwinium Tags

1. No missing data: The profiling using JS promises to ensure control and knowledge over when profiling has completed. Means there is no concept of missing or dropped profiling data.

2. First party: Darwinium profiling does not require a fetch or running of third party script. Profiling is done directly from your domain making it more secure.

3. Blocker protection: Tags are run directly rather than from a URL, meaning they are resistant to blockers that block on URL format.

3. Application Performance: There is control over the start and stopping times for profiling, allowing finer grained control over how long, where and when profiling should be performed

4. Simpler Profiling: The profiling is performed without the need for a profiling session identifier.

5. Traceability: Gives visibility and control over the error catching process for logging and traceability.

Comparison to Edge

The Tags approach has the following main differences compared to Edge approach:

In scenarios where the Edge is not viable for deployment (CDN limitations or technical limitiations) Darwinium can still operate through a JS tags approach. Decisions on these events are performed in the same way and the data stored in the same places as an Edge deployment.

• Manually implemented profiling tags have tighter control over timing and control. This makes them useful, even in edge-only implementations, for usecases such as single-page applications.

• Profiling a new interaction point in journey requires adding the tags and API call to relevant page(s)

• Tracking and decisioning on interactions  requires an API call rather than operating on existing requests. By extension, Darwinium cannot perform the header enrichment of existing requests

• Darwinium cannot perform journey interventions (redirects, session terminates)

Example Project

An example project (implemented in next.js) that demonstrates the use of tags-based profiling end-to-end can be downloaded below: