Browser fingerprinting

Using the Castle.js JavaScript to fingerprint browser-based user devices


Fingerprinting is a core component of a Castle integration that enhances Castle’s ability to detect fraudulent and malicious abuse of in-application activity.


  1. Add Castle.js
  2. Forward the fingerprint


Step 1. Add Castle.js

Castle.js is Castle’s proprietary fingerprinting script. It is available to fetch from a global CDN, or it can also be installed via npm in order to bundle it with your application JavaScript.

There are two ways to add Castle.js to pages:

We recommend adding Castle.js as high in the <head> tag of your page HTML as possible, because the script will start fingerprinting for bot behavior as soon as it loads. Using a tag manager is not recommended.

The Castle Castle.js JavaScript snippet should go into as many pages of your site as possible. This includes pages that are presented both before and after the user is authenticated, including the landing page of your website. At a very minimum, you should place it on the page of the login form.

  <!-- Place your Castle App ID after the ? -->
	<script src="{APPID}"></script>


NPM package

If you want to optimize page load speed and avoid a 3rd-party resource request, you can use our NPM Package and bundle Castle.js with the rest of your application JavaScript

Step 2. Forward the fingerprint

Once Castle.js is running on your web pages, you need to ensure that the client_id value generated by Castle.js is passed to your application server where the Castle server-side SDK will be able to extract the client_id value. This value gets assigned to the context.client_id property in requests to Castle.

Custom behavior

Sometimes you may want to recapture a fingerprint after the html page loads - this is often relevant for pages with dynamic content or modal login forms. To send the most up-to-date fingerprint on the page, recapture the client_id and add it as a hidden field in your login form. Make sure your backend team is able to locate this value and set it as the context.client_id in the backend events.

The Castle.js script sets the _castle(...) method on the global window object for the page. You can manually fetch the latest fingerprint by accessing this method: var clientId = _castle('getClientId');

// The following assumes you have a Form with an onsubmit function like:
// <form action="POST" onsubmit="onSubmit(this);">...</form>

function onSubmit(myForm) {
	// The token is continously updated so fetch it right before form submit
	var clientId = _castle('getClientId');

	// Populate a hidden field called `castle_fingerprint`
	var hiddenInput = document.createElement('input');
	hiddenInput.setAttribute('type', 'hidden');
	hiddenInput.setAttribute('name', 'castle_client_id');
	hiddenInput.setAttribute('value', clientId);

	// Add the `castle_client_id` into the form so it gets sent to the server