Identify users and add context

The SDK reads identification keys from the dataLayer for every automatic event. Push them before the SDK initializes: either hash server-side and render the values into the page, or hash in the browser. The dashboard's Install page generates both the npm and the script-tag snippet with an Identify logged-in visitors toggle that adds the browser-hashing version with your site key filled in.

Server-rendered hashes. Compute the hashes on the server (see above) and push them synchronously, above the Shield script tag or the GTM container snippet:

<script>
  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({
    user_id_hash: '9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08',
    plan: 'pro',
    lead_source: 'google_ads'
  });
</script>

Browser-hashed, npm. Fill the identify object from your app's current user, hash with WebCrypto, push, then initialize:

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

// Identify the logged-in visitor (optional).
// Fill these from your app's current user. Values are hashed in the browser;
// Shield never receives the raw user ID or email address.
const identify = {
  userId: '',   // e.g. currentUser.id
  email: '',    // e.g. currentUser.email
  plan: '',     // e.g. currentUser.plan
  salt: ''      // optional secret; use the same salt when resolving hashes
};

async function sha256(text: string): Promise<string> {
  const buf = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
  return Array.from(new Uint8Array(buf), (b) => b.toString(16).padStart(2, '0')).join('');
}

async function identifyVisitor(): Promise<void> {
  const prefix = identify.salt ? identify.salt + ':' : '';
  const email = identify.email.trim().toLowerCase();
  const context: Record<string, string> = {};

  if (identify.plan) context.plan = identify.plan;
  if (email.includes('@')) {
    context.email_domain = email.split('@').pop() ?? '';
    context.email_hash = await sha256(prefix + email);
  }
  if (identify.userId) context.user_id_hash = await sha256(prefix + identify.userId.trim());

  if (Object.keys(context).length) {
    // The SDK reads these keys from the dataLayer for every automatic event.
    const w = window as unknown as { dataLayer?: object[] };
    (w.dataLayer ??= []).push(context);
  }
}

await identifyVisitor();

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

For a plain script tag, the SDK must be loaded after the hashes are ready, because hashing is asynchronous. The Install page's script-tag snippet with the toggle enabled does exactly that: it hashes, pushes to the dataLayer, then injects v1.js (or the pinned SRI build) and calls FindIP.init().

Every automatic event (session_start, page_view, and the automatic form events) then carries those values. Two details matter:

• The SDK takes the first value it finds for each key across all dataLayer entries. Push once, early. A later push with the same key does not replace the earlier one.
• Only these keys are read from the dataLayer: user_id_hash, email_hash, email_domain, plan, transaction_amount, currency, form_name, lead_source. The custom object and account_age_days are accepted only through FindIP.track().

Manual events accept the full field list, including custom:

FindIP.track('checkout_started', {
  user_id_hash: '9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08',
  account_age_days: 412,
  plan: 'pro',
  transaction_amount: 129.0,
  currency: 'USD',
  custom: { cart_items: 3, coupon_applied: true, region: 'eu-west' }
});

Context passed to track() applies to that event only. Manual events do not read the dataLayer, so pass the identifier on each call.

4. WordPress, WooCommerce, and Shopify

The official plugins send coarse page-type context only (product view, checkout view, order received) and never user identifiers. To identify users on those platforms, use the GTM template fields from option 1 if you also run GTM, add the dataLayer push from option 2 to your theme template for logged-in users, or call FindIP.track() from your own code.

Open the site in the Shield dashboard, go to Events, and click an event. The detail drawer shows the stored context under Raw payload (sanitized) as customer_context. Fields that were dropped are shown as null, which is the quickest way to check that a value passed validation.