Client Components

This page documents the OpenClientID client component model:

• Which built-in components exist.
• Which ones are enabled by default.
• Which ones are stable vs unstable.
• How to add custom components.

Default behavior

• By default, OpenClientID includes all stable built-in components.
• Unstable built-ins are opt-in via includeComponents or explicit components.

Composition controls:

• components: explicit ordered built-in base list.
• includeComponents: additional built-ins appended after base.
• excludeComponents: built-ins removed from selection.
• customComponents: custom collectors appended after built-ins.

Built-in component matrix

Legend:

• 🟢 enabled by default / stable
• 🔴 not enabled by default / unstable
• 🟡 conditional instability

Adding custom components

Use customComponents in getFingerprint:

import { getFingerprint } from "openclientid";

const result = await getFingerprint({
	customComponents: [
		{
			id: "tenantTier",
			code: "ten",
			version: 1,
			kind: "h",
			getData: async () => ({ tier: "pro", region: "us-east-1" }),
		},
	],
});

Custom component fields

• id (required): unique string id. Must not match any built-in component id.
• code (required): exactly 3 lowercase alphanumeric characters.
• version (optional): integer 0..99 (default 1).
• kind (optional): one of h, b, e, n (default h).
• unstable (optional): if true, custom part is placed in unstable segment.
• getData (required): sync/async collector that returns raw value.
• getPayload (optional): payload builder for non-h kinds.

Deterministic custom payload example

import { getFingerprint } from "openclientid";

const result = await getFingerprint({
	customComponents: [
		{
			id: "cookieBannerSeen",
			code: "cbs",
			version: 1,
			kind: "b",
			getData: () => ({ seen: true }),
			getPayload: ({ value }) =>
				(value as { seen?: boolean }).seen === true ? "1" : "0",
		},
	],
});

Rules:

• For kind: "h", payload is the component hash automatically.
• For kind: "b" | "e" | "n", set getPayload to return your compact deterministic payload.
• Payload may contain only letters, numbers, and _.