Browser

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

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. Please see the Developer Quickstart on how to use the CDN version.

Installing Castle.js

You install the Castle client-side agentby including it in your app bundle using either the NPM or the Yarn package. This ensures optimal page load speed and avoids 3rd-party resource requests.

npm install --save @castleio/castle-js
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: The browser version of the Castle.js script sets the _castle(...) method on the global window object for the page.

:bulb: Note: The agent should be initialized 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:

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 new request token value should to be generated for each request to your backend. A request token will expire after 120 seconds and should only be used during a single request to your backend.

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();

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
  }
}

Examples of how to pass the request token

const myForm = document.getElementById('loginForm');

myForm.addEventListener(
  'submit',
  function (e) {
    e.preventDefault();

    // Insert a hidden field with the Castle request token
    const hiddenField = document.createElement('input');
    myForm.appendChild(hiddenField);
    hiddenField.setAttribute('type', 'hidden');
    hiddenField.setAttribute('name', 'castle_request_token');
    Castle.createRequestToken().then(function (token) {
      hiddenField.value = token;
      myForm.submit();
    });
  },
  false
);
const myHeaders = new Headers();
const token = await _castle('createRequestToken')

myHeaders.append('X-RequestToken', token);

fetch('https://example.com/login', {
  method: 'POST',
  mode: 'no-cors',
  headers: myHeaders,
  body: JSON.stringify(loginData)
})

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


Did this page help you?