@fingerprintjs/fingerprintjs-pro-react-native/dist/fpjs-pro-react-native.d.ts

Official React Native client for Fingerprint PRO. Best identification solution for React Native.

/**
 * FingerprintJS Pro React Native v3.3.1 - Copyright (c) FingerprintJS, Inc, 2025 (https://fingerprint.com)
 * Licensed under the MIT (http://www.opensource.org/licenses/mit-license.php) license.
 */

import { PropsWithChildren } from 'react';

interface RequestOptions {
    /**
     * Custom timeout for the request in milliseconds
     */
    timeout?: number;
}
/**
 * Configuration options for the {@link FingerprintJsProProvider} and {@link FingerprintJsProAgent}
 *
 * @group Types and interfaces
 */
interface FingerprintJsProAgentParams {
    /**
     * your public API key that authenticates the agent with the API
     */
    apiKey: string;
    /**
     * which region to use
     */
    region?: Region;
    /**
     * server API URL, should be only used with the Custom subdomain
     */
    endpointUrl?: string;
    /**
     * provide array of endpoints to specify fallbacks
     */
    fallbackEndpointUrls?: string[];
    /**
     * set this flag to get response in extended format
     */
    extendedResponseFormat?: boolean;
    /**
     * Custom request options
     */
    requestOptions?: RequestOptions;
}
interface QueryResult<TData, TError = Error> {
    /**
     * Visitor identification data
     */
    data?: TData;
    /**
     * Request state after calling `getData()`
     */
    isLoading?: boolean;
    /**
     * Error message in case of failed `getData()` call
     */
    error?: TError;
}
/**
 * The {@link https://dev.fingerprint.com/docs/regions | region} of your application.
 * The parameter is fully optional because JS agent detects the regions automatically using the provided API key.
 * Nevertheless, we recommend always specifying the parameter. Otherwise, the default region us.
 * @group Types and interfaces
 */
type Region = 'eu' | 'us' | 'ap';
/**
 * Visitor identification data
 *
 * @group Types and interfaces
 */
type VisitorData = ShortVisitorData | ExtendedVisitorData;
/**
 * Main identification information about the visitor
 * @group Types and interfaces
 */
interface ShortVisitorData {
    /**
     * The visitor identifier
     */
    visitorId: string;
    /**
     * The current request identifier. It's different for every request.
     */
    requestId: string;
    /**
     * A confidence score that tells how much the agent is sure about the visitor identifier
     */
    confidence: Confidence;
    /**
     * See more details in the Sealed Client Results(https://dev.fingerprint.com/docs/sealed-client-results) guide. The field will miss if Sealed Client Results are disabled or unavailable for another reason.
     */
    sealedResult?: string;
}
/**
 * Represents the probability of accurate identification.
 *
 * @group Types and interfaces
 */
interface Confidence {
    /**
     * A number between 0 and 1 that tells how much the agent is sure about the visitor identifier.
     * The higher the number, the higher the chance of the visitor identifier to be true.
     */
    score: number;
    /**
     * Additional details about the score as a human-readable text
     */
    comment?: string;
}
/**
 * All known identification information about the visitor
 *
 * @group Types and interfaces
 */
interface ExtendedVisitorData extends ShortVisitorData {
    /**
     * If true, this visitor was found and visited before.
     * If false, this visitor wasn't found and probably didn't visit before.
     */
    visitorFound: boolean;
    /**
     * IP address. Only IPv4 are returned.
     * @example
     * '191.14.35.17'
     */
    ip: string;
    /**
     * IP address location. Can be empty for anonymous proxies
     */
    ipLocation?: IpLocation;
    /**
     * OS name.
     * @example
     * 'iOS'
     * @example
     * 'Android'
     */
    os: string;
    /**
     * OS version
     * @example
     * '10.13.6'
     */
    osVersion: string;
    /**
     * Device.
     * @example
     * 'Samsung SM-J330F'
     */
    device: string;
    /**
     * When the visitor was seen for the first time
     */
    firstSeenAt: SeenAt;
    /**
     * When the visitor was seen previous time
     */
    lastSeenAt: SeenAt;
}
/**
 * {@link https://dev.fingerprint.com/docs/geolocation | IP address location}. Can be empty for anonymous proxies.
 *
 * @group Types and interfaces
 */
interface IpLocation {
    /**
     * IP address location detection radius. Smaller values (<50mi) are business/residential,
     * medium values (50 < x < 500) are cellular towers (usually),
     * larger values (>= 500) are cloud IPs or proxies, VPNs.
     * Can be missing, in case of Tor/proxies.
     */
    accuracyRadius?: number;
    /**
     * Latitude
     * Can be missing, in case of Tor/proxies.
     * @example
     * -19.8975
     */
    latitude?: number;
    /**
     * Longitude
     * Can be missing, in case of Tor/proxies.
     * @example
     * -43.9625
     */
    longitude?: number;
    /**
     * Timezone of the IP address location
     * @example
     * 'America/Chicago'
     */
    timezone?: string;
    /**
     * Postal code, when available
     */
    postalCode?: string;
    /**
     * City, when available
     */
    city?: {
        name: string;
    };
    /**
     * Administrative subdivisions array (for example states|provinces -> counties|parishes).
     * Can be empty or missing.
     * When not empty, can contain only top-level administrative units within a country, e.g. a state.
     */
    subdivisions?: [
        {
            isoCode: string;
            name: string;
        }
    ];
    /**
     * Country, when available. Will be missing for Tor/anonymous proxies.
     */
    country?: {
        name: string;
        code: string;
    };
    /**
     * Continent, when available. Will be missing for Tor/anonymous proxies.
     */
    continent?: {
        name: string;
        code: string;
    };
}
/**
 *
 * @group Types and interfaces
 */
interface SeenAt {
    /**
     * The date and time within your subscription. The string format is ISO-8601.
     * @example
     * '2022-03-16T05:18:24.610Z'
     * new Date(result.firstSeenAt.subscription)
     */
    subscription: string | null;
    /**
     * The date and time across all subscription. The string format is ISO-8601.
     * @example
     * '2022-03-16T05:18:24.610Z'
     * new Date(result.firstSeenAt.global)
     */
    global: string | null;
}
/**
 * Tags are returned in the webhook response so make sure the map you are passing to the library represents a valid JSON.
 *
 * @group Types and interfaces
 */
type Tags = {
    [K in string]: Tag | Tag[];
};
/**
 * Tags are returned in the webhook response so make sure the map you are passing to the library represents a valid JSON.
 *
 * @group Types and interfaces
 */
type Tag = string | number | boolean | Tags;
interface VisitorQueryResult extends QueryResult<VisitorData> {
    /**
     * Visitor identification dataaaa
     */
    data?: VisitorData;
}
/**
 * @group Hooks approach
 */
interface VisitorQueryContext extends VisitorQueryResult {
    /**
     * Retrieve the visitor identifier using your public API key.
     * @param tags is a customer-provided value or an object that will be saved together with the analysis event and will be returned back to you in a webhook message or when you search for the visit in the server API. {@link https://dev.fingerprint.com/docs/js-agent#tag | more info in the documentation page}
     * @param linkedId  is a way of linking current analysis event with a custom identifier. This will allow you to filter visit information when using the Server API {@link https://dev.fingerprint.com/docs/js-agent#linkedid | more info in the documentation page}
     */
    getData: (tags?: Tags, linkedId?: string, options?: RequestOptions) => Promise<VisitorData | null>;
}

type VisitorId = string;
/**
 *
 * @group API Client approach
 */
declare class FingerprintJsProAgent {
    /**
     * Initialises FingerprintJS Pro Agent with certain settings
     *
     * @param params
     */
    private requestOptions;
    constructor({ apiKey, region, endpointUrl, fallbackEndpointUrls, extendedResponseFormat, requestOptions, }: FingerprintJsProAgentParams);
    /**
     * Returns visitor identifier based on the request options {@link https://dev.fingerprint.com/docs/native-android-integration#get-the-visitor-identifier | more info in the documentation page}
     *
     * @param tags is a customer-provided value or an object that will be saved together with the analysis event and will be returned back to you in a webhook message or when you search for the visit in the server API. {@link https://dev.fingerprint.com/docs/js-agent#tag | more info in the documentation page}
     * @param linkedId is a way of linking current analysis event with a custom identifier. This will allow you to filter visit information when using the Server API {@link https://dev.fingerprint.com/docs/js-agent#linkedid | more info in the documentation page}
     * @param options is used to configure requests with different settings
     */
    getVisitorId(tags?: Tags, linkedId?: string, options?: RequestOptions): Promise<VisitorId>;
    /**
     * Returns visitor identification data based on the request options {@link https://dev.fingerprint.com/docs/native-android-integration#get-the-visitor-identifier | more info in the documentation page}
     *
     * Provide `extendedResponseFormat` option in the {@link constructor} to get response in the {@link https://dev.fingerprint.com/docs/native-android-integration#response-format | extended format}
     *
     * @param tags is a customer-provided value or an object that will be saved together with the analysis event and will be returned back to you in a webhook message or when you search for the visit in the server API. {@link https://dev.fingerprint.com/docs/js-agent#tag | more info in the documentation page}
     * @param linkedId is a way of linking current analysis event with a custom identifier. This will allow you to filter visit information when using the Server API {@link https://dev.fingerprint.com/docs/js-agent#linkedid | more info in the documentation page}
     * @param options is used to configure requests with different settings
     */
    getVisitorData(tags?: Tags, linkedId?: string, options?: RequestOptions): Promise<VisitorData>;
}

/**
 * Provides the FingerprintJsProContext to its child components.
 *
 * @example
 * ```jsx
 * <FingerprintJsProProvider
 *     apiKey: 'your-fpjs-public-api-key'
 *     requestOptions: { timeout: 5000 }  // Optional: Set a custom timeout in milliseconds
 * >
 *   <MyApp />
 * </FingerprintJsProProvider>
 * ```
 * @group Hooks approach
 */
declare function FingerprintJsProProvider({ children, ...fingerprintJsProAgentParams }: PropsWithChildren<FingerprintJsProAgentParams>): JSX.Element;

/**
 * Use the `useVisitorData` hook in your components to perform identification requests with the FingerprintJS API.
 *
 * @example
 * ```jsx
 * const {
 *   // Request state
 *   isLoading,
 *   // Error info
 *   error,
 *   // Visitor info
 *   data,
 *   // A method to be called to initiate request
 *   getData,
 * } = useVisitorData();
 * ```
 *
 * @group Hooks approach
 */
declare function useVisitorData(): VisitorQueryContext;

/**
 * Something was wrong while building URL for identification request
 *
 * @group Errors
 */
declare class InvalidUrlError extends Error {
    constructor(message: string);
}
/**
 * Something was wrong with params while building URL for identification request
 *
 * @group Errors
 */
declare class InvalidURLParamsError extends Error {
    constructor(message: string);
}
/**
 * Unknown API error
 *
 * @group Errors
 */
declare class ApiError extends Error {
    constructor(message: string);
}
/**
 * Token is missing in the request
 *
 * @group Errors
 */
declare class ApiKeyRequiredError extends Error {
    constructor(message: string);
}
/**
 * Wrong token
 *
 * @group Errors
 */
declare class ApiKeyNotFoundError extends Error {
    constructor(message: string);
}
/**
 * API token is outdated
 *
 * @group Errors
 */
declare class ApiKeyExpiredError extends Error {
    constructor(message: string);
}
/**
 * Wrong request format (content, parameters)
 *
 * @group Errors
 */
declare class RequestCannotBeParsedError extends Error {
    constructor(message: string);
}
/**
 * Request failed
 *
 * @group Errors
 */
declare class FailedError extends Error {
    constructor(message: string);
}
/**
 * Server timeout
 *
 * @group Errors
 */
declare class RequestTimeoutError extends Error {
    constructor(message: string);
}
/**
 * Request limit for token reached
 *
 * @group Errors
 */
declare class TooManyRequestError extends Error {
    constructor(message: string);
}
/**
 * Request Filtering deny origin
 *
 * @group Errors
 */
declare class OriginNotAvailableError extends Error {
    constructor(message: string);
}
/**
 * Request Filtering deny some headers
 *
 * @group Errors
 */
declare class HeaderRestrictedError extends Error {
    constructor(message: string);
}
/**
 * Request Filtering deny crawlers
 *
 * @group Errors
 */
declare class NotAvailableForCrawlBotsError extends Error {
    constructor(message: string);
}
/**
 * Request Filtering deny empty UA
 *
 * @group Errors
 */
declare class NotAvailableWithoutUAError extends Error {
    constructor(message: string);
}
/**
 * API key does not match the selected region
 *
 * @group Errors
 */
declare class WrongRegionError extends Error {
    constructor(message: string);
}
/**
 * Subscription is not active for the provided API key
 *
 * @group Errors
 */
declare class SubscriptionNotActiveError extends Error {
    constructor(message: string);
}
/**
 * Something wrong with used API version
 *
 * @group Errors
 */
declare class UnsupportedVersionError extends Error {
    constructor(message: string);
}
/**
 *
 *
 * @group Errors
 */
declare class InstallationMethodRestrictedError extends Error {
    constructor(message: string);
}
/**
 * Error while parsing the response
 *
 * @group Errors
 */
declare class ResponseCannotBeParsedError extends Error {
    constructor(message: string);
}
/**
 * Something wrong with network
 *
 * @group Errors
 */
declare class NetworkError extends Error {
    constructor(message: string);
}
/**
 * Error while parsing JSON response
 *
 * @group Errors
 */
declare class JsonParsingError extends Error {
    constructor(message: string);
}
/**
 * Bad response type
 *
 * @group Errors
 */
declare class InvalidResponseTypeError extends Error {
    constructor(message: string);
}
/**
 * Client-side timeout error
 *
 * @group Errors
 */
declare class ClientTimeoutError extends Error {
    constructor(message: string);
}
/**
 * Other error
 *
 * @group Errors
 */
declare class UnknownError extends Error {
    constructor(message: string);
}

export { ApiError, ApiKeyExpiredError, ApiKeyNotFoundError, ApiKeyRequiredError, ClientTimeoutError, type Confidence, type ExtendedVisitorData, FailedError, FingerprintJsProAgent, type FingerprintJsProAgentParams, FingerprintJsProProvider, HeaderRestrictedError, InstallationMethodRestrictedError, InvalidResponseTypeError, InvalidURLParamsError, InvalidUrlError, type IpLocation, JsonParsingError, NetworkError, NotAvailableForCrawlBotsError, NotAvailableWithoutUAError, OriginNotAvailableError, type Region, RequestCannotBeParsedError, type RequestOptions, RequestTimeoutError, ResponseCannotBeParsedError, type SeenAt, type ShortVisitorData, SubscriptionNotActiveError, type Tag, type Tags, TooManyRequestError, UnknownError, UnsupportedVersionError, type VisitorData, type VisitorQueryContext, WrongRegionError, useVisitorData };