Install JavaScript tags

Prev Next

With JavaScript tags, your developers add the Darwinium profiling script to your pages and decide when profiling starts and stops. Your backend then sends the result to Darwinium with an Event API call. This suits single-page apps and sites that are not on a supported CDN.

For front-end developers

The Darwinium tag API reference is the full interface: collect(), tryCollect(), stop(), the keyboard contexts and the signals. This page covers the setup around it, and the start() options in Step 4.

Read JavaScript profiling overview first if you haven't chosen between tags and the edge.

How it works

  1. Your page loads the profiling script from a subdomain of your site.
  2. Your code calls start() when the page or form appears.
  3. When the customer submits, your code calls collect(), which returns a profileBlob.
  4. Your frontend sends the profileBlob to your backend with the form data.
  5. Your backend calls the Darwinium Event API with the profileBlob in the dwn-profiling header, and gets a risk decision back.

Your site request carries the profileBlob to your backend, which sends it to a Darwinium API step in the dwn-profiling header and gets the risk response back

Step 1 - Choose a subdomain and validate the certificate

Agree a subdomain of your site to serve the script from, for example aps.yourdomain.com.

The script is served from your own domain so it looks first-party to the browser. This stops ad blockers from blocking it as a third-party script.

If you are not using a CDN deployment, we provide an SSL certificate for the subdomain through AWS Certificate Manager. Validate it in one of these ways:

  1. Recommended: add the CNAME name and value we send you to your DNS. This lets the certificate renew automatically.
  2. Validate by email to the domain owner.
  3. Sign a .csr file we send you.

Then add a CNAME record pointing your subdomain at the CloudFront distribution we provide, for example aps.yourdomain.com → d1example.cloudfront.net.

Step 2 - Add CloudFront as a target in the Darwinium Portal

Add the CloudFront deployment details to your node. See CloudFront deployment. We can do this for you.

Step 3 - Set up the Tag Profiling step

  1. In Workflows > Marketplace, find Darwinium profiling (Tag only - no proxy) and click Install. This adds dwn_profiling_tag.snippet and the profiling script to your node's repository.

    Darwinium profiling (Tag only - no proxy) in the Marketplace

  2. Open your journey, go to Configuration > Add Snippet, click ... and choose dwn_profiling_tag.snippet.

    dwn_profiling_tag.snippet under Import Snippets

  3. Click the arrow next to Add Step and choose Tag Profiling Step.

    Tag Profiling Step in the Add Step menu

Three fields are specific to tags:

Host, Listen URL and Javascript Variable Name on the Tag Profiling Step

Field Default What to enter
Host none The subdomain from Step 1, or a Host Alias. On an existing CDN deployment, use the host from your other steps
Listen URL /dwn_profiling.js The path the script is served on. Starts with /, ends in .js. We recommend your own path, because blockers target the default
Javascript Variable Name dwn The name your code uses to call profiling, for example dwn.start(). We recommend your own name, for the same reason

The other options (biometrics, geolocation, detections, payload size) are shared with edge profiling. See JavaScript profiling snippet options. Two defaults differ on tags: Use Device Geolocation and Enable Device Sensor are on.

  1. Build and deploy the journey.

To check, open https://aps.yourdomain.com/dwn_profiling.js (your host and listen URL). It should return the profiling script.

Step 4 - Add profiling to your frontend

The Darwinium tag API reference has the full interface. The steps below are the minimum to get profiling running.

a. Add the script

Add the script to the page's <head>, using your host and listen URL:

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

b. Start profiling

Start profiling when the page loads, or when the form the customer will fill in appears.

let profilingInstance = dwn.start({
  key_bm: [   // form fields to profile, each with a keyboard context
    { selector: '#first-name', context: 'FIRST_NAME' },
    { selector: '#last-name',  context: 'LAST_NAME' },
    { selector: '#password',   context: 'PASSWORD' }
  ]
});
  • Replace each selector with the CSS selector of an input on your page.
  • Choose each context from Contexts in the tag API reference. Contexts are not case-sensitive.
  • key_bm only works if Enable Keyboard Biometrics on Form Fields is on in the Tag Profiling step.
  • Mouse, touch and sensor biometrics, and Use Device Geolocation, are switched on or off in the Tag Profiling step, not in start().

You can call start() again, for example when a new form appears. Each instance keeps collecting until you stop it.

c. Collect and send the result

On submit, call collect() and send the result to your backend with the form data. A common way is a header on your existing request.

const handleSubmit = (e) => {
  e.preventDefault();
  try {
    profilingInstance.collect()
      .then((profileBlob) => {
        // Send profileBlob to your backend along with the form fields.
      })
      .catch(() => {
        // Profiling failed: send the form without it.
      });
  } catch (err) {
    // The profiling script didn't load: send the form without it.
  }
};

collect() waits for profiling to finish. If you can't wait, tryCollect() returns what has been collected so far:

let profileBlob = profilingInstance.tryCollect();

d. Stop profiling (optional)

You can collect from the same instance as many times as you need. To release it, call stop():

profilingInstance.stop();

Stop profiling before your customer enters sensitive data that Darwinium isn't assessing. For example, if Darwinium covers login and registration but not card payments, stop profiling before the payment form.

Step 5 - Send the event from your backend

For each action you want a decision on, add an API step to your journey with an event type, for example Login and Payment. See Creating and editing steps.

Login and Payment API steps in a journey

From your backend, call your node's Event API and include the profileBlob as the dwn-profiling header. The API helper on each step shows the URL, headers and body to use. See Event API.

Before you go live

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.

Example project

A Next.js project showing tags end to end: Tags Example Project (documentation access required).