# JavaScript SDK Reference

## npm Package

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

```ts
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();
```

The named exports provide the same API as the CDN global documented below.

## Global Object

```js
window.FindIP
```

## Methods

### `FindIP.init(options)`

Initialize the SDK. Called automatically when using script tag install.

```js
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,
  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](https://www.findip.net/docs/shield/cookies.md). 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](https://www.findip.net/docs/shield/server-verification.md). On the script tag: `data-session-field` or `data-session-field="your_name"`.

### `FindIP.track(eventName, context)`

Track a custom event with optional customer context.

```js
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`.
See [Identify Users and Add Context](https://www.findip.net/docs/shield/identify-users.md) for value rules, hashing, and the dataLayer path.

### `FindIP.identify(options)`

Tell Shield which of your users the visitor is. 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.

```js
FindIP.identify({ userId: user.id, email: user.email, plan: 'pro', salt: 'optional-secret' });
```

Script-tag equivalents: `data-user-id`, `data-user-email`, `data-plan`,
`data-hash-salt`. Requires 1.0.9+. See
[Identify Users and Add Context](https://www.findip.net/docs/shield/identify-users.md).

### `FindIP.getSession()`

Returns `{ sessionId, visitorId }`.

### `FindIP.setConsent(consent)`

```js
FindIP.setConsent(true);
FindIP.setConsent(false);
FindIP.setConsent({
  security_storage: 'granted',
  analytics_storage: 'denied',
});
```

## Payload Example

See the [events reference](https://www.findip.net/docs/shield/events.md) for the full payload schema.

## Privacy Notes

The SDK never collects passwords, credit card numbers, raw emails, or full form contents. Only metadata (field types, counts, button text) is sent.

## Troubleshooting

Enable debug mode: `FindIP.init({ siteKey: '...', debug: true })`.

---

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