Angular 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 provideKaidn() throws where you wrote it rather than letting it ship to every visitor.

Skip to step 3 if you have a project already.

npx @angular/cli new kaidn-angular-quickstart --standalone --style css
cd kaidn-angular-quickstart
npm install @kaidn/angular

One line in your application config. It holds configuration and collects nothing on its own, so it is safe in an app whose routes mostly have no signup on them.

import { ApplicationConfig } from "@angular/core";
import { provideKaidn } from "@kaidn/angular";

export const appConfig: ApplicationConfig = {
  providers: [
    provideKaidn({ publishableKey: "pk_live_your_key_here" }),
  ],
};

On an NgModule app the same call goes in providers on your @NgModule. provideKaidn returns a plain Provider[], so both work without a second entry point.

Why there is no NgModule, and no @Injectable

You will notice reading the source that KaidnServicecarries no decorator. That is deliberate. An Angular decorator has to be processed by Angular's own compiler, which is why libraries that use them ship partial-Ivy output from ng-packagrand get relinked against each consumer's Angular version, and why such libraries break on majors.

This package is built from runtime API only: InjectionToken, inject, signal, and one factory provider. Plain tsc compiles it, there is nothing to relink, and no version of Angular can break the build. The whole cost is the provideKaidn(…) line above, which every other Angular library asks for anyway.

Validation happens where you wrote it. provideKaidn() checks the key when it is called, in your app config, rather than lazily on first injection three navigations later. A bad key gives you a stack trace pointing at the mistake.

Inject the service and ask it for an id. It collects when you call it, not when it is constructed. That puts the work at the moment somebody acts, which is when the signal is freshest, and keeps fingerprinting off routes that do not need it.

import { Component, inject } from "@angular/core";
import { KaidnService } from "@kaidn/angular";

export class SignupComponent {
  readonly kaidn = inject(KaidnService);

  email = "";
  password = "";

  async submit() {
    // Never throws. A blocked script, an ad blocker, or server rendering all
    // resolve to null, and your signup carries on with one signal fewer.
    const deviceId = await this.kaidn.getDeviceId();

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

Bind the template straight to the service, since the state is exposed as signals:

<button type="submit" [disabled]="kaidn.isLoading()">
  {{ kaidn.isLoading() ? "Checking…" : "Create account" }}
</button>

The service gives you four things:

• getDeviceId() collects and resolves to string | null. Never throws.
• deviceId is a read-only signal holding the last id, or null before the first call.
• isLoading is a read-only signal, true while a collection is in flight.
• error is a read-only signal holding whatever went wrong last, for your logging rather than your user.

They are read-only on purpose: a consumer that could .set() them would be writing a device id nothing collected.

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 service keeps one collection in flight at a time, so an impatient visitor costs you one beacon rather than two.

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:

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.

ng serve

Open http://localhost:4200, 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 it resolves to null instead of throwing, and why the device id is one signal in a score rather than the whole thing.