Preact quickstart

1. Create an account if you do not have one.
2. Go to Fraud Scoring API → Device trackers, create a tracker, and list the domains it may run on. Include localhost while you build.
3. Copy the publishable key. It starts pk_live_.

This key is meant to be visible in your bundle. It is domain-locked and can only send fingerprints: it cannot score, read your data, or work from a site you did not authorise. Your kdn_live_ secret key is the opposite, and passing one to the provider throws immediately rather than letting it ship to every visitor.

Skip to step 3 if you have a project already.

npm create vite@latest kaidn-preact-quickstart -- --template preact
cd kaidn-preact-quickstart
npm install

Run it and open http://localhost:5173, Vite's default.

npm run dev

A component to attach to. Create src/SignupForm.jsx:

export default function SignupForm({ onSubmit, isLoading }) {
  return (
    <form
      class="wrap"
      onSubmit={(e) => {
        e.preventDefault();
        onSubmit(new FormData(e.currentTarget));
      }}
    >
      <h1>Create an account</h1>

      <label for="email">Email</label>
      <input id="email" name="email" type="email" required
             placeholder="you@example.com" />

      <label for="password">Password</label>
      <input id="password" name="password" type="password" required />

      <button type="submit" disabled={isLoading}>
        {isLoading ? "Checking…" : "Create account"}
      </button>
    </form>
  );
}

Preact accepts class and for as well as className and htmlFor. Either is fine; the plain HTML names are used here because that is what Preact's own templates ship.

And enough CSS to see it. Append to src/style.css:

.wrap {
  max-width: 380px; min-height: 100vh; margin: 0 auto;
  display: flex; flex-direction: column; justify-content: center; gap: .5rem;
  padding: 1rem; text-align: left;
}

input { padding: .6rem; border: 1px solid #ccc; border-radius: 6px; font: inherit; }
label { font-size: .85rem; color: #555; }

button {
  margin-top: .75rem; padding: .7rem 1.2rem; font: inherit; cursor: pointer;
  background: #111; color: #fff; border: 0; border-radius: 6px;
}
button:disabled { opacity: .6; cursor: not-allowed; }

npm install @kaidn/preact

Wrap your app once, at the root. The provider holds configuration and collects nothing on its own, so it is safe on every page including the ones with no signup on them.

import { render } from "preact";
import { KaidnProvider } from "@kaidn/preact";
import { App } from "./app.jsx";
import "./style.css";

render(
  <KaidnProvider publishableKey="pk_live_your_key_here">
    <App />
  </KaidnProvider>,
  document.getElementById("app")
);

For production, use an environment variable. Vite exposes anything prefixed VITE_, so import.meta.env.VITE_KAIDN_PK keeps it out of your repository. It is not a secret, but a key you can rotate without a code change is worth having.

Why not @kaidn/react with preact/compat

You can. preact/compat aliases React imports, and @kaidn/react runs fine underneath it. The catch is that it works only while that alias is in your bundler config, and the failure when someone removes it is a build error in a fraud dependency that nobody expects to be React.

This package imports preact and preact/hooksdirectly, so there is nothing to alias and nothing anyone's config can break. The API is deliberately identical, so moving between the two is an import change and nothing else.

useDeviceId() collects when you ask it to, not on mount. That puts the work at the moment somebody acts, which is when the signal is freshest, and keeps fingerprinting off pages that do not need it.

import { useDeviceId } from "@kaidn/preact";
import SignupForm from "./SignupForm.jsx";

export function App() {
  const { getDeviceId, isLoading } = useDeviceId();

  async function handleSubmit(form) {
    // Never throws. A blocked script or an ad blocker returns null, and your
    // signup carries on with one signal fewer.
    const deviceId = await getDeviceId();

    await fetch("/api/signup", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({
        email: form.get("email"),
        password: form.get("password"),
        deviceId,          // your server scores THIS
      }),
    });
  }

  return <SignupForm onSubmit={handleSubmit} isLoading={isLoading} />;
}

The hook gives you four things:

• getDeviceId() collects and returns string | null. Never throws.
• deviceId is the last id collected, or null before the first call.
• isLoading is true while a collection is in flight. Disable your button with it.
• error is whatever went wrong last, for your logging rather than your user.

Note what is not here: no verdict and no decision. The browser is an untrusted place to make one, so it never sees a score. It produces an id; your server produces the judgement.

A double-clicked button fingerprints once, not twice. The hook keeps one collection in flight at a time. Preact has no StrictMode double-invoke to work around, so that guard is there purely for the impatient-visitor case, which is the one that actually happens in production.

This is the step that turns a device id into fraud prevention. Everything before it collects; nothing before it decides.

Your /api/signup handler takes the id and passes it to /v1/score. Node, since you are already in a JavaScript project:

import { Kaidn } from "@kaidn/sdk";

// Your SECRET key. Server only, never the browser.
const kaidn = new Kaidn({ apiKey: process.env.KAIDN_API_KEY });

// Express, Fastify, Hono, a Next.js route handler: the call is the same.
app.post("/api/signup", async (req, res) => {
  let r;
  try {
    r = await kaidn.score({
      event: "signup",
      ip: req.ip,
      email: req.body.email,
      device_id: req.body.kaidn_device_id,   // the id the browser collected
    });
  } catch {
    // FAIL OPEN. An outage in your fraud vendor must never become an
    // outage in your signup form.
    return res.json({ ok: true });
  }

  if (r.verdict === "block") {
    // Do not name the signal. It teaches the next attempt.
    return res.status(403).json({ error: "We could not create that account." });
  }

  const user = await createUser(req.body);
  if (r.verdict === "review") await flagForReview(user.id, r.event_id, r.reason_text);

  res.json({ ok: true });
});

Three answers, and you decide what each one means. Kaidn never blocks anybody on your behalf.

npm run dev

Open http://localhost:5173, fill the form, submit, and look at the network tab. Your /api/signup request carries the id:

{ "email": "you@example.com", "deviceId": "8f1c2ae9d4b7c3e05a1f6b28d9074e3c" }

Turn ad blockers off on localhost while you test. Any fingerprinting script can be blocked by an extension, and when that happens you get nothing rather than a cautious answer. We measured what that does to a competitor and published the numbers. That is why the hook returns null instead of throwing, and why the device id is one signal in a score rather than the whole thing.