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 that matches the legacy SGFPM_* signatures. Android ships a Java JSGFPLib class with the same lifecycle. Each wrapper is a thin client that forwards calls to the local Connect Bridge over HTTP.

Available wrappers

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).

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) sets the wrapper to use a non-default host, for example an HTTPS LAN / kiosk bridge. Both http and https URLs are accepted.
• Session: the wrapper gets and refreshes a short-lived bearer token through POST /v1/session/start automatically. 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. This means SGFPM_CreateTemplate reuses the capture response instead of making a separate extract call.

Not served by the current bridge: WSQ

SGFPM_EncodeWSQ / SGFPM_DecodeWSQ (and the Android WSQEncode / WSQDecode) remain in the API for source compatibility. However, the restructured bridge has no /v1/wsq/* route. The capture call returns only raw8 / png image bytes. These calls receive an HTTP 404/501 and return SGFDX_ERROR_NO_LONGER_SUPPORTED. The functions are kept on purpose (not removed) so existing code compiles without changes. They will start working automatically if a future Connect Bridge version adds WSQ again.

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 includes a network-security-config that is limited to 127.0.0.1 / localhost only. It is not an app-wide android:usesCleartextTraffic="true" setting. The library manifest's <application> references it.
• Manifest-merger caveat: if an app that uses the library declares its own networkSecurityConfig, it overrides the library's config. The merger cannot combine two competing configs. Such apps must add a 127.0.0.1 cleartext rule themselves.
• If you point SetBridgeBaseURL() at an https LAN host, you avoid 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 that 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 and match scenario before rollout to real devices.

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 Connect Bridge and confirm that you get SGFDX_ERROR_INITIALIZE_FAILED. Disconnect the device and confirm that you get 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.

Same lifecycle as FDx SDK Pro

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.