@signap/signals-react

React 18+/19 wrapper for @signap/signals-web.

Install

pnpm add @signap/signals-react
# react/react-dom are peerDependencies (>=18 <20)

Usage

import { SignalsProvider, useVisitorData } from "@signap/signals-react";

export function App() {
  return (
    <SignalsProvider
      agent={{
        apiKey: "pk_live_...",
        endpoint: "https://ingest.signap.example",
      }}
    >
      <Page />
    </SignalsProvider>
  );
}

function Page() {
  const { data, isLoading, error, refetch } = useVisitorData({ tag: "page-view" });
  if (isLoading) return <p>Identifying…</p>;
  if (error) return <p>Failed: {error.message}</p>;
  return (
    <>
      <p>visitor: {data?.visitorId}</p>
      <p>confidence: {data?.confidence}</p>
      <button onClick={() => void refetch()}>Re-identify</button>
    </>
  );
}

Hook shape (v2)

useVisitorData() runs agent.identify() once on mount and exposes the resolved visitor in a single field. ADR §A2 means there is no separate ack/lookup transition.

| field | type | when populated | |-------------|---------------------------------------|-------------------------------------------| | data | IdentifyResult \| undefined | once agent.identify() resolves | | isLoading | boolean | true between mount and data arriving | | error | Error \| null | last failure (load / identify) | | refetch | () => Promise<void> | re-run agent.identify() |

StrictMode-safe (ref-guarded so the effect fires once even under double-invoke). SSR-safe (no browser-API access during render — everything is gated behind useEffect).

Endpoint discovery

The agent prop is the underlying AgentLoadOptions, so runtime endpoint discovery flows through unchanged — pass an endpoint callback (the SDK awaits it to resolve the URL). See the @signap/signals-web README (Endpoint section).

<SignalsProvider agent={{ apiKey: "pk_live_...", endpoint: async () => (await myConfig()).ingestEndpoint }}>

The provider snapshots agent on first render (it intentionally ignores later prop changes — remount to swap). If you pass an endpoint callback, keep it referentially stable / side-effect-light.

Breaking changes (v2.0.0)

• identifyAck + visitorData fields collapsed into a single data field — under ADR §A2 the SDK call is fully synchronous, so the transitional ack state is gone.
• polling option removed (no polling).
• Pinned to @signap/signals-web@^2.

See the @signap/signals-web CHANGELOG for the underlying SDK change.