@deepvue-tech/fp-react-native

Deepvue mobile fingerprinting SDK for React Native and Expo with backend-native mobile_v1_1 support.

What this SDK does

• Collects runtime/device/network/battery signals.
• Derives local visitor_id and device_fingerprint_id.
• Computes fingerprint_confidence and risk hints.
• Sends collect payloads to backend with retries, timeout, and signature headers.
• Sends mobile_v1_1 payloads by default; supports explicit legacy mode.
• Exposes optional backend response metadata in collect() output.

Backend endpoints

• Health check: GET /health
• Collect fingerprint: POST /api/v1/collect
• Public key (future encrypted flow): GET /public-key

Base URL example:

https://your-backend.example.com

Install

Install SDK:

npm install @deepvue-tech/fp-react-native

For Expo prebuild/dev-client native auto-wiring, add the SDK plugin in app config:

{
  "expo": {
    "plugins": ["@deepvue-tech/fp-react-native"]
  }
}

Quick start

import DeepvueFP from '@deepvue-tech/fp-react-native';

DeepvueFP.config({
  collectUrl: 'https://your-backend.example.com/api/v1/collect',
  apiKey: 'YOUR_API_KEY',
  autoSend: true,
  debug: true, // logs outbound payload and response summary

  // v1.1 backend defaults
  apiKeyHeader: 'X-API-Key',
  schemaVersion: 'mobile_v1_1',
  channel: 'mobile',
  identityScope: 'device_linked',
  appVariant: __DEV__ ? 'debug' : 'release',
  payloadSigned: false,

  // existing controls
  strictMode: false,
  normalizeMode: true,
  requestTimeoutMs: 8000,
  maxRetries: 3,
  baseRetryDelayMs: 500,
});

const result = await DeepvueFP.collect();

console.log(result.visitor_id); // local canonical ID
console.log(result.device_fingerprint_id);
console.log(result.collection);
console.log(result.backend); // optional server metadata on successful send

Authentication headers

POST /api/v1/collect requires API key auth.

Required header:

• X-API-Key: <your_api_key> (configurable via apiKeyHeader)

Sent by SDK:

• Content-Type: application/json
• X-SDK-Version: 1.1.0
• X-Timestamp, X-Nonce, X-Signature, X-Payload-Signed

Payload behavior

Default (mobile_v1_1)

SDK now sends payloads with:

• schema_version, channel, identity_scope
• timing.collect_started_at_ms, timing.collect_finished_at_ms, timing.collection_time_ms
• hashes.stable_hash_v2, hashes.core_hash_v1, hashes.entropy_hash_v1, hashes.hash_inputs_version
• build_context
• transport
• signals, risk_hints, collection, meta

timing.collection_time_ms is always at least 1 ms.

Legacy fallback

Set schemaVersion: 'legacy' to send the previous payload shape (the raw SignalsResult payload).

mobile_vNext (opt-in)

Set schemaVersion: 'mobile_vNext' to include:

• Extended signal groups: hardware, runtime, integrity, environment, storage_anomaly
• Per-field signal provenance at signals.attribute_provenance
• Backend metadata counters in meta.attribute_coverage
• Native availability parity map in meta.native_signal_parity

API reference

DeepvueFP.config(options)

Updates runtime config. Non-sensitive fields are persisted. apiKey, idSalt, and signingKey remain memory-only.

DeepvueFP.collect(overrides?)

Collects signals, computes IDs/risk/confidence, stores history, and optionally sends to backend.

On successful send, collect() appends:

backend?: {
  request_id?: string;
  status: number;
  response?: CollectResponse;
  matched_on?: string;
  needs_secondary_verification?: boolean;
  risk_level?: string;
  bot_score?: number;
  error?: string | null;
}

DeepvueFP.send(signals)

Manually sends a previously collected payload using configured schema mode.

Config options

| Option | Type | Default | Notes | | --- | --- | --- | --- | | collectUrl | string | https://sidc.deepvue.ai/api/v1/collect | Collection endpoint | | apiKey | string | '' | Required for sending | | apiKeyHeader | string | X-API-Key | Backend API key header name | | schemaVersion | 'mobile_v1_1' \| 'mobile_vNext' \| 'legacy' | mobile_v1_1 | Payload mode | | channel | 'mobile' | mobile | Payload channel | | identityScope | 'device_linked' | device_linked | Payload identity scope | | appVariant | 'debug' \| 'release' | runtime (__DEV__) | Build context flag | | payloadSigned | boolean | false | Transport payload_signed + header value | | autoSend | boolean | false | Send after collect() | | strictMode | boolean | false | Includes integrity subset in ID seed | | normalizeMode | boolean | true | Normalizes/buckets stable signals | | idSalt | string | '' | Salt used for ID derivation | | signingKey | string | '' | Request-signature key | | requestTimeoutMs | number | 8000 | Min enforced: 1000 | | maxRetries | number | 3 | Min enforced: 0 | | baseRetryDelayMs | number | 500 | Min enforced: 100 | | debug | boolean | false | Enable verbose SDK logs including outbound payload metadata |

Migration: 1.0.0 -> 1.1.0

1. Deploy backend with mobile_v1_1 support (backward compatible).
2. Upgrade SDK to 1.1.0.
3. Keep default schemaVersion: 'mobile_v1_1'.
4. Monitor backend metrics (automation false positives, collisions, secondary verification).
5. Use schemaVersion: 'legacy' only for temporary rollback/compatibility.

cURL parity check (plaintext)

curl -X POST "https://your-backend.example.com/api/v1/collect" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your-api-key>" \
  -H "X-SDK-Version: 1.1.0" \
  -d '{
    "schema_version":"mobile_v1_1",
    "channel":"mobile",
    "identity_scope":"device_linked",
    "sdk":{"platform":"android","version":"3.0.1"},
    "timing":{"collect_started_at_ms":1772530000000,"collect_finished_at_ms":1772530000123,"collection_time_ms":123},
    "hashes":{"stable_hash_v2":"st_v2_x","core_hash_v1":"core_v1_x","entropy_hash_v1":"ent_v1_x","hash_inputs_version":"v1"},
    "signals":{"os_name":"android","os_version":"36","device_model":"SM-S711B"},
    "risk_hints":{"is_debugger_attached":true},
    "build_context":{"is_dev_build":true,"is_debugger_attached_runtime":true,"app_variant":"debug"},
    "transport":{"payload_signed":false,"signature_version":"v1","nonce":"n1","timestamp_iso":"2026-03-03T10:15:00.123Z"}
  }'

Notes

• Encryption flow via GET /public-key is not implemented in this release.
• In debug mode, risk hints can include debugger-related signals.
• If native module injection is unavailable (e.g., Expo Go or plugin not applied), SDK automatically falls back to JS-only collection and WebCrypto attestation fallback.

Native signal parity

| Field | Parity | | --- | --- | | integrity.play_integrity_available | android_only | | integrity.app_attest_available | ios_only | | integrity.native_signal_bridge_available | both | | integrity.native_attestation_available | both | | integrity.native_hostile_detection_available | both | | runtime.execution_environment | both | | native.collectAdvancedSignals | expo_go_unavailable |

Native scaffold files are included in the SDK under native/ and Expo prebuild wiring is handled by the SDK config plugin.