Native SDK Wrapper Guide

The native wrappers let existing FDx SDK Pro applications target SecuGen Connect with minimal code change. Linux, macOS, and Windows ship a shared C API matching the legacy SGFPM_* signatures; Android ships a Java JSGFPLib class with the same lifecycle. Each wrapper is a thin client that forwards to the local Connect bridge over HTTP.

The wrapper family

The Linux, macOS, and Windows wrappers compile from a byte-identical shared C source tree (src/sgfplib.c); only the build system and packaging differ per platform (Makefile on Linux/macOS, CMake / build.bat on Windows). The browser/TypeScript wrapper (sdk-webapi-connect) is covered separately in the WebAPI Migration Guide.

Transport

• Default base URL: http://127.0.0.1:4499 — plain HTTP on loopback. Mainstream installs do not require a Local-CA cert.
• Override: SGFPM_Connect_SetBridgeBaseURL() (C) / SetBridgeBaseURL() (Java) repoints the wrapper at a non-default host — for example an HTTPS LAN / kiosk bridge. Both http and https URLs are accepted.
• Session: the wrapper obtains and refreshes a short-lived bearer token via POST /v1/session/start transparently — callers never handle the token.

Endpoint mapping

The wrappers call the bridge's standard /v1 REST endpoints:

Capture and template creation are served by a single POST /v1/fingerprint/capture call — it returns both the image (when requested) and the extracted template, so SGFPM_CreateTemplate reuses the capture response rather than a separate extract round-trip.

Not served by the current bridge: WSQ

SGFPM_EncodeWSQ / SGFPM_DecodeWSQ (and the Android WSQEncode / WSQDecode) remain in the API for source compatibility, but the restructured bridge exposes no /v1/wsq/* route — capture returns raw8 / png image bytes only. These calls receive an HTTP 404/501 and return SGFDX_ERROR_NO_LONGER_SUPPORTED. The functions are deliberately kept (not removed) so existing code compiles unchanged, and they will begin working automatically if a future bridge re-introduces WSQ.

Error handling

HTTP / API failures are mapped to representative SGFDxErrorCode values.

Android specifics

The Android wrapper (SecuGen.FDxSDKPro.JSGFPLib) uses OkHttp and is otherwise API-compatible with the C lifecycle (Init, OpenDevice, GetImage, CreateTemplate, MatchTemplate, GetMatchingScore, …). Because the default transport is now cleartext HTTP to loopback, Android's network-security policy (API 28+) blocks it without an explicit opt-in:

• The AAR ships a network-security-config scoped to 127.0.0.1 / localhost only — not a blanket android:usesCleartextTraffic="true" — referenced from the library manifest's <application>.
• Manifest-merger caveat: a consuming app that declares its own networkSecurityConfig overrides the library's (the merger cannot combine two competing configs). Such apps must add a 127.0.0.1 cleartext rule themselves.
• Pointing SetBridgeBaseURL() at an https LAN host avoids the cleartext requirement entirely; the OkHttp client trusts the loopback / configured host for that override path.
• INTERNET permission is required (declared by the library manifest).

Migration strategy

1. Keep the existing flow: Create → Init → Open → Capture / CreateTemplate → Match → Close.
2. Confirm the Connect bridge is reachable at http://127.0.0.1:4499 (or your configured override URL).
3. For templates generated outside the wrapper, set the template format with SGFPM_SetTemplateFormat before matching.
4. Validate with one end-to-end capture + match scenario before real-device rollout.

Validation checklist

1. Bridge reachable at http://127.0.0.1:4499 (or the configured override) — GET /v1/health returns {"ok":true}.
2. SGFPM_Init returns SGFDX_ERROR_NONE.
3. SGFPM_EnumerateDevice returns at least one device.
4. Two captures produce a match score and a boolean match result.
5. Error path: stop the bridge and verify SGFDX_ERROR_INITIALIZE_FAILED; disconnect the device and verify SGFDX_ERROR_DEVICE_NOT_FOUND.
6. Android: confirm the loopback cleartext rule is active (capture succeeds on API 28+), or that an https override is configured.

Lifecycle parallelism

Every wrapper preserves the legacy FDx SDK Pro lifecycle — only the binding mechanism changes:

// Legacy FDx SDK Pro (native C)
HSGFPM h; SGFPM_Create(&h);
SGFPM_Init(h, SG_DEV_AUTO);
SGFPM_OpenDevice(h, 0);
SGFPM_GetImage(h, buf);
SGFPM_CreateTemplate(h, NULL, buf, tpl1);
// ... second capture ...
SGFPM_GetMatchingScore(h, tpl1, tpl2, &score);
SGFPM_CloseDevice(h);

// SecuGen Connect — same C API, bridge-backed (http://127.0.0.1:4499)
HSGFPM h; SGFPM_Create(&h);
SGFPM_Init(h, SG_DEV_AUTO);                 // → GET  /v1/health  (+ POST /v1/session/start transparently)
SGFPM_OpenDevice(h, 0);                     // → GET  /v1/info
SGFPM_GetImage(h, buf);                     // → POST /v1/fingerprint/capture
SGFPM_CreateTemplate(h, NULL, buf, tpl1);  // template returned by the same capture call
// ... second capture ...
SGFPM_GetMatchingScore(h, tpl1, tpl2, &score); // → POST /v1/match/score
SGFPM_CloseDevice(h);

Application code keeps the same call sequence, the same constants, and the same response semantics. The wrapper handles session lifecycle, authentication, transport (HTTP by default, HTTPS for a configured LAN host), and error-code translation internally.