Shield · SDK reference

JavaScript SDK

Use named imports from @findip/shield or the global window.FindIP CDN object. The SDK never collects passwords, card numbers, raw emails, or form contents — only metadata.

npm and module bundlers

Typed ESM and CommonJS entry points for modern applications.

npm install @findip/shield

import { init, track, getSession, setConsent } from '@findip/shield';

init({
  siteKey: 'pub_xxxxxxxxx',
  privacyMode: 'balanced',
  autoTrack: true,
  autoDetectForms: true,
});

await track('login_attempt');
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
  endpoint: 'https://shield.findip.net/v1/shield/track',
  debug: false,
  maxPayloadBytes: 32768,
  sessionCookieDurationMinutes: 30,
  visitorCookieDurationDays: 30,
});

`FindIP.track(eventName, context)`

Track an event with optional customer context.

FindIP.track('signup_attempt', {
  email_domain: 'gmail.com',
  plan: 'free',
  user_id_hash: 'abc123...',
  custom: { referral: 'partner_x' },
});

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.

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 collects passwords, credit card numbers, raw emails, or full form contents. Only metadata (field types, counts, button text category) is sent — see Data Collection for the field-level breakdown and Events for the payload schema.