identifyOnInteraction()

agent.identifyOnInteraction() starts identification when a visitor first interacts with an element. Call take() when submitting to obtain that result or start a fresh check.

import { load } from '@shieldlabs-ai/js';

const agent = await load({ publicKey: 'PUBLIC_API_KEY' });
const form = document.querySelector<HTMLFormElement>('#signup');
if (!form) throw new Error('Signup form not found');

const identification = agent.identifyOnInteraction(form);

Arguments

EventTarget

required

The form or element to observe. It must support addEventListener and removeEventListener. The agent listens for focusin, pointerdown and keydown.

IdentifyOptions

Optional userId and timeout, with the same rules as identify(). Recreate the handle if the signed-in user changes.

Returned handle

The method synchronously returns an InteractionIdentifier with two methods:

Promise<IdentifyResult>

required

Returns an in-flight or successful early identification while it is fresh. Starts a new identification if none exists, the earlier one failed, or it completed at least four minutes ago. Each call re-arms the handle for the next submission.

void

required

Removes the listeners and drops the retained result. Call it when the form is removed or the component unmounts. It does not cancel a check already in progress.

Use take() in your existing submit handler before forwarding the protected action:

const { requestId: identificationId } = await identification.take();
// Include identificationId in the request to your backend.

Remove the listeners during cleanup:

identification.dispose();

Refresh and errors

While interactions continue, a completed early result can be replaced after four minutes. After an early failure, another interaction can retry after five seconds. This is interaction-driven, not a background polling timer. Each identification that runs consumes volume, even if the form is never submitted. Invalid arguments throw invalid_options synchronously. take() returns a promise that can reject with the identification errors. Handle rejection before completing the protected action.

Run a check

Get the result

Account

Contracts

identifyOnInteraction()

Arguments

Returned handle

Refresh and errors

​Arguments

​Returned handle

​Refresh and errors

Arguments

Returned handle

Refresh and errors