--- title: "Install JavaScript tags" slug: "tags-deployment" updated: 2026-11-11T04:01:59Z published: 2026-11-11T04:01:59Z canonical: "docs.darwinium.com/tags-deployment" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.darwinium.com/llms.txt > Use this file to discover all available pages before exploring further. # Install JavaScript tags 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](https://dahibthxi6hbt.cloudfront.net/dwn-api-docs/javascript/docs/dwn.html) 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](/v1/docs/javascript-profiling) 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](/v1/docs/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](https://cdn.document360.io/db6f7316-640d-4099-b5a1-b01b4dbd17fc/Images/Documentation/image(141).png?sv=2026-02-06&spr=https&st=2026-11-19T12%3A45%3A22Z&se=2026-11-19T13%3A45%3A22Z&sr=b&sp=r&sig=tXg6OfuUQ7lNVz6EFCnhZt5VaCUAsiSUm7B0yGAQiOk%3D) ## 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](/v1/docs/cloudfront-deployment#step-8-add-the-ids-into-the-darwinium-portal). 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](https://cdn.document360.io/db6f7316-640d-4099-b5a1-b01b4dbd17fc/Images/Documentation/Screenshot%202023-06-16%20at%203.15.53%20PM.png?sv=2026-02-06&spr=https&st=2026-11-19T12%3A45%3A22Z&se=2026-11-19T13%3A45%3A22Z&sr=b&sp=r&sig=05z%2B5FhiujQXughbSZtZ6fY7Rv98Qmn1WcMmG5VtzSw%3D) 2. Open your journey, go to **Configuration** > **Add Snippet**, click **...** and choose `dwn_profiling_tag.snippet`. ![dwn_profiling_tag.snippet under Import Snippets](https://cdn.document360.io/db6f7316-640d-4099-b5a1-b01b4dbd17fc/Images/Documentation/Screenshot%202023-06-16%20at%203.28.50%20PM.png?sv=2026-02-06&spr=https&st=2026-11-19T12%3A45%3A22Z&se=2026-11-19T13%3A45%3A22Z&sr=b&sp=r&sig=OYMpUk1HFR9Tu4jKtoSMDydG5rrTqkU%2FGqy9lvyDwhs%3D) 3. Click the arrow next to **Add Step** and choose **Tag Profiling Step**. ![Tag Profiling Step in the Add Step menu](https://cdn.document360.io/db6f7316-640d-4099-b5a1-b01b4dbd17fc/Images/Documentation/Screenshot%202023-06-16%20at%203.30.21%20PM.png?sv=2026-02-06&spr=https&st=2026-11-19T12%3A45%3A22Z&se=2026-11-19T13%3A45%3A22Z&sr=b&sp=r&sig=TVVDfgXcQrIFybeQ%2BR9WEPhtQkoZbL%2BYa8VDhZLKRXw%3D) Three fields are specific to tags: ![Host, Listen URL and Javascript Variable Name on the Tag Profiling Step](https://cdn.document360.io/db6f7316-640d-4099-b5a1-b01b4dbd17fc/Images/Documentation/tag_profiling_step_fields.png?sv=2026-02-06&spr=https&st=2026-11-19T12%3A45%3A22Z&se=2026-11-19T13%3A45%3A22Z&sr=b&sp=r&sig=1u2sWTHUKPiuAGx%2Fs6mMN40GXZtSij%2F%2BsPB2zfcAGVQ%3D) | Field | Default | What to enter | | --- | --- | --- | | **Host** | none | The subdomain from Step 1, or a [Host Alias](/v1/docs/hosts-targets-git-repo). 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](/v1/docs/javascript-profiling-snippet-options). Two defaults differ on tags: **Use Device Geolocation** and **Enable Device Sensor** are on. 1. [Build and deploy](/v1/docs/deployment-confirmation) 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](https://dahibthxi6hbt.cloudfront.net/dwn-api-docs/javascript/docs/dwn.html) 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: ``` ``` ### 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](https://dahibthxi6hbt.cloudfront.net/dwn-api-docs/javascript/docs/global.html#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()`](https://dahibthxi6hbt.cloudfront.net/dwn-api-docs/javascript/docs/dwn.html#.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()`](https://dahibthxi6hbt.cloudfront.net/dwn-api-docs/javascript/docs/dwn.html#.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()`](https://dahibthxi6hbt.cloudfront.net/dwn-api-docs/javascript/docs/dwn.html#.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](/v1/docs/creating-and-editing-steps). ![Login and Payment API steps in a journey](https://cdn.document360.io/db6f7316-640d-4099-b5a1-b01b4dbd17fc/Images/Documentation/image(142).png?sv=2026-02-06&spr=https&st=2026-11-19T12%3A45%3A22Z&se=2026-11-19T13%3A45%3A22Z&sr=b&sp=r&sig=fopzct%2F6tqjaYC8fT8y%2BkFdKloPzp3NjbSqQxWMq040%3D) 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](/v1/docs/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](/v1/docs/javascript-profiling-site-policies) during setup and after changing them. The page is private: sign in through the Portal (see [Help & documentation access](/v1/docs/access-gated-docs-links)) or ask your Darwinium contact. ## Example project A Next.js project showing tags end to end: [Tags Example Project](/v1/docs/tags-example-project) (documentation access required).