# Quickstart

Install FindIP Shield on your website in under two minutes.

## npm Install

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

```bash
npm install @findip/shield
```

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

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

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

The package includes ESM, CommonJS, and TypeScript declarations. Replace
`pub_xxxxxxxxx` with your public site key from the FindIP dashboard.

To attach your own user to each session, pass `identify: { userId, email, plan }`
to `init()`; the SDK hashes the values in the browser. The Install page's npm snippet has an "Identify
logged-in visitors" toggle that adds this for you; see
[Identify Users and Add Context](https://www.findip.net/docs/shield/identify-users.md).

## Script Tag Install

Paste this before the closing `</body>` tag:

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

Replace `pub_xxxxxxxxx` with your public site key from the FindIP dashboard.

The `v1.js` URL always serves the latest non-breaking 1.x build. If you prefer
to pin an exact version with subresource integrity, use the pinned snippet
(shown on your site's Install page with a current hash):

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

Pinned URLs are immutable; upgrading means changing the version and hash.

To attach your own user to each session with the script tag, enable "Identify
logged-in visitors" on the Install page. The snippet then carries the user's ID,
email and plan as `data-*` attributes; the SDK hashes them in the browser
before sending. See [Identify Users and Add Context](https://www.findip.net/docs/shield/identify-users.md).

## What Happens Automatically

1. SDK loads and auto-initializes from `data-*` attributes
2. A first-party session cookie (`_fip_sid`) is created
3. A `page_view` event is sent to FindIP
4. Form submissions are detected and classified (signup, login, checkout, etc.)
5. Risk results are pushed to `dataLayer` if GTM is present

## Next: Identify Your Users

Events are anonymous until you attach your own user identifier. Push a hashed
user ID to the dataLayer or pass it to `FindIP.track()` so a risky session can
be traced back to an account in your system. See
[Identify Users and Add Context](https://www.findip.net/docs/shield/identify-users.md).

## Verify Installation

Open browser DevTools → Network tab. Filter for `shield/track`. You should see POST requests after page load.

## Options

| 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 GTM dataLayer |
| `data-debug` | `false` | Enable console debug logging |

## Troubleshooting

- **No events appearing**: Check that your domain is allowlisted for the site key
- **CORS errors**: Ensure your origin matches the configured allowed domain
- **No visitor cookie**: Expected in `strict` privacy mode

---

Canonical page: https://www.findip.net/docs/shield/quickstart · Markdown: https://www.findip.net/docs/shield/quickstart.md · All Shield docs in one file: https://www.findip.net/llms-full.txt