Tags Deployment

Introduction

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.

Here, a Darwinium profiling instance is added directly to the page(s) where profiling is wanted and a follow up API call to Darwinium is 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.

Comparison to Edge

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

• 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)

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.

Step 1 - Setup the Profiling Tags Step

The first step involves installing the profiling tags snippet and adding it to your journey.

1. In the Darwinium Marketplace tab of the Workflows Editor, locate "Darwinium profiling (Tag only - no proxy)" and click install:

2. This will install several files in your node's repo. The key file used is dwn_profiling_tag.snippet
3. Activate the snippet in your journey by opening the journey, navigating to Configuration and clicking Add Snippet. Click ... and locate dwn_profiling_tag.snippet

4. 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.yourcompany.com for this to be hosted. You will need to provide an SSL certificate to Darwinium that aligns with this domain name. 

Step 2 - Create API Step(s)

For each unique event that you wish to profile/add custom decisioning on, you should create API steps. For example, if you are looking to profile Logins and Payments, add API steps called Login and Payment respectively. Assign appropriate event types for each of these and whatever rules and additional decisioning logic you see fit.

Step 3 - Implement Tags on your Application Frontend

1. 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:

<script type="text/javascript" src="https://aps.your-domain.com/dwn_profiling.js"></script>

replace "://aps.your-domain.com/dwn_profiling.js" with the Host and Listen URL values you specified in the Tag step settings

2. Create a new Profiling Instance

The next step is to tell 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'}
  ]
})

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.

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

4. (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();

Reference: Profiling Functions

dwn.start

Returns: A Darwinium profiling instance

Description: Call to initiate a Darwinium profiling session. It typically obtains the neccesary data within 3 seconds and can be left running to collect behvaioural biometrics information continuously.

Inputs:

dwn.stop

Returns: None

Optional function which stops Darwinium profiling. 

Note, this is optional as it is called automatically when collect is, but offers finer grained control over performance of the application to stop profiling earlier.

dwn_handle.collect().then(( blob )

Designed as a JS promise which ensures profiling is complete.

Instructs the Darwinium handle to gather profiling, and execute the logic within the subsequent code block to run when finished, The profiling blob (all profiling data) is available as a local parameter.

The blob should be passed to your backend within this function and included as the value for dwn_profiling parameter on the subsequent API call to Darwinium.

Step 4 - Call your API step from your application backend

(See dedicated article for full overview of Calling the Darwinium API).

On your backend, make a call to your node's Darwinium API step, making sure to add the profilingBlob on a header called: dwn-profiling.

The formatting the API can be streamlined by clicking:

on your API step. 

• You may leave the body as an empty object ({}) if you do not wish to provide any additional information for decisioning

• your profiling blob should be included as a request 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/<journey name>/<step name>"

//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.<yourcompany>.com
aps.wowscale.com
ats.wowscale.com
*.dxf.wowscale.com

Example Project

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