Avalonia reference

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

Package: FacePing.Sdk.Avalonia (NuGet, preview). Starter app: faceping/avalonia-starter. Avalonia 12 and .NET 10. Android 7 (API 24) or later on 64-bit phones, iOS 15 or later.

Namespaces: FacePing.Sdk.Avalonia for setup, IFacePing, FaceImage and FaceCameraView; FacePing.Sdk for results and exceptions, the same on every platform. With implicit usings on, the package adds using FacePing.Sdk for you.

Install#

Add the package to your shared project (your views) and to the Android and iOS projects:

dotnet add FaceCheck package FacePing.Sdk.Avalonia --prerelease
dotnet add FaceCheck.Android package FacePing.Sdk.Avalonia --prerelease
dotnet add FaceCheck.iOS package FacePing.Sdk.Avalonia --prerelease

The shared project compiles against the same API, and each platform project brings the real thing: the native core, the face models and the camera. On desktop and in the browser your app still builds, but face checks throw FacePingModelException: FacePing runs on Android and iOS devices.

The Android project needs <RuntimeIdentifiers>android-arm64;android-x64</RuntimeIdentifiers> (FacePing runs on 64-bit phones and x86_64 emulators) and <SupportedOSPlatformVersion>24</SupportedOSPlatformVersion>. The iOS project needs <SupportedOSPlatformVersion>15.0</SupportedOSPlatformVersion>.

Setup#

In CustomizeAppBuilder, in Android's Application and in iOS's AppDelegate:

builder.UseFacePing(o =>
{
    o.SandboxKey = "fp_test_…";                 // sandbox: faces enrolled on the device
    // o.DeviceToken = "fpd_…";                 // production: faces synced from your list
    // o.Region = FacePingRegion.EU;          // your account's region (the default)
});

FacePingOptions#

UseFacePing sets FacePing up once and starts loading the face models in the background. Then use IFacePing.Current anywhere, or register it in your own container.

Setting neither SandboxKey nor DeviceToken, or both, throws FacePingSetupException when the app starts.

IFacePing#

public interface IFacePing
{
    static IFacePing Current { get; }   // the app's FacePing, once UseFacePing has run

    bool IsSandbox { get; }
    IReadOnlyCollection<string> EnrolledIds { get; }

    Task<EnrollResult> EnrollAsync(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);   // sandbox: activate the key; production: fetch faces
    event EventHandler<SyncResult>? Synced;                         // production
}

FaceImage#

What you can pass as a photo. Bytes and streams convert implicitly; use FaceImage.FromFile for a storage file.

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

FaceCameraView#

A front-camera control with a face guide and the liveness prompts ("Turn your head left", "Look back at the camera"). FacePing runs the camera itself (CameraX on Android, AVFoundation on iOS) and draws the picture in Avalonia, so the control sits in your layout like any other: rounded corners, clipping and overlays all work.

<!-- xmlns:fp="using:FacePing.Sdk.Avalonia" -->
<fp:FaceCameraView x:Name="Camera" Height="420" />

The camera starts when the control appears and stops when it leaves the screen. Camera permission is requested the first time: the package declares Android's camera permission, and your iOS project's Info.plist needs NSCameraUsageDescription.

Results#

public record EnrollResult(EnrollOutcome Outcome, string Id)
{
    public bool IsEnrolled { get; }   // Outcome == Enrolled
}

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

public record VerifyResult(
    VerifyOutcome Outcome,
    double Similarity,
    double? LivenessScore,
    TimeSpan Elapsed,
    bool IsSandbox)
{
    public bool IsMatch { get; }   // Outcome == Match
}

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

public record SyncResult(
    SyncStatus Status,                  // Ok, Gone, Revoked or Unavailable
    int Enrolled,
    DateTimeOffset? LeaseUntil,         // production: verifies offline until then
    DateTimeOffset? DeleteAfter);

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.

EnrollmentPhoto#

For server-side enrolment: shrinks a camera photo before your app uploads it to your server. FacePing works at 1280 px, so a 12 MP original only costs upload time; this makes about 1.4 MB into 0.2 to 0.3 MB with the same result, and applies the photo's EXIF orientation. It runs in the FacePing core, with the same decoder as the server.

public static class EnrollmentPhoto            // namespace FacePing.Sdk
{
    public const int DefaultQuality = 90;

    // A JPEG, upright, longest side at most 1280 px. Throws ArgumentException if the photo isn't a JPEG or PNG.
    public static byte[] Prepare(byte[] photo, int quality = DefaultQuality);
}

Exceptions#

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