Shield · Quickstart

Install FindIP Shield in under two minutes

Install from npm for bundled applications or add one script tag directly. Every visit gets a session, risk signals, and auto-detected form events.

npm install

Recommended for React, Next.js, Vue, Vite, and other bundled applications.

npm install @findip/shield

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

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

await track('signup_attempt', { plan: 'free' });

The official @findip/shield package includes ESM, CommonJS, and TypeScript declarations. Replace pub_xxxxxxxxx with your public site key from the dashboard.

CDN script tag install

For sites without a bundler, paste before the closing </body> tag. Replace pub_xxxxxxxxx with your public site key from the dashboard.

<script
  src="https://cdn.findip.net/shield/v1.js"
  data-site-key="pub_xxxxxxxxx"
  data-auto-track="true"
  data-privacy-mode="balanced">
</script>

That's it — the v1.js URL always serves the latest non-breaking 1.x build, so you get fixes and improvements automatically. Prefer to lock down an exact version? See Versions below.

What happens automatically

1. Auto-initThe SDK initializes itself from the data-* attributes.

2. SessionA first-party session cookie (_fip_sid) is created.

3. First eventA page_view event is sent to FindIP.

4. FormsForm submissions are detected and classified (signup, login, checkout, …).

5. GTMRisk results are pushed to dataLayer if Google Tag Manager is present.

Manual events & verification

FindIP.track('signup_attempt', {
  email_domain: 'gmail.com',
  plan: 'free',
});

Verify the install: open browser DevTools → Network tab and filter for shield/track. You should see POST requests after page load — and the event on your site's dashboard moments later.

Options

All configuration via data-* attributes

Attribute	Default	Description
`data-site-key`	required	Your public site key
`data-privacy-mode`	`balanced`	`strict`, `balanced`, or `advanced`
`data-auto-track`	`true`	Auto page view tracking
`data-auto-detect-forms`	`true`	Auto form submit detection
`data-push-to-data-layer`	`true`	Push risk results to the GTM dataLayer
`data-debug`	`false`	Enable console debug logging

No events appearingCheck that your domain is allowlisted for the site key.

Origin rejectedEnsure your page's origin matches the site's configured allowed domains.

No visitor cookieExpected in strict privacy mode.

Versions

All published SDK builds on the CDN

Version	URL	SRI hash
`v1` (latest 1.x)	`https://cdn.findip.net/shield/v1.js`	—
`1.0.8`	`https://cdn.findip.net/shield/1.0.8/findip-shield.min.js`	`sha384-aJa5dlL7hwJ6DtWQEKKDt6ScyoyaUwd9tayFZod2uWxGU4/s2dGMqzmGa8MWkdAr`
`1.0.7`	`https://cdn.findip.net/shield/1.0.7/findip-shield.min.js`	`sha384-bmSqh1lpjT7HOgHC6ashLVMkYXQefCX+pvv0CQDRvdRRSCWYfOgHLsmnQT7PeHQ2`
`1.0.6`	`https://cdn.findip.net/shield/1.0.6/findip-shield.min.js`	`sha384-bF++3gi7opAIskDJwzrfKVtMMSWIB5kqFFuUvIPS/edUz7kXzFpYOMoBBypjBOVx`
`1.0.5`	`https://cdn.findip.net/shield/1.0.5/findip-shield.min.js`	`sha384-rwISMrRaCS6RMzWGm8J3VimsKtyhHuJwOc+ZmUYZPyynHyU5kICyoXXQsYlTp/5e`
`1.0.4`	`https://cdn.findip.net/shield/1.0.4/findip-shield.min.js`	`sha384-sStx4NQ370t3JTfuEWFjXyE8bjX6BVkL7G5CBq1Vuu+vc/MBVMjXybrKjh5MUrAM`
`1.0.1`	`https://cdn.findip.net/shield/1.0.1/findip-shield.min.js`	`sha384-4h6bh1btv0FKVS4QdmCwBQLPJKWjzZnaEiC4KyugJBf8RLfhTNT0fvHvvSelG8Og`
`1.0.0`	`https://cdn.findip.net/shield/1.0.0/findip-shield.min.js`	`sha384-PeQP/w5zFyMfV9tAzduMXZi85Z+MsaQ92jaK0L0BBBmp72Qt8exJTtf/776MSD4D`

Pinning an exact version. The rolling v1.js URL is the easiest option and safe for most sites. If your security policy requires a fixed, verifiable build, load a versioned URL with subresource integrity instead — the browser then refuses to run the script unless it exactly matches the hash:

<script
  src="https://cdn.findip.net/shield/1.0.8/findip-shield.min.js"
  integrity="sha384-aJa5dlL7hwJ6DtWQEKKDt6ScyoyaUwd9tayFZod2uWxGU4/s2dGMqzmGa8MWkdAr"
  crossorigin="anonymous"
  data-site-key="pub_xxxxxxxxx"
  data-auto-track="true"
  data-privacy-mode="balanced">
</script>

Pinned URLs are immutable — the file at a versioned URL never changes. Upgrading means updating both the version in the URL and the integrity hash (your site's Install page always shows the current pinned snippet). SRI hashes can't be used with v1.js, since its content changes as new 1.x builds are released.