faceping.aidocs
Preview: this page describes the FacePing SDK sandbox, which is launching soon.

.NET MAUI reference

Every public type in FacePing.Sdk.Maui: setup, enrolment, verification, the camera view and results.

Package: FacePing.Sdk.Maui (NuGet). Namespace: FacePing.Sdk.Maui. Android 7 (API 24) or later, iOS 15 or later.

Setup#

builder.UseFacePing(o =>
{
    o.SandboxKey = "fp_test_…";                 // sandbox: faces enrolled on the device
    // o.DeviceToken = "fpd_…";                 // production: faces synced from your group or event
    // o.ApiBaseUrl = new("https://api-eu.faceping.ai/");
});

FacePingOptions#

Property Type Default Notes
SandboxKey string? null A fp_test_ key from Developers → Sandbox keys.
DeviceToken string? null Production. A fpd_ token for one group or event. Set this or SandboxKey, not both.
ApiBaseUrl Uri https://api-eu.faceping.ai/ Your account's region.
AutoSyncInterval TimeSpan? 5 minutes Production only. null turns automatic sync off; call SyncAsync yourself.
GatePolicy GatePolicy GatePolicy.Default How strict verification is. Change only if you know why.

UseFacePing registers IFacePing as a singleton. Ask for it in a constructor, or use FacePing.Current where there's no dependency injection.

IFacePing#

public interface IFacePing
{
    bool IsSandbox { get; }
    IReadOnlyCollection<string> EnrolledIds { get; }

    Task<EnrolResult> EnrolAsync(string id, FaceImage photo, CancellationToken ct = default);
    Task<VerifyResult> VerifyLiveAsync(string id, FaceCameraView camera, CancellationToken ct = default);
    Task<VerifyResult> VerifyAsync(string id, FaceImage photo, CancellationToken ct = default);

    Task<bool> ForgetAsync(string id);
    Task ForgetAllAsync();

    Task<SyncResult> SyncAsync(CancellationToken ct = default);   // production
    event EventHandler<SyncResult>? Synced;                         // production
}
Method Notes
EnrolAsync Sandbox only. Production enrolment happens with consent on your server or through the FacePing widget. Replaces any face already stored under id.
VerifyLiveAsync Runs a live attempt on the camera's frames: match, head turn, match again. Shows prompts in the FaceCameraView. Times out after 10 seconds with NoFace or the last failure.
VerifyAsync One photo, passive liveness only.
ForgetAsync / ForgetAllAsync Deletes stored faces from the device straight away.
SyncAsync Production. Downloads the latest faces for the device's group or event. A revoked device wipes its faces.

FaceImage#

What you can pass as a photo. Converts implicitly from each of these:

From Example
byte[] (JPEG or PNG) await faceping.EnrolAsync("me", bytes)
Stream await faceping.EnrolAsync("me", stream)
FileResult (from MediaPicker) await faceping.EnrolAsync("me", await MediaPicker.CapturePhotoAsync())
FaceCameraView capture await faceping.EnrolAsync("me", await Camera.CaptureAsync())

Large photos are scaled down to 1280 pixels on the device before anything else happens.

FaceCameraView#

A front-camera view with a face guide and the liveness prompts ("Turn your head left", "Look back at the camera").

<fp:FaceCameraView x:Name="Camera" HeightRequest="420" />
Member Notes
Task<FaceImage> CaptureAsync() Takes a still from the live view.
bool ShowGuide The face outline. Default true.
string? Prompt Set by VerifyLiveAsync; bind to it if you draw your own prompts.

Camera permission is requested the first time the view appears.

Results#

public record EnrolResult(EnrolOutcome Outcome, string Id);

public enum EnrolOutcome
{
    Enrolled, NoFace, MultipleFaces, FaceTooSmall, NotLive, LimitReached
}

public record VerifyResult(
    VerifyOutcome Outcome,
    double Similarity,
    double? LivenessScore,
    TimeSpan Elapsed,
    bool IsSandbox);

public enum VerifyOutcome
{
    Match, NoMatch, NotEnrolled, NoFace, LivenessFailed, ChallengeFailed, Expired, LeaseExpired
}

LimitReached means the sandbox already holds 25 faces on this device: forget one first. LeaseExpired (production) means the device hasn't synced for longer than its lease, 24 hours by default; it needs a connection before it verifies again.

Exceptions#

Exception When
FacePingSetupException The key or token is missing, invalid or revoked, or the sandbox key couldn't be activated (no connection on first run). The message says which.
FacePingModelException The face models couldn't load on this device. Send people to your normal entry.

Everything else is a result, not an exception: a face check never throws because someone looked away.