@castleio/castle-js

Castle Fingerprinting Script

Packaged version of Castle fingerprinting script.

Introduction

The Castle JavaScript automatically captures every user action in your web application, including clicks, taps, swipes, form submissions, and page views. We use this data to build profiles of good user behavior in order to detect the bad.

Installation

npm install --save @castleio/castle-js

yarn add @castleio/castle-js

Configuration

Basic configuration of the app

// @option options [string] :pk castle publishable key.
// @option options [object] :window (default `window`) eg JSDOM.window
// @option options [boolean] :avoidCookies (default `false`) when true cookies usage will be avoided
// @option options [string] :cookieDomain (default topLevel domain) cookies domain scope
// @option options [string] :apiUrl (default `https://m.castle.io/v1/monitor`) castle api url
// @option options [number] :timeout (default 1000) castle api response timeout
// @option options [boolean] :verbose (default true) verbose mode

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

Castle.configure(options);

Usage

Getting castle request token

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

Castle.createRequestToken().then( (requestToken) => {
  ....
});

// or
const requestToken = await Castle.createRequestToken();

See Castle Docs for more information and how to pass the token further.

form submit helper example (when castle.browser.js is used)

// @param event [Event] submit event
// @param onDone [Function] optional form submit callback replacement

<form action="/" onsubmit="_castle('injectTokenOnSubmit', event)">
  <button type="submit">Submit</button>
</form>

helper is also available directly (when castle.umd.js is used)

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

const submitHandler = (evt) => Castle.injectTokenOnSubmit(evt);

<form action="/" onsubmit="submitHandler(event)">
  <button type="submit">Submit</button>
</form>

browser version

If your environment does not support modules you can use the browser version

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

_castle('configure', {pk: YOUR_CASTLE_PUBLISHABLE_KEY});
_castle('createRequestToken').then( (requestToken) => {
  ....
});

Sending page event

// @param options [PageParams] castle page command params.
// @option user [UserParams] user object with the required `id`, optional `email`, `phone`, `registered_at`, `name`, `traits`
// @option userJwt [string] optiona jwt encoded UserParams
// @option name [String]
// @option referrer [String]
// @option url [String]

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

const page = Castle.page(options);

event response can be verified with promise like call.

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

// result - true - success response from the server
// result - false - error response from the server, missing configuration or data
// result - null - timeout or debounced event (300ms)

Castle.page(options).then( (result) => { } )

If your environment does not support modules you can use the browser version

// @param options [PageParams] castle page command params.
// @option user [UserParams] user object with the required `id`, optional `email`, `phone`, `registered_at`, `name`, `traits```
// @option userJwt [string] JWT encoded UserParams (can be passed instead of the user)
// @option name [String]
// @option referrer [String]
// @option url [String]

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

_castle('configure', {pk: YOUR_CASTLE_PUBLISHABLE_KEY});
_castle('page', options);

Sending form event

// @param options [FormParams] castle form command params.
// @option user [UserParams] user object with the required `id`, optional `email`, `phone`, `registered_at`, `name`, `traits`
// @option userJwt [string] JWT encoded UserParams (can be passed instead of the user)
// @option name [String]
// @option values [Record<string, string>]

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

Castle.form(options);

event response can be verified with promise like call.

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

// result - true - success response from the server
// result - false - error response from the server, missing configuration or data
// result - null - timeout or throttled event (300ms)

Castle.form(options).then( (result) => { } )

If your environment does not support modules you can use the browser version

// @param options [FormParams] castle form command params.
// @option user [UserParams] user object with the required `id`, optional `email`, `phone`, `registered_at`, `name`, `traits`
// @option userJwt [string] JWT encoded UserParams (can be passed instead of the user)
// @option name [String]
// @option values [Record<string, string>]

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

_castle('configure', {pk: YOUR_CASTLE_PUBLISHABLE_KEY});
_castle('form', options);

form submit helper for form events (when castle.browser.js is used)

// @param event [Event] submit event
// @param user_or_userJwt [UserParams| string] user object with the required `id`, optional `email`, `phone`, `registered_at`, `name`, `traits`,
//        data will be treated as JWT if provided as string
// @param options [FormEventOnSubmitOptions] optional

<form action="/" data-castle-name="Change Profile" onsubmit="_castle('formEventOnSubmit', event, user_or_userJwt options?)">
  <input type="text" name="user_mail" data-castle-value="email">
  <button type="submit">Submit</button>
</form>

helper is also available directly (when castle.umd.js is used)

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

const user = YOUR_USER_DATA;
const submitHandler = (evt) => Castle.formEventOnSubmit(evt, user);

<form action="/" data-castle-name="Change Profile" onsubmit="submitHandler(event)">
  <input type="text" name="user_mail" data-castle-value="email">
  <button type="submit">Submit</button>
</form>

Sending custom event

// @param options [CustomParams] castle custom command params.
// @option user [UserParams] user object with the required `id`, optional `email`, `phone`, `registered_at`, `name`, `traits`
// @option userJwt [string] JWT encoded UserParams (can be passed instead of the user)
// @option name [String]
// @option properties [Record<string,string>]

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

const custom = Castle.custom(options);

event response can be verified with promise like call.

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

// result - true - success response from the server
// result - false - error response from the server, missing configuration or data
// result - null - timeout or debounced event (300ms)

Castle.custom(options).then( (result) => { } )

If your environment does not support modules you can use the browser version

// @param options [CustomParams] castle custom command params.
// @option user [UserParams] user object with the required `id`, optional `email`, `phone`, `registered_at`, `name`, `traits`
// @option userJwt [string] JWT encoded UserParams (can be passed instead of the user)
// @option name [String]
// @option properties [Record<string,string>]

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

_castle('configure', {pk: YOUR_CASTLE_PUBLISHABLE_KEY});
_castle('custom', options);

Upgrade from 1.x script

Before

_castle('getClientId')

After

Castle.createRequestToken().then( (requestToken) => {
});
// or
const token = await Castle.createRequestToken();

No longer available commands for _castle(...) :

`autoForwardClientId`, 'autoTrack', `catchHistoryErrors`, `identify`, `setUserId`, `setAccount`, `setKey`, `setAccount`, `sessionId`, `reset`, `page`, `trackPageView`, `setTrackerUrl`

Request Token is now required to be passed in the request params and it is no longer available in the cookie. Check the docs

Changelog

• 2.1.0 – added page, form, custom events support, changed configuration DSL, added formEventOnSubmit helper, renamed onFormSubmit to injectTokenOnSubmit
• 2.0.4 – bug fixes
• 2.0.3 – bug fixes and stability improvements
• 2.0.2 – bug fixes
• 2.0.1 – internal enhancements
• 2.0.0 – migration from 1.x, modularization, updated DSL

Minimal Requirements:

ES3+ version supported browsers eg:

• Chrome 5+
• Firefox 3+
• IE 6+
• Safari 4+
• All modern browsers (desktop and mobile)

to use page/form functionality:

• Chrome 9+
• Firefox 6+
• IE 10+
• Safari 5+
• All modern browsers (desktop and mobile)

License

MIT