Insert JavaScript profiling at the edge

Prev Next

On a CDN deployment, our edge worker can add Darwinium profiling to your pages as they load. You set it up in the Darwinium Portal, so no change to your site's code is needed. This lets you add profiling to a new page with a journey change rather than a release.

Before you start:

How it works

  1. A customer loads a page, for example GET /login.
  2. The edge worker adds the profiling script to the page.
  3. Profiling runs while the customer fills in the form.
  4. On submit, for example POST /login, profiling adds its result to the request as the dwn-profiling header (or a hidden form field).
  5. The edge worker on the submit request reads the result, removes it so it never reaches your servers, and creates the Darwinium event.
  6. Optionally, the worker waits for results such as the journey ID or risk score and passes them to your servers in a header. This lets your backend act on the decision, at the cost of the time the worker waits.

Edge profiling flow, from page load to submit

You need two journey steps: one on the page load (to add the script) and one on the submit request (to create the event). The submit step must have an event type set, otherwise no event is created.

Step 1 - Install the profiling snippet

  1. In the Darwinium Portal, open Workflows and the Marketplace tab.
  2. Find Darwinium Profiling and click Install.

Marketplace tab in Workflows

Darwinium Profiling with the Install button

This adds two files to your node's repository: dwn_profiling.snippet (the options shown in the Portal) and fpjs/dwn_profiling.js (the profiling script).

Step 2 - Add the snippet to your journey

  1. Open your .journey.yaml file and go to Configuration > Snippets > Add snippet.
  2. Click ... and choose dwn_profiling.snippet.
  3. Close and reopen the journey so the new options appear.

Step 3 - Add profiling to the page

  1. Open the step for the page load. It should match a GET request, for example /login.
  2. Go to Data Mappings > Response > Body Mappings.
  3. Set Body Type to Regular, Body Rule to With HTML/XML path and Mode to html.
  4. Click + to add a row. Set XPath to /html/head (recommended) or /html/body. See where the script runs and Map, inject & extract data for XPath.
  5. Set Operation to Inject darwinium profiling. If it isn't in the list, check Step 2.

Body Mappings with an XPath row

Inject darwinium profiling in the Operation list

We recommend adding profiling to every page in the journey, not only the one before submit. This lets you spot changes in device or behaviour as the customer moves through the journey.

Inject darwinium profiling options

Step 4 - Choose which request gets the dwn-profiling header

These three options decide which of your page's requests profiling adds the dwn-profiling header to, or the hidden dwn-profiling field for form posts.

This is normally the submit request, for example POST /login. Get them right first, because the rest work well at their defaults.

Application HTTP Requests

How your page sends the submit request that should get the dwn-profiling header. To check, open your browser's Network tab, submit the form, and look at the Type column for the submit request.

  • fetch (default): choose this when Type shows fetch. Profiling hooks into window.fetch and adds the dwn-profiling header to those requests.
  • XMLHttpRequest(xhr): choose this when Type shows xhr. Profiling hooks into window.XMLHttpRequest, also known as Ajax, and adds the header to those requests.
  • both: choose this when your submit requests show a mix of fetch and xhr. Profiling adds the header to either kind.
  • none: choose this when Type shows document, which means a regular HTML form post that loads a new page. Profiling adds a hidden dwn-profiling field to the form instead of a header.
Form posts that show the form again

With a form post, the response is a new page. If it can show the form again, for example after a failed login, add Inject darwinium profiling to the POST step's response as well as the GET step. Otherwise the retry is sent without profiling.

Fetch/xhr URL Restricted to

  • /example1,/example2: the paths of the requests that the dwn-profiling header is added to (the decisioning steps), such as login and registration. This is the recommended setting.
  • any (not recommended): every fetch or xhr request the page sends gets the header, including requests to other domains. Some servers reject headers they don't expect, so only use it if every request can accept it.
  • none: use with form posts, where this setting doesn't apply.

Note: Each path is matched against the whole request path, one / segment at a time:

  • /api/login matches /api/login only, not /api/login/otp. Query parameters are ignored.
  • * as a whole segment matches one or more segments. /*/auth/login matches /en/auth/login and /en/gb/auth/login. /api/* matches anything under /api/.
  • * at the end of the last segment matches the start of it and anything below it. /api/login* matches /api/login, /api/login-v2 and /api/login/otp.
  • * anywhere else isn't supported, and that path never matches.
  • A path on its own matches on every host the page sends requests to, including other domains. To limit it to one host, include the host: api.example.com/login.

Form Post CSS Selector

  • A selector for the form, for example form#login: use with form posts.
  • The value form matches every form on the page that sends a POST.
  • none: use with fetch or xhr.

Step 5 - Review the other options

The remaining options control which data is collected and which detections run. The defaults suit most sites. See JavaScript profiling snippet options for each one.

Step 6 - Map keyboard fields (recommended)

Keyboard biometrics compare how a customer types into a field with normal behaviour for that kind of field. Pasting a national ID number is common, for example, while pasting a first name is unusual. So each field needs a context, such as EMAIL or PASSWORD.

  1. In the same Body Mappings, click + to add a row. Set XPath to /html/head.
  2. Set Operation to Enable Keyboard Biometrics On Input Field.
  3. In CSS Input Selector of the Input Field, enter a selector that matches only this field, for example input#email.
  4. In Context of the Input Field, choose the closest match. See Keyboard input contexts.
  5. Repeat for each field the customer types into.

Enable Keyboard Biometrics On Input Field in the Operation list

To find a selector, right-click the field and choose Inspect. To test it, run document.querySelectorAll("input#email").length in the browser console. It should return 1.

Give each field its own context. If two fields share a context, the later mapping replaces the earlier one and only that field is profiled.

Step 7 - Deploy and check

Check the site requirements

Your site's Content Security Policy, CORS, Permissions-Policy and header size limits can stop profiling working, often without an obvious error. Check Site requirements for JavaScript profiling during setup and after changing them. The page is private: sign in through the Portal (see Help & documentation access) or ask your Darwinium contact.

Commit, build and deploy the journey. See Deployment confirmation.

Test on a staging environment first. Profiling is passive, but confirm your site still behaves normally with the script and header added.

To check profiling is working:

  1. Load the page and view its source. The Darwinium script should appear where you set the XPath. With form posts, the script adds a hidden dwn-profiling field after the page loads, so look for it in your browser's developer tools (Elements), not the page source.

Darwinium profiling script in the page head

  1. Submit the form with your browser's Network tab open. The submit request should carry a dwn-profiling header (or form field).

dwn-profiling header on the submit request

  1. In the Darwinium Portal, search for events from that page with:
profiling.source = "browser"

Those events had the valid dwn-profiling header