Browser

This page describes how to install and use Castle.js client-side fingerprinting

Castle.js is Castle's proprietary fingerprinting agent, and comes available to install either as a module via NPM or as a browser version for environments that doesn't support modules. For quick non-production experiments, Castle also provides a global CDN URL which hosts a browser version of Castle.js that can be included directly in the HTML head tag.

Installing Castle.js

NPM

The recommended way of installing the Castle client-side agent is to include it in your app bundle with our NPM Package. This ensures optimal page load speed and avoids 3rd-party resource requests.

Install using NPM:

npm install --save @castleio/castle-js

or with Yarn:

yarn add @castleio/castle-js

Initialization and Configuration

Once installed, the SDK needs to be configured using your Castle App ID, which can be found in the Dashboard for users with administrator access.

import * as Castle from '@castleio/castle-js'

Castle.configure(YOUR_CASTLE_APP_ID);

If you have an environment that doesn't support modules, you can use the browser version.

import '@castleio/castle-js/dist/castle.browser.js'
_castle('setAppId', YOUR_CASTLE_APP_ID);

:warning: Note: we recommend initializing the agent as early as possible when your app loads. The more time that passes from initialization to when you create a request token (next section), the more data the agent can collect, which in turn improves accuracy.

Example of an app environment and where to initialize the Castle agent:

import * as Castle from '@castleio/castle-js'

// Main app instance that runs at start
class Application {
  constructor() {
    // Initialize the Castle agent as early as possible
    Castle.configure(YOUR_CASTLE_APP_ID);

    // Rest of initialization code
  }
}

CDN

For quick non-production testing, you can use the Castle CDN to include Castle.js in the head tag directly in the browser.

<script src="//cdn.castle.io/v2/castle.js?{APPID}"></script>

:warning: Note: The browser and CDN versions of the Castle.js script sets the _castle(...) method on the global window object for the page.

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.

📘

Please note that if you plan on using Castle's server side Filter or Risk APIs, a valid request token value is required

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. Alternatively, if you're sending requests asynchronously using e.g. fetch with a JSON payload, you can simply include the request token as an additional parameter. Make sure your backend team is able to locate this value and set it as the request_token in the backend events sent to Castle.

You can automatically populate include the proper hidden field named castle_request_token by using castle form submit handler as in the example below

import * as Castle from '@castleio/castle-js'
// Get the request token when you needs it, eg. before login or other user actions
Castle.createRequestToken().then( (requestToken) => {
  ....
});

// or
const requestToken = await Castle.createRequestToken();
<!-- Use the form helper to automatically insert the request token on form submit //-->
<form onsubmit="_castle('onFormSubmit', event)">
  // ....
</form>

<script>
// Alternate ways of retrieving the request token using the browser version of Castle.js  
_castle('createRequestToken').then(function(token) {
  var requestToken = token
});

// or with modern version of the javascript
const requestToken = await _castle('createRequestToken');
</script>

For example, using the dummy app example from step 1, this is how a request token should be created before trying to log the user in

import * as Castle from '@castleio/castle-js'

// Main app instance that runs at start
class Application {
  constructor() {
    // Initialize the Castle agent as early as possible
    Castle.configure(YOUR_CASTLE_APP_ID);

    // Handle a login request
    document.querySelector('#loginForm').addEventListener('submit', this.handleLogin)
  }
  
  handleLogin = async () => {
    const requestToken = await Castle.createRequestToken();
    // TODO: Append the requestToken and proceed with login request to backend
  }
}

Optional configuration parameters

When initializing Castle.js using the configure method, additional parameters can be passed for advanced usage.

import * as Castle from '@castleio/castle-js'

Castle.configure(appId, options);

option

description

default

window

Overrides the browser window object. Useful e.g. when running in a test environment with a mocked DOM, like JSDOM.

window

avoidCookies

Disables the usage of cookies when set to true

false

cookieDomain

When cookies are used, set the cookie domain scope

top level domain