JavaScript SDK
Use named imports from @findip/shield or the global window.FindIP CDN object. The SDK never reads what a visitor types into a field: no passwords, card numbers, email addresses or other form values are sent. For each form it sends metadata, including the labels and button text printed on the page, and outside strict mode it may take one picture of the form with every value blanked.
npm and module bundlers
Typed ESM and CommonJS entry points for modern applications.
npm install @findip/shieldimport { init, track, getSession, setConsent } from '@findip/shield';
init({
siteKey: 'pub_xxxxxxxxx',
privacyMode: 'balanced',
autoTrack: true,
autoDetectForms: true,
});
// The login form's submit is reported by form detection (login_attempt).
// Report the outcome yourself:
await track('login_success');
const { sessionId } = getSession();See the package on npm or review its source on GitHub. The named exports provide the same API as the CDN examples below.
FindIP.init(options)
Called automatically on script-tag install; call manually for bundler installs.
FindIP.init({
siteKey: 'pub_xxxxxxxxx', // required
privacyMode: 'balanced', // strict | balanced | advanced
autoTrack: true,
autoDetectForms: true,
pushToDataLayer: true,
consentRequired: false,
noConsentMode: 'strict', // strict | disabled
integration: undefined, // javascript | gtm | wordpress | woocommerce | shopify; worked out from the page when omitted
identify: null, // 1.0.9+: { userId, email, plan, salt, custom }, see FindIP.identify() below
identityKey: null, // 1.1.0+: normally omitted, the SDK fetches your site's identity public key itself
captureFormSnapshots: true, // 1.9.0+: false = this browser never takes a picture of a form
snapshotRendererUrl: 'https://cdn.findip.net/shield/vendor/html-to-image-1.11.13.min.js', // 1.9.0+: loaded only when a picture is wanted
endpoint: 'https://shield.findip.net/v1/shield/track',
debug: false,
maxPayloadBytes: 32768,
sessionCookieDurationMinutes: 30,
visitorCookieDurationDays: 30,
sessionField: false, // 1.11.0+: true, or a field name, adds the session ID to your forms as a hidden input
linkSession: false, // 1.11.0+: carry the session ID across link clicks for browsers that keep no session cookie
});linkSession adds a short-lived _fip token to same-origin links at click time, only for visitors whose session cookie does not work; see Cookies. On the script tag: data-link-session.
sessionField adds a hidden input (findip_session by default) carrying the Shield session ID to forms that POST to the page's own origin, for server verification. On the script tag: data-session-field or data-session-field="your_name".
integration names how the SDK was installed and is reported on every event as sdk.integration. Leave it out for a normal install: the SDK reports gtm when Google Tag Manager is on the page and javascript otherwise. The WordPress, WooCommerce and Shopify integrations set it themselves. A value outside the list is ignored. On the script tag: data-integration.
identify attaches your own user to every event from the first one on; it takes the same object as FindIP.identify() below. On the script tag: data-user-id, data-user-email, data-plan, data-hash-salt.
identityKey is your site's identity public key (fk1.<key id>.<base64>), used to encrypt the email and user ID passed to identify so that only your Shield dashboard can show them. Normally you leave it out and the SDK fetches the key from Shield once per page, only when identify carries an email or a user ID. Set it to skip that request. On the script tag: data-identity-key.
captureFormSnapshots controls the form picture described in Data Collection. With the default, true, Shield may ask one visitor's browser per form version for a picture of the form with every value blanked, so the dashboard can show what the form looks like. Set it to false and this browser never takes or uploads one. No picture is taken when privacyMode is set to strict, whatever this option says. There is no data- attribute for it: with the script tag, leave data-site-key off the tag and call FindIP.init({ siteKey: 'pub_xxxxxxxxx', captureFormSnapshots: false }) yourself.
snapshotRendererUrl is where the SDK loads the library that draws that picture (html-to-image). It is requested only at the moment a picture is wanted, never on a normal page view. Change it only to serve the same library from your own origin, for example under a strict Content Security Policy.
FindIP.track(eventName, context)
Track an event yourself, with optional customer context.
FindIP.track('signup_success', {
email_domain: 'gmail.com',
plan: 'free',
user_id_hash: 'abc123...',
custom: { referral: 'partner_x' },
});With autoDetectForms on (the default), a submitted <form> is already reported as its attempt event (signup_attempt, login_attempt, payment_attempt and so on). Calling track() with the same event name for the same submit sends a second event, and the attempt is counted twice. Use track() for outcomes (signup_success, login_success, login_failed, payment_failed) and for attempts that fire no form submit event, such as a request sent from a click handler or a call to form.submit(). An event name outside the events reference is recorded as custom.
Allowed context fields: user_id_hash, email_hash, email_domain, account_age_days, plan, transaction_amount, currency, form_name, lead_source, custom. Anything else is dropped. See Identify users and add context for value rules, hashing, and the dataLayer path.
FindIP.identify(options)
Tell Shield which of your users the visitor is.
FindIP.identify({
userId: user.id,
email: user.email,
plan: 'pro',
salt: 'optional-secret'
});The SDK hashes userId and email with SHA-256 in the browser and attaches only user_id_hash, email_hash, email_domain and plan to every subsequent event. Pass the same object as the identify option of init() to have it on the first event, or call it later (after a login); pass null on logout.
Script-tag equivalents: data-user-id, data-user-email, data-plan, data-hash-salt; identityKey / data-identity-key optionally supplies the site's identity key. Requires 1.0.9+ (1.1.0+ for the encrypted email / user ID shown in the dashboard). See Identify users and add context.
Session & consent
FindIP.getSession() returns { sessionId, visitorId } — pass the session id to your backend for server-side verification.
FindIP.setConsent(true);
FindIP.setConsent(false);
FindIP.setConsent({
security_storage: 'granted',
analytics_storage: 'denied',
});Debugging: FindIP.init({ siteKey: '...', debug: true }) logs SDK activity to the console. FindIP.version reports the loaded version.
Privacy guarantees
The SDK never reads what a visitor types into a field: no passwords, card numbers, email addresses or other form values are sent. For each form it sends metadata (field counts and types, the labels printed next to the fields, the button text) and, outside strict mode, Shield may ask one browser for a picture of the form with every value blanked. Data Collection lists everything, field by field; Events has the payload schema.