Introduction

The Browser SDK is a central component of the Castle integration, and provides device fingerprinting and behavioral analysis.

The primary purpose of the SDK is to create request tokens: unique, short-lived tokens that carry the device and behavioral signals Castle collected in the browser. Your frontend passes a token to your server, and your server includes it when calling Castle's Risk and Filter APIs.

A working integration has three parts:

1. Castle.js runs on your pages and collects signals.
2. Your frontend creates a request token and sends it to your backend with the user action (login, signup, and so on).
3. Your backend calls the Castle API with that token. See the Integration guide for the server side.

Requirements

Castle.js requires a browser with native Promise support. This covers all current versions of Chrome, Safari, Firefox and Edge. Internet Explorer 11 and legacy embedded webviews without native Promise are not supported.

Installation

Install the Castle Browser SDK package using your preferred package manager. Setup instructions and credentials are available in the Castle Dashboard.

Configuration

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

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

const castle = Castle.configure({ pk: '<YOUR_PUBLISHABLE_KEY>' });

import '@castleio/castle-js/dist/castle.browser.js'

const castle = Castle.configure({ pk: '<YOUR_PUBLISHABLE_KEY>' });

configure() returns the SDK instance. Keep a reference to it, as it's what you call createRequestToken() on later.

Content Security Policy

Castle.js loads web worker assets and injects inline CSS. If you run a strict Content Security Policy, you need to allow:

Creating request tokens

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.

const requestToken = await castle.createRequestToken();

The createRequestToken method doesn't accept any options.

Call configure() as early as possible in page load, and don't generate a token on the very first frame after it. Token generation is asynchronous: the SDK collects and encodes device signals at generation time, which is normally near-instant, but a token requested before the SDK has finished loading its external resources (workers, CSS) can take up to 1-2 seconds.

Examples on how to pass the request token

const token = await castle.createRequestToken();

fetch('https://example.com/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    ...loginData,
    castle_request_token: token
  })
})

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

myForm.addEventListener('submit', async (e) => {
  e.preventDefault();

  let hiddenField = myForm.querySelector('input[name="castle_request_token"]');
  if (!hiddenField) {
    hiddenField = document.createElement('input');
    hiddenField.type = 'hidden';
    hiddenField.name = 'castle_request_token';
    myForm.appendChild(hiddenField);
  }

  hiddenField.value = await castle.createRequestToken();
  myForm.submit();
});

Verifying your integration

After deploying, confirm the three parts in order.

1. The SDK initializes and returns a token. On a page where configure() has run, call await castle.createRequestToken() from the browser console. You should get back a long opaque string.
2. The token reaches your backend. Inspect the outgoing request and confirm the token is present in the request body.
3. Castle receives the event. Open Explore in the Castle Dashboard and look for the event your backend just sent.

Common problems

Upgrading from 2.x to 3.0

Configuration

The configure() surface has been reorganized from flat, abbreviated keys to a nested, descriptive shape.

Removed fields

Undocumented options

2.x also accepted a handful of options that were never part of the documented configuration. If you were passing any of these, they now live under a nested name:

cookieDomain is unchanged. Any other option that doesn't appear in the configuration table above is no longer supported.

Removed APIs

The public surface is now exactly two methods: configure() and createRequestToken(). Everything below has been removed.

Promises

The SDK now returns real Promise objects instead of thenable wrappers. Environments without native Promise support (such as IE11 or legacy embedded webviews) are no longer supported.

Request token transport

The request token must now be sent in the request body (not as an HTTP header). The token may exceed the size limits imposed by servers and proxies on individual HTTP headers.

Migration checklist

1. Confirm every browser you support has native Promise (see Requirements)
2. Remove window, timeout and throttling from your configure() call
3. Move any worker URL or CSS overrides to their nested names
4. Replace form() and custom() calls with createRequestToken()
5. Remove usage of page(), injectTokenOnSubmit() and formEventOnSubmit()
6. Check whether you were relying on page()/form()/custom() to send activity to Castle, not just to mint tokens. If so, move that activity server-side
7. Ensure the request token is sent in the request body, not as a header
8. Update any test setup that passed the window option, which has been removed
9. Verify your Content Security Policy allows the worker and style directives (see Content Security Policy)