Castle Fingerprinting Script
Packaged version of Castle fingerprinting script.
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.
``bash
npm install --save @castleio/castle-js
`
`bash
yarn add @castleio/castle-js
`
`jswindow
// @option options [string] :pk castle publishable key.
// @option options [object] :window (default ) eg JSDOM.windowhttps://m.castle.io/v1/monitor
// @option options [string] :apiUrl (default ) castle api url__cuid
// @option options [number] :timeout (default 1000) castle api response timeout
// @option options [boolean] :verbose (default true) verbose mode (console warnings)
// @option options [object] :storage (default name , default expireIn 400 days in seconds: 34560000) used for storing uuid in the localStorage and the cookies, and for setting cookie expiration time.
import * as Castle from '@castleio/castle-js'
Castle.configure(options);
`
If your environment does not support modules you can use the browser version
`js
import '@castleio/castle-js/dist/castle.browser.js'
Castle.configure(options);
`
`js
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.
js
// @param event [Event] submit event
// @param onDone [Function] optional form submit callback replacement
``html
`helper is also available directly (when castle.umd.js is used)
`js
import * as Castle from '@castleio/castle-js'const submitHandler = (evt) => Castle.injectTokenOnSubmit(evt);
``html
`$3
`js
// @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.
`js
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) => { } )
`$3
`js
// @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]import * as Castle from '@castleio/castle-js'
Castle.form(options);
`event response can be verified with promise like call.
`js
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) => { } )
`form submit helper for form events
`js
import * as Castle from '@castleio/castle-js'const user = YOUR_USER_DATA;
const submitHandler = (evt) => Castle.formEventOnSubmit(evt, user);
``html
`$3
`js
// @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]import * as Castle from '@castleio/castle-js'
const custom = Castle.custom(options);
`event response can be verified with promise like call.
`js
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 (default 1000ms)
Castle.custom(options).then( (result) => { } )
`Breaking changes
Upgrading from 1.x to 2.0.x
$3
Legacy package: https://www.npmjs.com/package/castle.js
`js
require "castle.js"
``js
_castle('setAppId', "YOUR_APP_ID")
_castle('getClientId')
`$3
New package:
`js
import * as Castle from "@castleio/castle-js"
`1. Renamed the main object from
_castle to Castle in the new module, but kept the _castle in the CDN version as well as the browser-specific module @castleio/castle-js/dist/castle.browser.js
2. Introduced the concept of request tokens that need to be generated for each call to Castle's server-side API.`js
Castle.createRequestToken().then( (requestToken) => {
});// or
const token = await Castle.createRequestToken();
`3. Request tokens can no longer be retrieved from the cookie string.
4. All the following methods were removed:
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
Upgrading from 2.0.x to 2.1.x or later
$3
`js
Castle.configure(YOUR_CASTLE_APP_ID);
`$3
1. Removed the
_castle object for all versions and now only relying on Castle.2. Switched to use the Publishable Key that can be found in the same place as the now deprecated App ID.
`js
Castle.configure({pk: YOUR_PUBLISHABLE_KEY});
`3.
onFormSubmit has been renamed to injectTokenOnSubmit4.
_castle global method is no longer supported and has been replaced with Castle (for the CDN and castle.browser.js versions) check docs5. CDN version no longer needs
appID in the url and requires
`javascript
`
to be added. The CDN version can't be used for generating request tokens, but only for tracking client-side events.6. Introduced
page, form, and custom methods for client-side event tracking
More info can be found in the docs
Changelog
* 2.8.4 - performance updates
* 2.8.3 - performance updates
* 2.8.2 – security enhancements
* 2.8.1 – bug fixes
* 2.8.0 - security updates, removed official support for older browsers (target updated from ES3 to ES5); updated minimal requirements
* 2.7.1 - no changes
* 2.7.0 - createRequestToken, page, form, and custom return Promise if available (Thenable otherwise), internal enhancements
* 2.6.2 - reduced bundle size, added internal features, added support for chaining .then, as well as using .catch and .finally for the createRequestToken, page, form, and custom
* 2.6.1 - removed undocumented getVersion function and dropped usage of temporary cookie, internal enhancements
* 2.6.0 - bug fixes and internal features
* 2.5.3 - security updates
* 2.5.2 - internal release
* 2.5.1 - extended browser support range and bug fixes
* 2.5.0 - enhanced bot detection capabilities, performance improvements, bug fixes
* 2.4.3 - internal enhancements
* 2.4.2 - force https for the monitor requests, bug fixes, utf enhancements
* 2.4.1 – internal enhancement
* 2.4.0 – larger set of enhancements and internal features
* 2.3.6 – internal enhancements
* 2.3.5 – fixed issue with exporting types in the d.ts file
* 2.3.4 – internal enhancements
* 2.3.3 – internal enhancements
* 2.3.2 – bug fixes
* 2.3.1 – internal stability fixes
* 2.3.0 – new configuration option throttling, enabled by default, and set to 500ms, is used when multiple custom events are being sent within short time intervals.
* 2.2.0 – new configuration option storage, deprecated storageNamespace, and stability improvements.
* 2.1.15 – new configuration option storageNamespace`, for specifing localStorage and cookie storage namespace, stability improvements* Chrome 38+
* Firefox 44+
* Opera 32+
* Edge 12+
* Safari 8+
* All modern browsers (desktop and mobile)
MIT