React Client SDK (Behavioral Biometrics)

Unlike our server-side SDKs (Next.js, Node.js) which run WAF rules and block traffic, the React Client SDK is designed purely for telemetry gathering.

When you enable Strict Behavioral Analysis in your dashboard rules, ZTLayer requires proof of human interaction (mouse movement patterns, touch dynamics, typing cadence). The React SDK captures this data asynchronously, creates a cryptographic token, and appends it to your outbound API requests.

1. Installation

Install the official React package. This package is fully compatible with standard React SPA setups (Vite, Create React App) as well as React frameworks like Next.js or Remix.

npm install @ztlayer/react

2. Global Provider Setup

To gather accurate telemetry, the ZTProvider must be mounted as high up in your component tree as possible (ideally wrapping your entire application).

Security Note

You must use your Project ID here, NOT your secret API Key. Your Project ID is safe to be exposed in the client bundle.

// src/main.tsx (Vite) or src/index.tsx (CRA)
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import { ZTProvider } from '@ztlayer/react';
 
// Use environment variables for the public ID
const projectId = import.meta.env.VITE_ZTLAYER_PROJECT_ID; 
 
ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
  <React.StrictMode>
    <ZTProvider projectId={projectId}>
      <App />
    </ZTProvider>
  </React.StrictMode>,
);

3. Protecting Specific Actions (e.g., Login)

While the provider gathers data globally, you usually only need to submit this telemetry when performing sensitive actions, such as logging in, resetting a password, or making a payment.

Use the useZTLayer hook to generate a one-time, cryptographically signed telemetry token before submitting your form.

import React, { useState } from 'react';
import { useZTLayer } from '@ztlayer/react';
 
export function LoginForm() {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  // 1. Import the hook
  const { generateToken } = useZTLayer();
 
  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
 
    // 2. Await the token generation (usually takes < 10ms)
    // This token contains the encrypted behavioral fingerprint
    const ztToken = await generateToken();
 
    // 3. Attach the token to your API request headers
    const response = await fetch('/api/auth/login', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        // The edge network will look for this header
        'X-ZTLayer-Telemetry': ztToken 
      },
      body: JSON.stringify({ email, password })
    });
 
    if (response.ok) {
      // Handle success
    } else if (response.status === 403) {
      // ZTLayer rejected the request (Likely a bot)
      alert("Security check failed.");
    }
  };
 
  return (
    <form onSubmit={handleSubmit}>
      <input type="email" value={email} onChange={(e) => setEmail(e.target.value)} />
      <input type="password" value={password} onChange={(e) => setPassword(e.target.value)} />
      <button type="submit">Log In</button>
    </form>
  );
}

4. Privacy & GDPR Compliance

ZTLayer takes privacy extremely seriously.

• No PII: The React SDK does not record keystrokes (keylogging), input values, passwords, or the contents of the screen.
• Anonymized Dynamics: It only measures the timing between generic keystrokes, the acceleration of mouse movements, and screen touch pressure.
• No Fingerprinting: We do not use intrusive canvas fingerprinting or cross-site tracking cookies.

If you are operating in the EU, you do not need to prompt users with an explicit cookie banner purely for using the ZTLayer SDK, as it falls under the "Strictly Necessary for Security" exemption under GDPR/ePrivacy. However, consult your legal team for your specific implementation.

Next Steps

• Next.js Server SDK: Learn how to validate this telemetry token on your backend.
• Tutorials: See how this telemetry stops credential stuffing.