Skip to content

Aziface: ๐Ÿ“ฑ React Native SDK adapter for Aziface biometric authentication - Face matching & document verification

License

Notifications You must be signed in to change notification settings

azifydev/aziface-mobile

Folders and files

NameName
Last commit message
Last commit date

Latest commit

ย 

History

92 Commits
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

@azify/aziface-mobile ๐Ÿ“ฑ

Note

This package supports only new architecture.

Version NPM Downloads Unpacked Size

Aziface SDK adapter to react native.

Summary


Installation

npm install @azify/aziface-mobile
# or
yarn add @azify/aziface-mobile

Only iOS:

cd ios && pod install && cd ..

Usage

import { useState } from 'react';
import { Text, TouchableOpacity, Platform, ScrollView } from 'react-native';
import {
  initialize,
  enroll,
  authenticate,
  liveness,
  photoMatch,
  photoScan,
  setLocale,
  FaceView,
  type Params,
  type Headers,
  type Processor,
  type Locale,
} from '@azify/aziface-mobile';

export default function App() {
  const [isInitialized, setIsInitialized] = useState(false);
  const [localization, setLocalization] = useState<Locale>('default');

  const opacity = isInitialized ? 1 : 0.5;

  const onInitialize = async () => {
    /*
     * The SDK must be initialized first
     * so that the rest of the library
     * functions can work!
     * */
    const headers: Headers = {
      'x-token-bearer': 'YOUR_X_TOKEN_BEARER',
      'x-api-key': 'YOUR_X_API_KEY',
      'clientInfo': 'YUOR_CLIENT_INFO',
      'contentType': 'YOUR_CONTENT_TYPE',
      'device': 'YOUR_DEVICE',
      'deviceid': 'YOUR_DEVICE_ID',
      'deviceip': 'YOUR_DEVICE_IP',
      'locale': 'YOUR_LOCALE',
      'xForwardedFor': 'YOUR_X_FORWARDED_FOR',
      'user-agent': 'YOUR_USER_AGENT',
      'x-only-raw-analysis': '1',
    };

    const params: Params = {
      isDevelopment: true,
      deviceKeyIdentifier: 'YOUR_DEVICE_KEY_IDENTIFIER',
      baseUrl: 'YOUR_BASE_URL',
    };

    try {
      const initialized = await initialize({
        params,
        headers,
      });

      setIsInitialized(initialized);
      console.log(initialized);
    } catch (error: any) {
      setIsInitialized(false);
      console.error(error);
    }
  };

  const onFaceScan = async (type: string, data?: any) => {
    try {
      let processor: Processor | null = null;

      switch (type) {
        case 'enroll':
          processor = await enroll(data);
          break;
        case 'liveness':
          processor = await liveness(data);
          break;
        case 'authenticate':
          processor = await authenticate(data);
          break;
        case 'photoMatch':
          processor = await photoMatch(data);
          break;
        case 'photoScan':
          processor = await photoScan(data);
          break;
        default:
          processor = false;
          break;
      }

      console.log(type, processor);
    } catch (error: any) {
      console.error(type, error.message);
    }
  };

  const onLocale = () => {
    const LOCALES: Locale[] = ['default', 'en', 'es', 'pt-BR'];
    const localeIndex = Math.floor(Math.random() * (LOCALES.length - 2));
    const value = LOCALES.filter((l) => l !== localization)[localeIndex]!;

    setLocalization(value);
    setLocale(value);
  };

  return (
    <ScrollView
      style={styles.scroll}
      contentContainerStyle={styles.scrollContent}
      showsVerticalScrollIndicator={false}
    >
      <FaceView
        style={styles.content}
        onInitialize={(event) => console.log('onInitialize', event)}
        onOpen={(event) => console.log('onOpen', event)}
        onClose={(event) => console.log('onClose', event)}
        onCancel={(event) => console.log('onCancel', event)}
        onError={(event) => console.log('onError', event)}
        onVocal={(event) => console.log('onVocal', event)}
      >
        <TouchableOpacity
          style={styles.button}
          activeOpacity={0.8}
          onPress={onInitialize}
        >
          <Text style={styles.buttonText}>Initialize SDK</Text>
        </TouchableOpacity>

        <TouchableOpacity
          style={[styles.button, { opacity }]}
          activeOpacity={0.8}
          onPress={() => onFaceScan('enroll')}
          disabled={!isInitialized}
        >
          <Text style={styles.buttonText}>Enrollment</Text>
        </TouchableOpacity>

        <TouchableOpacity
          style={[styles.button, { opacity }]}
          activeOpacity={0.8}
          onPress={() => onFaceScan('liveness')}
          disabled={!isInitialized}
        >
          <Text style={styles.buttonText}>Liveness</Text>
        </TouchableOpacity>

        <TouchableOpacity
          style={[styles.button, { opacity }]}
          activeOpacity={0.8}
          onPress={() => onFaceScan('authenticate')}
          disabled={!isInitialized}
        >
          <Text style={styles.buttonText}>Authenticate</Text>
        </TouchableOpacity>

        <TouchableOpacity
          style={[styles.button, { opacity }]}
          activeOpacity={0.8}
          onPress={() => onFaceScan('photoMatch')}
          disabled={!isInitialized}
        >
          <Text style={styles.buttonText}>Photo Match</Text>
        </TouchableOpacity>

        <TouchableOpacity
          style={[styles.button, { opacity }]}
          activeOpacity={0.8}
          onPress={() => onFaceScan('photoScan')}
          disabled={!isInitialized}
        >
          <Text style={styles.buttonText}>Photo Scan</Text>
        </TouchableOpacity>

        <TouchableOpacity
          style={[styles.button, { opacity }]}
          activeOpacity={0.8}
          onPress={() => onLocale()}
          disabled={!isInitialized}
        >
          <Text style={styles.buttonText}>Localization: {localization}</Text>
        </TouchableOpacity>
      </FaceView>
    </ScrollView>
  );
}

const styles = StyleSheet.create({
  scroll: {
    flex: 1,
    paddingTop: Platform.OS === 'ios' ? 40 : 0,
    backgroundColor: 'white',
  },
  scrollContent: {
    flexGrow: 1,
  },
  content: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    gap: 40,
    backgroundColor: 'white',
  },
  button: {
    width: '100%',
    justifyContent: 'center',
    alignItems: 'center',
    padding: 20,
    borderRadius: 16,
    backgroundColor: '#4a68b3',
  },
  buttonText: {
    fontSize,
    fontWeight: 'bold',
    color: 'white',
  },
});

API

Methods Return Type Platform
initialize Promise<boolean> All
enroll Promise<Processor> All
authenticate Promise<Processor> All
liveness Promise<Processor> All
photoMatch Promise<Processor> All
photoScan Promise<Processor> All
setLocale void All
vocal void All

initialize

The initialize of the Aziface SDK is the process of configuring and preparing the SDK for use before any face capture, liveness, authentication, or identity verification sessions can begin.

During initialization, the application provides the SDK with the required configuration data, such as the device key identifier, base URL, and x-token-bearer. The SDK validates these parameters, performs internal setup, and prepares the necessary resources for secure camera access, biometric processing, and user interface rendering.

A successful initialization confirms that the SDK is correctly licensed, properly configured for the target environment, and ready to start user sessions. If initialization fails due to invalid keys, network issues, or unsupported device conditions, the SDK returns boolean information (true or false) so the application can handle the failure gracefully and prevent session startup.

Initialization is a mandatory step and must be completed once during the application lifecycle (or as required by the platform) before invoking any Aziface SDK workflows.

const initialized = await initialize({
  params: {
    deviceKeyIdentifier: 'YOUR_DEVICE_KEY_IDENTIFIER',
    baseUrl: 'YOUR_BASE_URL',
  },
  headers: {
    'x-token-bearer': 'YOUR_TOKEN_BEARER',
    // your headers...
  },
});

console.log(initialized);

Properties

Initialize type Required
params Params โœ…
headers Headers โœ…

enroll

The enroll method in the Aziface SDK is responsible for registering a userโ€™s face for the first time and creating a secure biometric identity. During enrollment, the SDK guides the user through a liveness detection process to ensure that a real person is present and not a photo, video, or spoofing attempt.

While the user follows on-screen instructions (such as positioning their face within the oval and performing natural movements), the SDK captures a set of facial data and generates a secure face scan. This face scan is then encrypted and sent to the backend for processing and storage.

The result of a successful enrollment is a trusted biometric template associated with the userโ€™s identity, which can later be used for authentication, verification, or ongoing identity checks. If the enrollment fails due to poor lighting, incorrect positioning, or liveness issues, the SDK returns detailed status and error information so the application can handle retries or user feedback appropriately.

const result = await enroll();

console.log(result);

Properties

Property type Required Default
data any โŒ undefined

authenticate

The authentication method in the Aziface SDK is used to verify a userโ€™s identity by comparing a newly captured face scan against a previously enrolled biometric template. This process confirms that the person attempting to access the system is the same individual who completed the enrollment.

During authentication, the SDK performs an active liveness check while guiding the user through simple on-screen instructions. A fresh face scan is captured, encrypted, and securely transmitted to the backend, where it is matched against the stored enrollment data.

If the comparison is successful and the liveness checks pass, the authentication is approved and the user is granted access. If the process fails due to a mismatch, spoofing attempt, or poor capture conditions, the SDK returns detailed result and error codes so the application can handle denial, retries, or alternative verification flows.

const result = await authenticate();

console.log(result);

Properties

Property type Required Default
data any โŒ undefined

liveness

The liveness method in the Aziface SDK is designed to determine whether the face presented to the camera belongs to a real, live person at the time of capture, without necessarily verifying their identity against a stored template.

In this flow, the SDK guides the user through a short interaction to capture facial movements and depth cues that are difficult to replicate with photos, videos, or masks. The resulting face scan is encrypted and sent to the backend, where advanced liveness detection algorithms analyze it for signs of spoofing or fraud.

A successful liveness result confirms real human presence and can be used as a standalone security check or as part of broader workflows such as authentication, onboarding, or high-risk transactions. If the liveness check fails, the SDK provides detailed feedback to allow the application to respond appropriately.

const result = await liveness();

console.log(result);

Properties

Property type Required Default
data any โŒ undefined

photoMatch

The photoMatch method in the Aziface SDK is used to verify a userโ€™s identity by analyzing a government-issued identity document and comparing it with the userโ€™s live facial biometric data.

In this flow, the SDK first guides the user to capture high-quality images of their identity document. Then, a face scan is collected through a liveness-enabled facial capture. Both the document images and the face scan are encrypted and securely transmitted to the backend.

A successful result provides strong identity assurance, combining document authenticity and biometric verification. This flow is commonly used in regulated onboarding, KYC, and high-security access scenarios. If any step fails, the SDK returns detailed results and error information to support retries or alternative verification paths.

const result = await photoMatch();

console.log(result);

Properties

Property type Required Default
data any โŒ undefined

photoScan

The photoScan method in the Aziface SDK is used to verify the authenticity and validity of a government-issued identity document without performing facial biometric verification.

In this flow, the SDK guides the user to capture images of the identity document, ensuring proper framing, focus, and lighting. The captured document images are encrypted and securely sent to the backend for analysis.

A successful document-only verification is suitable for lower-risk scenarios or cases where biometric capture is not required. If the verification fails due to image quality issues, unsupported documents, or suspected tampering, the SDK provides detailed feedback for proper error handling and user guidance.

const result = await photoScan();

console.log(result);

Properties

Property type Required Default
data any โŒ undefined

setLocale

The setLocale method in the Aziface SDK is used to define the language and locale used by the SDKโ€™s user interface and vocal guidance during verification sessions.

By calling this method, the application specifies which language the SDK should use for on-screen text, voice prompts, and user instructions. This allows the SDK to present a localized experience that matches the userโ€™s preferred or device language.

The selected language applies to all Aziface SDK workflows, including enrollment, authentication, liveness checks, photo scan, and photo match verification. The language must be set before starting a session to ensure consistent localization throughout the user interaction.

If an unsupported or invalid language code is provided, the SDK falls back to a default language (en-US) and returns appropriate status or error information, depending on the platform implementation.

setLocale('en');

Properties

Property type Required
locale Locale โœ…

vocal

The Vocal Guidance feature in the Aziface SDK provides spoken, real-time instructions to guide users through face capture, liveness, authentication, and identity verification flows.

During a session, the SDK uses voice prompts to instruct the user on what to do next, such as positioning their face within the camera frame, moving closer or farther, or maintaining proper alignment. This auditory guidance complements on-screen visual cues, helping users complete the process more easily and with fewer errors.

vocal();

Enums

Enums Platform
Errors All

Types

Types Platform
Params All
Headers All
Processor All
ProcessorData All
ProcessorError All
ProcessorAdditionalSessionData All
ProcessorResult All
ProcessorHttpCallInfo All
ProcessorRequestMethod All
ProcessorIDScanResultsSoFar All
Locale All

Params

Here must be passed to initialize the Aziface SDK! Case the parameters isn't provided the Aziface SDK goes to be not initialized.

Params type Required Default
deviceKeyIdentifier string โœ… -
baseUrl string โœ… -
isDevelopment boolean โŒ false

Headers

Here you can add your headers to send request when some method is called. Only values from type string, null or undefined are accepts!

Headers type Required Default
x-token-bearer string โœ… -
[key: string] string or null or undefined โŒ undefined

Processor

A processor always return this properties.

Processor type Description
isSuccess boolean Indicates if the processing was successful.
data ProcessorData or null or undefined The processor data response.
error ProcessorError or null or undefined The processor error response.

ProcessorData

This is data response processor. Each processor can give different responses.

ProcessorData type Description
idScanSessionId string or null or undefined The unique identifier for the ID scan session.
externalDatabaseRefID string or null or undefined The unique identifier for the face session.
additionalSessionData ProcessorAdditionalSessionData The additional session data.
result ProcessorResult or null or undefined The result of the processing.
responseBlob string The raw response blob from the server.
httpCallInfo ProcessorHttpCallInfo or null or undefined The HTTP call information.
didError boolean Indicates if an error occurred during processing.
serverInfo unknown or null or undefined The server information.
idScanResultsSoFar ProcessorIDScanResultsSoFar or or null or undefined The ID scan results so far.

ProcessorError

This is error response processor.

ProcessorError type Description
code Errors The error code.
message string The error message.
ProcessorAdditionalSessionData

The additional session data are extra information about device and processor.

ProcessorAdditionalSessionData type Description
platform string The platform of the device.
appID string The application ID.
installationID string The installation ID.
deviceModel string The device model.
deviceSDKVersion string The device SDK version.
userAgent string The user agent.
sessionID string The session ID.
ProcessorResult

The result object of the face or scan analyze.

ProcessorResult type Description
livenessProven boolean Indicates if it's liveness proven.
auditTrailImage string The audit trail image in base64 format.
ageV2GroupEnumInt number The age group enumeration integer.
matchLevel number or undefined The match level.
ProcessorHttpCallInfo

The HTTP information of the processor request.

ProcessorHttpCallInfo type Description
tid string The transaction ID.
path string The request path.
date string The date of the request.
epochSecond number The epoch second of the request.
requestMethod ProcessorRequestMethod The request method.
ProcessorRequestMethod

The request method of the processor.

ProcessorRequestMethod Description
GET GET request.
POST POST request.
ProcessorIDScanResultsSoFar

The processor scan result. It's shown when you use photoScan or photoMatch.

ProcessorIDScanResultsSoFar Type Description
photoIDNextStepEnumInt number The photo ID next step enumeration integer.
fullIDStatusEnumInt number The full ID status enumeration integer.
faceOnDocumentStatusEnumInt number The face on document status enumeration integer.
textOnDocumentStatusEnumInt number The text on document status enumeration integer.
expectedMediaStatusEnumInt number The expected media status enumeration integer.
unexpectedMediaEncounteredAtLeastOnce boolean Indicates if unexpected media was encountered at least once.
documentData string The document data in stringified JSON format.
nfcStatusEnumInt number The NFC status enumeration integer.
nfcAuthenticationStatusEnumInt number The NFC authentication status enumeration integer.
barcodeStatusEnumInt number The barcode status enumeration integer.
mrzStatusEnumInt number The MRZ status enumeration integer.
idFoundWithoutQualityIssueDetected boolean Indicates if the ID was found without quality issues.
idFacePhotoFoundWithoutQualityIssueDetected boolean Indicates if the face photo was found without quality issues.
idScanAgeV2GroupEnumInt number The ID scan age group enumeration integer.
didMatchIDScanToOCRTemplate boolean Indicates if the ID scan matched the OCR template.
isUniversalIDMode boolean Indicates if the universal ID mode is enabled.
matchLevel number The match level.
matchLevelNFCToFaceMap number The match level NFC to face map.
faceMapAgeV2GroupEnumInt number The face map age group enumeration integer.
watermarkAndHologramStatusEnumInt number The watermark and hologram status enumeration integer.

Locale

The Locale type use the ISO 639 language codes pattern.

type Description Platform
af Afrikaans language. All
ar Arabic language. All
de German language. All
default English language. All
en English language. All
el Greek language. All
es Spanish and Castilian language. All
fr French language. All
ja Japanese language. All
kk Kazakh language. All
nb Norwegian Bokmรฅl language. All
pt-BR Portuguese Brazilian language. All
ru Russian language. All
vi Vietnamese language. All
zh Chinese language. All

Errors

Errors Description Platform
NotInitialized When trying to initialize a process, but SDK wasn't initialized. All
ConfigNotProvided When deviceKeyIdentifier and baseUrl aren't provided. All
ParamsNotProvided When parameters aren't provided, this case, it is null. All
NotAuthenticated When authenticate process is called, but enroll wasn't done first. All
NotFoundTargetView When Activity (Android) or ViewController (iOS) aren't found on call processor. All
CameraError When an error on use the camera occurs. All
CameraPermissionsDenied When the user doesn't permit the use camera. All
UserCancelledIdScan When process was cancelled on ID scan. All
UserCancelledFaceScan When process was cancelled on face scan. All
RequestAborted When process has request aborted. Some error in JSON or network. All
LockedOut When process is locked out. All
UnknownInternalError When process has unknown internal error. All

Components

FaceView

The FaceView extends all properties of the View, but it has five new callbacks to listener Aziface SDK events.

Properties

Property Description Returns Platform
onOpen Callback function called when the Aziface SDK is opened. boolean All
onClose Callback function called when the Aziface SDK is closed. boolean All
onCancel Callback function called when the Aziface SDK is cancelled. boolean All
onError Callback function called when an error occurs in the Aziface SDK. boolean All
onVocal Callback function called when the vocal guidance is activated. boolean All
onInitialize Callback function called when the Aziface SDK is initialized. boolean All

Dynamic Strings

The setDynamicStrings method in the Aziface SDK allows applications to dynamically customize and override the text strings displayed in the SDKโ€™s user interface during verification sessions.

This method enables the application to replace default UI messages such as instructions, error messages, button labels, and guidance text with custom strings at runtime. It is commonly used to adapt wording, terminology, or tone to better align with product language, branding, regulatory requirements, or user context.

The dynamic strings defined through this method apply across Aziface SDK workflows, including enrollment, authentication, liveness checks, photo scan, and photo match verification. To ensure consistency, setDynamicStrings should be called before starting a session so that all UI elements display the customized text.

If a provided string key is invalid or missing, the SDK falls back to its default text for that element. This ensures that the user experience remains functional even if some custom strings are not defined.

We separated another documentation about the dynamic strings, see more here!


Theme

The Aziface SDK provides the ability to change the theme of each flow. We separated another documentation about the theme, see more here!


Vocal Guidance

The Aziface SDK provides the vocal method for you on vocal guidance. We recommend using it the SDK is initialized. The vocal method will always return false when the device is muted.

Note: We recommend to use the FaceView component for control vocal guidance state with efficiently.

import { useState } from 'react';
import { Button } from 'react-native';
// ...
import { initialize, vocal, type Params } from '@azify/aziface-mobile';

export default function App() {
  const [isInitialized, setIsInitialized] = useState(false);
  // State to manager when vocal is enabled
  const [isVocalEnabled, setIsVocalEnabled] = useState(false);

  function onInitialize() {
    const params: Params = {
      isDevelopment: true,
      deviceKeyIdentifier: 'YOUR_DEVICE_KEY_IDENTIFIER',
      baseUrl: 'YOUR_BASE_URL',
    };

    try {
      const initialized = await initialize({ params });
      setIsInitialized(initialized);
    } catch {
      setIsInitialized(false);
    } finally {
      setIsVocalEnabled(false);
    }
  }

  // Call onVocal function when SDK is initialized!
  function onVocal(enabled: boolean) {
    setIsVocalEnabled(enabled);
  }

  return (
    <FaceView onVocal={onVocal}>
      {/* ... */}

      <Button
        title={isVocalEnabled ? 'Vocal ON' : 'Vocal OFF'}
        onPress={vocal}
      />
    </FaceView>
  );
}

Enabling Camera (iOS only)

If you want to enable the camera, you need to add the following instructions in your Info.plist file:

<key>NSCameraUsageDescription</key>
<string>$(PRODUCT_NAME) need access to your camera to take picture.</string>

That's will be necessary to what iOS works correctly!


Integration guide

The Azify offers an example App for Flutter developers. Currently, this example App has full implementation in Android apps. Now, in iOS apps it's still in progress. Check that's the documentation here.


Expo

In Expo, you need to convert to a custom development build or use prebuild. You can use also React Native without Expo. Check Expo example App here.


Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.


License

MIT License. ๐Ÿ™‚


Made with create-react-native-library. ๐Ÿ˜Š

About

Aziface: ๐Ÿ“ฑ React Native SDK adapter for Aziface biometric authentication - Face matching & document verification

Resources

License

Code of conduct

Contributing

Stars

Watchers

Forks

Packages

No packages published

Contributors 3

  •  
  •  
  •