Skip to main content

Developing User Applications

Resources​

MegaMatcher ID Web Service comes with prebuilt Java and Typescript REST wrappers. They are located in:

  • Bin\Java\mega-matcher-id-management-client.jar
  • Bin\typescript\neurotec-megamatcherid-management-client.tgz

If user does not want to use these wrappers or other programming language support is needed, REST schema Documentation\REST-schema.json can be used to develop their own wrappers. More information about APIs can be found here

Java wrapper usage​

Install​

To use the client first, we need to install it using maven

mvn install

Add maven dependency to your project:

    <dependency>
        <groupId>com.neurotec</groupId>
        <artifactId>mega-matcher-id-management-client</artifactId>
        <version>2024.2.0.0</version>
    </dependency>

Usage​

To use client first we need to initialize ApiClient and set base path, authorization and some additional settings. Here is an example of how to use initialize client.

REST client is built on top of Feign HTTP client, because of that every endpoint has its own interface that has to be used to create a client.

Example below shows how to create client for Subjects endpoint;

    public SubjectsApi subjectsApi() {
        ApiClient client = new ApiClient();
        var objectMapper = client.getObjectMapper();
        objectMapper.enable(DeserializationFeature.ACCEPT_EMPTY_STRING_AS_NULL_OBJECT);
        objectMapper.configure(DeserializationFeature.ACCEPT_SINGLE_VALUE_AS_ARRAY, true);
        client.getFeignBuilder().decoder(new JacksonDecoder(objectMapper));
        client.setBasePath("http://<server-address>:<management-port>/");
        client.addAuthorization("main", new BasicAuthRequestInterceptor("admin", "admin"));
        return client.buildClient(SubjectsApi.class);
    }

Now we can call this method to make request to the Subjects endpoint as a Admin user.

Typescript wrapper usage​

Install​

To use Face Verification Management Client for TypeScript firstly you have to include it to your project package.json. You can do that by running your package manager (npm, yarn, etc...) install command and providing path to compiled client package.

Example:

yarn install file:./typescript/neurotec-megamatcherid-management-client-2024.2.0.tgz

Usage​

To use client first we need to configure it by specifying correct management service address. Here is an example of how to use initialize client.

Example below shows how to initialize client for Janus, Management, Subjects, Operations and Images endpoints:

import { Configuration, ConfigurationParameters, JanusApi, ManagementApi, SubjectsApi } from "neurotec-megamatcherid-management-client";

export const apiConfig: ConfigurationParameters = {
    basePath: "http://<server-address>:<management-port>",
    username: "user",
    password: "admin"
}

export const JanusAPI = new JanusApi(new Configuration(apiConfig));
export const ManagementAPI = new ManagementApi(new Configuration(apiConfig));
export const SubjectsAPI = new SubjectsApi(new Configuration(apiConfig));
export const OperationsAPI = new OperationsApi(new Configuration(apiConfig));
export const ImagesAPI = new ImagesApi(new Configuration(apiConfig));

Now we can import JanusAPI, ManagementAPI, SubjectsAPI, OperationsAPI, ImagesAPI in our project and make requests to according endpoints as simple User

API​

There are 6 main API endpoints:

Subject management is the main functionality of the service. Through the REST /subjects endpoint communication management service can:

  • create and delete subject
  • delete subjects in bulk
  • download subject`s data
  • get subjects
  • clearDb

Operations management is the additional functionality of the service. Through the REST /operations endpoint communication management service can: - get operations log - delete operations - add to operation log

Images management is the additional functionality of the service. Through the REST /images endpoint communication management service can: - get image - download image

Settings management is additional functionality of the service. Through the REST /management endpoint communication management service can:

  • get saved setting by key
  • get saved settings by key prefix
  • create/update/delete setting
  • reset default settings

Licensing management is additional functionality of the service. Through the REST /licensing endpoint communication management service can:

  • get connected dongles to licensing service
  • get licensing token
  • get licensing operation usage
  • apply update to dongles
  • get dongle update status

Janus session management is additional functionality of the service. Through the REST /janus endpoint communication management service can:

  • create Janus session
  • attach to Janus session
  • connect to Janus session
  • stop Janus session
  • trickle information to Janus

Full API documentation can be found here

Development with debug SSL certificate​

For development purposes it is possible to use development certificate. The certificate can be generated with opensll tools via following command:

openssl req -newkey rsa:4096 -nodes -sha256 -keyout domain.key -x509 -days 365 -out domain.crt

The command will produce domain.key and domain.crt. Now it can be used to Enable SSL. NOTE: during certificate generation resolvable domain ir ip address of the host machine should be used.

Main logic​

All biometric operation session creation are done through Management service. After session creation, Janus service and the users browser communicates directly. The full pipeline can be described in these steps:

  1. Call mmid-management/janus/create-and-attach, receive session object.
  2. Call mmid-management/janus/connect and log operation to database. The payload includes:
    1. jsep object received from RTCPeerConnection.createOffer.
    2. session object received from mmid-management/janus/create-and-attach.
    3. params object which contains:
      1. type (integer [1 - Verify, 2 - Check Liveness, 3 - Enroll]).
      2. subjectId (subjectId’s stored in the database can be accessed via mmid-management/subjects/id-list)
        1. if type is Verify, subjectId must be from the database.
        2. if type is Enroll, subjectId must be unique in the database.
      3. checkIcaoCompliance, timeout, livenessMode and advancedParameters can be sent only if mmid-management runs in debug mode (this can be checked using mmid-management/management/info).
  3. RTCPeerConnection should now call the RTCPeerConnection.onicecandidate callback. Now call mmid-management/janus/trickle, the payload should include:
    1. session object received from mmid-management/janus/create-and-attach.
    2. data object which should include the ice candidate received on callback.
  4. RTCDataChannel’s (which should be created with RTCPeerConnection.createDataChannel) RTCDataChannel.onmessage callback should be evoked. Received object should contain a data object which should be parsed to a json object and conform to the schemas/janusResponse.json schema.
  5. mmid-management/janus/stop can be called after received data.operationFinished is true.

Samples​

Simple sample​

Simple sample is the most basic sample with minimal overhead to understand the MegaMatcher ID pipeline.

Source building instructions can be found here.

Sample source code is located in Samples\MegaMatcherIdWebClientSample.

Before starting the sample, management service address should be configured in Samples\MegaMatcherIdWebClientSample\src\api\api.ts:

export const apiConfig: ConfigurationParameters = {
    basePath: "http://<server_address>:<management_port>",
    username: "user",
    password: "admin"
}

Web sample​

Web sample provides higher level UI and operation management. This sample is described more here from UI perspective. Building instructions can be found here.

Web sample source code is private, but is supplied to some customers on demand.

Before starting the sample, management service address should be configured in neurotec-mega-matcher-id-demo-web\src\config\management-api.ts:

export const getFullApiUrl = (): string => {
    return "<server_address>"
}