New

If you signed up before June 3, 2021, see the migration guide to learn about the recent API changes.

Web client-side integration

Using Castle.js to collect data from and fingerprint web browsers

Summary

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


Steps

  1. Add Castle.js
  2. Forward the request token


Tutorial

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.

<script src="https://d2t77mnxyo7adj.cloudfront.net/v1/c.js?{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 request token

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

Custom behavior

Sometimes you may want to recapture a request token 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 request token on the page, recapture the request_token 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 request_token in the backend events.

The Castle.js script sets the _castle(...) method on the global window object for the page. You can fetch request token by using this method: _castle('createRequestToken'); as in the example below:

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

function onSubmit(evt) {
  evt.preventDefault();
  // The token is continuously updated so fetch it right before form submit
  _castle('createRequestToken').then(function(requestToken) {
    var form = evt.target;
    // Populate a hidden field called `castle_request_token`
    var hiddenInput = document.createElement('input');
    hiddenInput.setAttribute('type', 'hidden');
    hiddenInput.setAttribute('name', 'castle_request_token');
    hiddenInput.setAttribute('value', requestToken);
    // Add the `castle_request_token` into the form so it gets sent to the server
    form.appendChild(hiddenInput);
    form.submit();
 });
};