Skip to content

Integration with Face SDK

Integration of the Face API with the Document Reader SDK enables automatic face matching and search using a portrait. The portrait can be extracted from the document Visual Zone or RFID chip, a submitted selfie, or a facial image captured during a liveness transaction.

How to Enable

To enable the integration with the Face SDK, set useFaceApi to true:

DocReader.shared.processParams.useFaceApi = true

[RGLDocReader shared].processParams.useFaceApi = @YES;

DocumentReader.Instance().processParams().useFaceApi = true

DocumentReader.Instance().processParams().useFaceApi = true;

DocumentReader.instance.processParams.useFaceApi = true;

DocumentReader.instance.processParams.useFaceApi = true

var params = new ProcessParams()
params.useFaceApi = true
DocumentReader.setProcessParams(params, _ => { }, _ => { })

var params = new ProcessParams()
params.useFaceApi = true
DocumentReader.setProcessParams(params)

var params = new ProcessParams()
params.useFaceApi = true
DocumentReader.setProcessParams(params, function (m) { }, function (e) { })

// Android
DocumentReader.Instance().ProcessParams().UseFaceApi = (Java.Lang.Boolean)true;

// iOS
RGLDocReader.Shared.ProcessParams.UseFaceApi = true;

After you enable the integration, the Face SDK uses the default configuration. To change the configuration, see Configure Parameters.

One-Shot Identification

One-Shot Identification mode recognizes the document, extracts portraits from the document and a live photo, and compares the portraits. This mode simplifies integration with the Document Reader SDK and the Face SDK.

One-Shot Identification works only in single-frame processing mode, not during live video capture.

To enable One-Shot Identification mode, use these examples:

To enable One-Shot Identification mode, set oneShotIdentification to true in the recognition configuration:

let config = DocReader.RecognizeConfig(images: images)
config.scenario = RGL_SCENARIO_FULL_PROCESS
config.oneShotIdentification = true

RGLRecognizeConfig *config = [[RGLRecognizeConfig alloc] initWithImages:images];
config.scenario = RGL_SCENARIO_FULL_PROCESS;
config.oneShotIdentification = YES;

val recognizeConfig = RecognizeConfig.Builder(Scenario.SCENARIO_FULL_PROCESS).setBitmaps(bitmaps).setOneShotIdentification(true).build()

RecognizeConfig recognizeConfig = new RecognizeConfig.Builder(Scenario.SCENARIO_FULL_PROCESS).setBitmaps(bitmaps).setOneShotIdentification(true).build();

var config = RecognizeConfig.withScenario(
  Scenario.FULL_PROCESS,
  image: image,
  oneShotIdentification: true,
);

var config = RecognizeConfig.withScenario(
  Scenario.FULL_PROCESS, {
  image: image,
  oneShotIdentification: true,
});

var config = new RecognizeConfig()
config.scenario = ScenarioIdentifier.SCENARIO_FULL_PROCESS
config.image = image
config.oneShotIdentification = true

var config = new RecognizeConfig()
config.scenario = ScenarioIdentifier.SCENARIO_FULL_PROCESS
config.image = image
config.oneShotIdentification = true

var config = new RecognizeConfig()
config.scenario = ScenarioIdentifier.SCENARIO_FULL_PROCESS
config.image = image
config.oneShotIdentification = true

// Android
var config = new RecognizeConfig.Builder(Scenario.ScenarioFullProcess)
    .SetBitmap(bitmap)
    .SetOneShotIdentification(true)
    .Build();

// iOS
var config = new RGLRecognizeConfig(image);
config.Scenario = Constants.RGL_SCENARIO_FULL_PROCESS;
config.OneShotIdentification = true;

Select the image from Gallery or Files and process it.

External and Live Portraits

When Face SDK integration is enabled, you can add an external portrait, a live portrait, or both for face matching and search:

  • External is a portrait from a gallery, database, or another source.
  • Live is a portrait captured with a mobile device camera.

You can also use the facial image captured during a Face SDK liveness transaction. To use it for face matching, set the livenessTransactionId property in FaceApiParams.

Note

If both livePortrait and livenessTransactionId are specified, livenessTransactionId takes priority. The livePortrait image is ignored and is not sent to the Face API.

Add portraits when you create the configuration object and before you start document processing.

The examples below create a RecognizeConfig object for a document image selected from the gallery. Because the configuration object requires a processing scenario, the examples use the Full Processing scenario.

let config = DocReader.RecognizeConfig(images: images)
config.scenario = RGL_SCENARIO_FULL_PROCESS
config.extPortrait = UIImage(named: "external-portrait")
config.livePortrait = UIImage(named: "live-portrait")

RGLRecognizeConfig *config = [[RGLRecognizeConfig alloc] initWithImages:images];
config.scenario = RGL_SCENARIO_FULL_PROCESS;
config.extPortrait = [UIImage imageNamed:@"external-portrait"];
config.livePortrait = [UIImage imageNamed:@"live-portrait"];

val externalPortrait = BitmapFactory.decodeResource(context.resources,
                                       R.drawable.external_portrait)
val livePortrait = BitmapFactory.decodeResource(context.resources,
                                       R.drawable.live_portrait)
val config = RecognizeConfig.Builder(Scenario.SCENARIO_FULL_PROCESS)
    .setBitmaps(bitmaps)
    .setExtPortrait(externalPortrait)
    .setLivePortrait(livePortrait)
    .build()

Bitmap externalPortrait = BitmapFactory.decodeResource(context.getResources(),
                                       R.drawable.external_portrait);
Bitmap livePortrait = BitmapFactory.decodeResource(context.getResources(),
                                       R.drawable.live_portrait);
RecognizeConfig config = new RecognizeConfig.Builder(Scenario.SCENARIO_FULL_PROCESS)
        .setBitmaps(bitmaps)
        .setExtPortrait(externalPortrait)
        .setLivePortrait(livePortrait)
        .build();

var config = RecognizeConfig.withScenario(Scenario.FULL_PROCESS, image: image);
config.extPortrait = externalPortrait;
config.livePortrait = livePortrait;

var config = RecognizeConfig.withScenario(Scenario.FULL_PROCESS, { image: image });
config.extPortrait = externalPortrait;
config.livePortrait = livePortrait;

var config = new RecognizeConfig()
config.scenario = Enum.ScenarioIdentifier.SCENARIO_FULL_PROCESS
config.image = image
config.extPortrait = externalPortraitBase64
config.livePortrait = livePortraitBase64

var config = new RecognizeConfig()
config.scenario = Enum.ScenarioIdentifier.SCENARIO_FULL_PROCESS
config.image = image
config.extPortrait = externalPortraitBase64
config.livePortrait = livePortraitBase64

var config = new RecognizeConfig()
config.scenario = Enum.ScenarioIdentifier.SCENARIO_FULL_PROCESS
config.image = image
config.extPortrait = externalPortraitBase64
config.livePortrait = livePortraitBase64

// Android
RecognizeConfig config = new RecognizeConfig.Builder(Scenario.ScenarioFullProcess)
    .SetBitmap(bitmap)
    .SetExtPortrait(externalPortrait)
    .SetLivePortrait(livePortrait)
    .Build();

// iOS
var config = new RGLRecognizeConfig(image);
config.Scenario = Constants.RGL_SCENARIO_FULL_PROCESS;
config.ExtPortrait = externalPortrait;
config.LivePortrait = livePortrait;

In the examples above, both livePortrait and extPortrait processing parameters are set, but you can use either one or both of them.

Then you can pick the image from Gallery or Files, and process it.

Configure Parameters

Use FaceApiParams to change the Face SDK Web Service URL, matching mode, search settings, thresholds, and proxy settings.

└── FaceApiParams
|   └── livenessTransactionId
|   └── url
|   └── mode
|   └── search
|   |   └── limit
|   |   └── threshold
|   |   └── groupIds    
|   └── threshold    
|   └── serviceTimeout
|   └── proxy
|   └── proxyUserPwd
|   └── proxyType

The table below describes the FaceApiParams parameters.

Parameter Default Description
livenessTransactionId — The ID of the liveness transaction from which the captured facial image is used for face matching instead of a submitted selfie. In match+search mode, the facial image captured during the liveness transaction is not returned in the response.
url https://faceapi.regulaforensics.com The URL of the Face SDK Web Service instance to use.

The default Regula Face SDK service URL is for demo purposes only. For production use, purchase an appropriate license. Contact Regula Face SDK sales for details.
mode match The processing mode: match or match+search.

Use match to compare the persons passed in the request. This mode works by default.

Use match+search to match and search by image. If only one person is available, the service runs only search. If no search parameters are specified, the service searches the entire database with the default parameters.

Learn more in OpenAPI documentation.
search — The search filter applies when the match+search mode is enabled. It may include the limit, threshold, and groupIds parameters. By default, the service searches the default group. If groupIds are specified, the service searches only these groups. For more information about search operations, see the OpenAPI documentation.
threshold 75 The similarity threshold is a value from 0 to 100. Values above 75 verify face similarity. Values below 75 do not verify face similarity.
serviceTimeout 3000 The service request timeout, ms.
proxy — The proxy to use. Set it according to the cURL standard.
proxyUserPwd — The username and password for proxy authentication. Set them according to the cURL standard.
proxyType — The proxy protocol type. Set it according to the cURL standard.

To configure FaceApiParams, use these examples:

let faceApiParams = FaceAPIParams()
faceApiParams.livenessTransactionId = "abc123ab-c123-abc1-23ab-c123abc123ab"
faceApiParams.url = "url"
faceApiParams.mode = "match"
faceApiParams.threshold = 90
faceApiParams.proxy = "proxy"
faceApiParams.proxyPassword = "user_pwd"
faceApiParams.proxyType = 1

let faceApiSearchParams = RGLFaceAPISearchParams()
faceApiSearchParams.limit = 100
faceApiSearchParams.threshold = 0.9
faceApiSearchParams.groupIDs = ["id1", "id2", "id3"]
faceApiParams.searchParams = faceApiSearchParams

DocReader.shared.processParams.useFaceApi = true
DocReader.shared.processParams.faceApiParams = faceApiParams

RGLFaceAPIParams *faceApiParams = [[RGLFaceAPIParams alloc] init];
faceApiParams.livenessTransactionId = @"abc123ab-c123-abc1-23ab-c123abc123ab";
faceApiParams.url = @"url";
faceApiParams.mode = @"match";
faceApiParams.threshold = @90;
faceApiParams.proxy = @"proxy";
faceApiParams.proxyPassword = @"user_pwd";
faceApiParams.proxyType = @1;

RGLFaceAPISearchParams *faceApiSearchParams = [[RGLFaceAPISearchParams alloc] init];
faceApiSearchParams.limit = @100;
faceApiSearchParams.threshold = @0.9f;
faceApiSearchParams.groupIDs = @[@"id1", @"id2", @"id3"];
faceApiParams.searchParams = faceApiSearchParams;

RGLDocReader.shared.processParams.useFaceApi = @YES;
RGLDocReader.shared.processParams.faceApiParams = faceApiParams;

val faceApiParams = FaceApiParams()
faceApiParams.livenessTransactionId = "abc123ab-c123-abc1-23ab-c123abc123ab"
faceApiParams.url = "url"
faceApiParams.mode = "match"
faceApiParams.serviceTimeout = 4000
faceApiParams.threshold = 90
faceApiParams.proxy = "proxy"
faceApiParams.proxyUserPwd = "user_pwd"
faceApiParams.proxyType = 1

val search = FaceApiParams.Search()
search.limit = 100
search.threshold = 0.9f
search.groupIds = arrayOf("id1", "id2", "id3")

faceApiParams.search = search

DocumentReader.Instance().processParams().faceApiParams = faceApiParams

FaceApiParams faceApiParams = new FaceApiParams();
faceApiParams.setLivenessTransactionId("abc123ab-c123-abc1-23ab-c123abc123ab");
faceApiParams.setUrl("url");
faceApiParams.setMode("match");
faceApiParams.setServiceTimeout(4000);
faceApiParams.setThreshold(90);
faceApiParams.setProxy("proxy");
faceApiParams.setProxyUserPwd("user_pwd");
faceApiParams.setProxyType(1);

FaceApiParams.Search search = new FaceApiParams.Search();
search.setLimit(100);
search.setThreshold(0.9f);
search.setGroupIds(new String[]{"id1", "id2", "id3"});

faceApiParams.setSearch(search);

DocumentReader.Instance().processParams().faceApiParams = faceApiParams;

var faceApiParams = FaceApiParams(
    livenessTransactionId: "abc123ab-c123-abc1-23ab-c123abc123ab",
    url: "https://faceapi.regulaforensics.com/",
    mode: "match",
    serviceTimeout: 2000,
    threshold: 90,
    proxy: "https://example.com/",
    proxyPassword: "Regula%20user:StrongPassword",
    proxyType: 2,
    searchParams: FaceApiSearchParams(
      limit: 100,
      threshold: 0.9,
      groupIds: ["id1", "id2", "id3"],
    ));

DocumentReader.instance.processParams.useFaceApi = true;
DocumentReader.instance.processParams.faceApiParams = faceApiParams;

var faceApiParams = new FaceApiParams({
  url: "https://faceapi.regulaforensics.com/",
  mode: "match",
  serviceTimeout: 2000,
  threshold: 90,
  proxy: "https://example.com/",
  proxyPassword: "Regula%20user:StrongPassword",
  proxyType: 2,
  searchParams: new FaceApiSearchParams({
    limit: 100,
    threshold: 0.9,
    groupIds: ["id1", "id2", "id3"]
  })
});

DocumentReader.instance.processParams.useFaceApi = true;
DocumentReader.instance.processParams.faceApiParams = faceApiParams;

var faceApiParams = new FaceApiParams()
faceApiParams.livenessTransactionId = "abc123ab-c123-abc1-23ab-c123abc123ab"
faceApiParams.url = "https://faceapi.regulaforensics.com/"
faceApiParams.mode = "match"
faceApiParams.serviceTimeout = 2000
faceApiParams.threshold = 90
faceApiParams.proxy = "https://example.com/"
faceApiParams.proxyPassword = "Regula%20user:StrongPassword"
faceApiParams.proxyType = 2

var search = new Search()
search.limit = 100
search.threshold = 0.9
search.groupIds = ["id1", "id2", "id3"]
faceApiParams.searchParams = search

DocumentReader.setProcessParams({
    useFaceApi: true,
    faceApiParams: faceApiParams,
}, _ => { }, _ => { })

var faceApiParams = new FaceApiParams()
faceApiParams.livenessTransactionId = "abc123ab-c123-abc1-23ab-c123abc123ab"
faceApiParams.url = "https://faceapi.regulaforensics.com/"
faceApiParams.mode = "match"
faceApiParams.serviceTimeout = 2000
faceApiParams.threshold = 90
faceApiParams.proxy = "https://example.com/"
faceApiParams.proxyPassword = "Regula%20user:StrongPassword"
faceApiParams.proxyType = 2

var search = new Search()
search.limit = 100
search.threshold = 0.9
search.groupIds = ["id1", "id2", "id3"]
faceApiParams.searchParams = search

DocumentReader.setProcessParams({
    useFaceApi: true,
    faceApiParams: faceApiParams,
})

var faceApiParams = new FaceApiParams()
faceApiParams.livenessTransactionId = "abc123ab-c123-abc1-23ab-c123abc123ab"
faceApiParams.url = "https://faceapi.regulaforensics.com/"
faceApiParams.mode = "match"
faceApiParams.serviceTimeout = 2000
faceApiParams.threshold = 90
faceApiParams.proxy = "https://example.com/"
faceApiParams.proxyPassword = "Regula%20user:StrongPassword"
faceApiParams.proxyType = 2

var search = new Search()
search.limit = 100
search.threshold = 0.9
search.groupIds = ["id1", "id2", "id3"]
faceApiParams.searchParams = search

DocumentReader.setProcessParams({
    useFaceApi: true,
    faceApiParams: faceApiParams,
}, function (s) { }, function (e) { })

// Android
FaceApiParams faceApiParams = new()
{
    LivenessTransactionId = "abc123ab-c123-abc1-23ab-c123abc123ab",
    Url = "url",
    Mode = "match",
    ServiceTimeout = 4000,
    Threshold = 90,
    Proxy = "proxy",
    ProxyUserPwd = "user_pwd",
    ProxyType = (Java.Lang.Integer)1
};

FaceApiParams.Search search = new()
{
    Limit = 100,
    Threshold = 0.9f
};
search.SetGroupIds(new String[] { "id1", "id2", "id3" });

faceApiParams.SetSearch(search);

DocumentReader.Instance().ProcessParams().UseFaceApi = (Java.Lang.Boolean)true;
DocumentReader.Instance().ProcessParams().FaceApiParams = faceApiParams;

// iOS
RGLFaceAPIParams faceApiParams = new()
{
    LivenessTransactionId = "abc123ab-c123-abc1-23ab-c123abc123ab",
    Url = "url",
    Mode = "match",
    Threshold = 90,
    Proxy = "proxy",
    ProxyPassword = "user_pwd",
    ProxyType = 1
};

RGLFaceAPISearchParams faceApiSearchParams = new()
{
    Limit = 100,
    Threshold = 0.9f,
    GroupIDs = new NSString[] { "id1", "id2", "id3" }
};
faceApiParams.SearchParams = faceApiSearchParams;

RGLDocReader.Shared.ProcessParams.UseFaceApi = true;
RGLDocReader.Shared.ProcessParams.FaceApiParams = faceApiParams;

Then start the document processing.

Next Steps