Como integrar Oz Liveness à sua aplicação móvel

O Oz Liveness Mobile SDK implementa a interface de usuário de captura facial pronta para uso, essencial para uma experiência do cliente fluida e resultados de Liveness precisos.

Este guia conduz você pela sua primeira verificação de Liveness usando Mobile SDK (iOS ou Android) e Oz API.

O fluxo descrito combina:

• Modo de captura – o Mobile SDK captura o vídeo de Liveness no app e o backend do CLIENT o encaminha para Oz API. Os resultados de captura não são enviados do SDK diretamente para Oz API; o backend do CLIENT atua como intermediário.

• OzCapsula – um contêiner binário criptografado proprietário. O SDK empacota a mídia capturada nele; apenas a Oz API pode descriptografá-lo e processá-lo. No dispositivo, ele é um blob opaco – não é possível decodificá-lo ou inspecioná-lo, apenas encaminhá-lo como está.

Cada etapa é marcada:

• [Oz SDK] – chame nossa API do SDK.

• [Seu código] – chame seu próprio backend ou seu próprio código.

{{host}} nos exemplos abaixo é a URL base da sua implantação da Oz API, fornecida durante a configuração da implantação.

Requisitos

Componente	Versão mínima
Oz API	6.6.1
iOS SDK	10.0.0
Android SDK	10.0.0
Flutter	10.0.0

Use Content-Type: application/octet-stream para qualquer contêiner enviado ao Oz API.

Antes de começar, certifique-se de ter credenciais do Oz API. Ao usar a API SaaS, você as obtém de nós:

Login: [e-mail]
Senha: …
API: https://<link>.ozforensics.com
Web Console: https://<link>.ozforensics.com

Para o Oz API on-premise, você precisa criar um usuário por conta própria ou pedir à sua equipe que gerencia a API. Consulte o guia sobre criação de usuário via Web Console. Considere a função de usuário adequada (CLIENT na maioria dos casos ou CLIENT ADMIN, se for fazer o SDK funcionar com as pastas pré-criadas de outros usuários da API). No fim, você precisa obter um conjunto semelhante de credenciais ao que receberia no cenário SaaS.

Esses parâmetros são obrigatórios para o OzCapsula funcionar. Defina-os no arquivo de configuração da sua API.

OZ_SESSION_TOKEN_LIFETIME=<your_ttl_for_session_token>
OZ_JWT_PRIVATE_KEY_PATH=<jwt_private_key_path>
OZ_JWT_PUBLIC_KEY_PATH=<jwt_public_key_path>
OZ_MALEWICZ_ANALYSIS_ENABLED=true

Também recomendamos o uso do nosso serviço de logging chamado telemetry, pois ele ajuda muito na investigação dos detalhes dos ataques. Para usuários do Oz API, o serviço está habilitado por padrão. Para instalações on-premise, forneceremos credenciais.

Oz Liveness Mobile SDK requer uma licença. A licença está vinculada ao bundle_id da sua aplicação, por exemplo, com.yourcompany.yourapp.

Instruções

1

(seu código) Adicione o SDK ao seu projeto

Android

No build.gradle do seu projeto, adicione:

allprojects {
    repositories {
        maven { url "https://ozforensics.jfrog.io/artifactory/main" }
    }
}

No build.gradle do módulo, adicione:

dependencies {
    implementation 'com.ozforensics.liveness:full:<version>'
    // Você pode encontrar a versão necessária no changelog do Android
}

iOS

CocoaPods

Para integrar o OZLivenessSDK a um projeto Xcode, adicione ao Podfile:

pod 'OZLivenessSDK', :git => 'https://gitlab.com/oz-forensics/oz-mobile-ios-sdk', :tag => '<version>' // Você pode encontrar a versão necessária no changelog do iOS

SPM

Adicione as seguintes dependências de pacote via SPM: https://gitlab.com/oz-forensics/oz-mobile-ios-sdk (se precisar de um guia sobre como adicionar as dependências de pacote, consulte a documentação da Apple). OzLivenessSDK é obrigatório. Ignore o OzLivenessSDKOnDevice arquivo.

Flutter

Adicione ao pubspec.yaml:

ozsdk: ^10.0.0

2

(Oz SDK) Inicialize o SDK com uma licença

Chame uma vez a cada inicialização do app.

Android

OzLivenessSDK.init(
    context,
    listOf(LicenseSource.LicenseAssetId(R.raw.forensics)),
    object : StatusListener<LicensePayload> {
        override fun onSuccess(result: LicensePayload) {
            // SDK pronto — prossiga para a Etapa 3
        }
        override fun onError(error: OzException) {
            // trate o erro de licença
        }
    }
)

Conecte o receptor de telemetry

Depois que a licença for carregada, aponte o SDK para o receptor de telemetry do Oz para que ele possa enviar telemetry. Passe o host de eventos junto com um token de serviço.

val eventsConnection = OzConnection.fromServiceToken(
    host = "<telemetry-receiver-host>",
    token = "<telemetry-service-token>"
)

OzLivenessSDK.setEventsConnection(eventsConnection, object : StatusListener<String?> {
    override fun onSuccess(accessToken: String?) {
        // receptor de telemetry pronto — prossiga para a Etapa 2
    }
    override fun onError(error: OzException) {
        // trate o erro de conexão de eventos
    }
})

O host de eventos e o token de serviço são fornecidos por Oz Forensics. Eles são distintos do session_token usado para a captura na Etapa 2.

iOS

OZSDK(licenseSources: [.licenseFilePath(path)]) { licenseData, error in
    if let error = error {
        // trate o erro de licença
    } else {
        // SDK pronto — prossiga para a Etapa 3
    }
}

Configuração opcional de idioma:

OZSDK.set(languageBundle: Bundle(for: OzSdk.self))
OZSDK.localizationCode = (lang == "en") ? .en : .custom(lang)

Conecte o receptor de telemetry

Depois que a licença for carregada, aponte o SDK para o receptor de telemetry do Oz para que ele possa enviar telemetry. Passe o host de eventos junto com um token de serviço.

let eventsConnection = Connection.fromServiceToken(
    host: "<telemetry-receiver-host>",
    token: "<telemetry-service-token>",
    sslPins: nil
)

OZSDK.setEventsConnection(eventsConnection) { accessToken, error in
    if let error = error {
        // trate o erro de conexão de eventos
    } else {
        // receptor de telemetry pronto — prossiga para a Etapa 2
    }
}

O host de eventos e o token de serviço são fornecidos por Oz Forensics. Eles são distintos do session_token usado para a captura na Etapa 2.

Flutter

await OZSDK.initSDK([<% license path and license file name %>]);

Conecte o receptor de telemetry

Depois que a licença for carregada, aponte o SDK para o receptor de telemetry do Oz para que ele possa enviar telemetry. Passe o host de eventos junto com um token de serviço.

await OZSDK.setEventConnectionWithToken(<telemetry-receiver-token>, <telemetry-receiver-host>);

O host de eventos e o token de serviço são fornecidos por Oz Forensics. Eles são distintos do session_token usado para a captura na Etapa 2.

Durante o desenvolvimento, as verificações de segurança do SDK podem fazer com que a análise seja declined – por exemplo, quando o app é executado com um depurador conectado. Se precisar executar o SDK nessas condições durante o desenvolvimento, reduza a rigidez das verificações de segurança definindo o ambiente do SDK como o debug modo:

Android

OzLivenessSDK.setEnvironment(OzLivenessSDK.Environment.DEBUG)

iOS

OZSDK.setEnvironment(environment: .debug)

Flutter

OZSDK.setEnvironment(debug)

O debug deve ser usado somente durante o desenvolvimento e os testes. Todas as compilações de release devem usar o valor padrão PRODUCTION (Android), .prod (iOS), ou production (Flutter), em que todas as verificações de segurança estão habilitadas.

3

(seu código) Obtenha um session_token do seu backend

O OzCapsula usa um session_token. O token é obrigatório para o OzCapsula.

Seu backend solicita um session_token da Oz API. Solicite-o antes de cada sessão de captura, o mais próximo possível do momento em que o usuário iniciar a captura.

Endpoint:

GET {{host}}/api/authorize/session_token

Solicitação:

curl --location -g '{{host}}/api/authorize/session_token' \\
--header 'X-Forensic-Access-Token: {{access_token}}' ## opcional, depende das configurações da instalação

O mecanismo de autorização para chamadas à Oz API (access_token) depende das configurações da sua instalação: ao usar a Instant API, você pode integrá-la ao seu próprio esquema de autorização. Se um access token for exigido no seu caso, consulte Autenticação. Além disso, observe que o token de acesso e o session_token são tokens diferentes emitidos para finalidades diferentes.

Resposta:

{
  "session_token": "<session_token>"
}

Esse token é de curta duração (validade padrão: 900 segundos para API Full, 120 segundos para Instant API). Solicite um por sessão de captura e passe-o ao SDK imediatamente – não armazene em cache nem reutilize tokens entre sessões.

4

(Oz SDK) Abra a tela de captura com o session_token

Passe o session_token de Etapa 3.

Android

val captureRequest = CaptureRequest(
    listOf(
        AnalysisProfile(
            Analysis.Type.QUALITY,
            listOf(MediaRequest.ActionMedia(OzAction.Blank))
        )
    )
)
val intent = OzLivenessSDK.createMediaCaptureScreen(captureRequest, sessionToken)
startActivityForResult(intent, REQUEST_LIVENESS_CONTAINER)

iOS

let mediaRequest = MediaRequest.action(.selfie)

let profile = AnalysisProfile(
    mediaList: [mediaRequest],
    type: .quality,
    params: [:]
)

let request = CaptureRequest(
    analysisProfileList: [profile],
    cameraPosition: .front
)

let livenessVC = try OZSDK.createMediaCaptureScreen(
    delegate,
    request,
    sessionToken: sessionToken          // da Etapa 3
)

livenessVC.modalPresentationStyle = .fullScreen
parent.present(livenessVC, animated: true)

Flutter

final sessionToken = await _getSessionToken();
OZSDK.createMediaCaptureScreen(
  CaptureRequest(
    analysisProfileList: [
      AnalysisProfile(
        Type.quality,
        mediaList: [ActionMedia(VerificationAction.blank)]
      ),
    ],
  ),
  sessionToken,
);

5

(Oz SDK) Obtenha o contêiner OzCapsula

O contêiner é um blob criptografado opaco. Você não pode decodificá-lo, inspecioná-lo ou extrair imagens / quadros / metadados individuais dele no dispositivo. Ele deve ser encaminhado como está para o seu backend. Se precisar de acesso às imagens capturadas (por exemplo, a melhor captura), recupere-as da resposta de análise da Oz API no lado do servidor.

Android

Extraia o DataContainer do intent de resultado.

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    if (requestCode == REQUEST_LIVENESS_CONTAINER) {
        when (resultCode) {
            OzLivenessResultCode.SUCCESS -> {
                val container = OzLivenessSDK.getContainerFromIntent(data)
                handleContainer(container)
            }
            OzLivenessResultCode.USER_CLOSED_LIVENESS -> { /* o usuário fechou a tela */ }
            else -> {
                val errorMessage = OzLivenessSDK.getErrorFromIntent(data)
                /* exibir erro */
            }
        }
    }
}

iOS

Implemente o delegate. Em caso de sucesso, você recebe um DataContainer.

extension YourViewController: LivenessDelegate {
    func onResult(container: DataContainer) {
        // Passe o contêiner para a Etapa 6
        handleContainer(container)
    }

    func onError(status: OZVerificationStatus?) {
        // usuário cancelou, a captura falhou etc.
    }
}

Flutter

Inscreva-se em livenessResult; o contêiner chega como um DataContainer.

@override
void initState() {
  super.initState();
  _subscription = OZSDK.livenessResult.listen((result) {
    if (result is DataContainer) {
      // mídia do OzCapsula
    }
  }, onError: (Object error) {
    // tratar o erro, na maioria dos casos PlatformException
  });
}

6

(seu código) Envie o contêiner para a Oz API

Envie o contêiner criptografado para o seu próprio backend como bytes brutos (application/octet-stream). Seu backend o encaminha para Oz API e retorna a resposta da análise.

Não não execute a análise diretamente do mobile SDK. No fluxo de integração com SDK incorporado, a chamada de análise deve passar pelo seu próprio backend.

Android

O código abaixo é ilustrativo – YourBackend.uploadOzContainer(...) for não parte do Oz SDK. Implemente este método você mesmo no cliente do seu backend; o Oz SDK não fornece um helper de upload para este caminho de integração.

private fun handleContainer(container: DataContainer?) {
    if (container == null) return

    YourBackend.uploadOzContainer(
        container = container.getBytes(),
        contentType = "application/octet-stream"
    )
}

Não não chame AnalysisRequest.Builder().addContainer(...).build().run(...).

iOS

O código abaixo é ilustrativo – YourBackend.uploadOzContainer for não parte do Oz SDK. Implemente este método você mesmo no cliente do seu backend; o Oz SDK não fornece um helper de upload para este caminho de integração.

func handleContainer(_ container: DataContainer) {
    YourBackend.uploadOzContainer(
        container,
        contentType: "application/octet-stream"
    ) { result in
        DispatchQueue.main.async {
            self.handleAnalysisResult(result)
        }
    }
}

Não não chame AnalysisRequestBuilder / AnalysisRequest.run(...).

Flutter

O código abaixo é ilustrativo – YourBackend.uploadOzContainer for não parte do Oz SDK. Implemente este método você mesmo no cliente do seu backend; o Oz SDK não fornece um helper de upload para este caminho de integração.

final Uint8List? containerBytes = await OZSDK.getContainerBytes(dataContainer);
await YourBackend.uploadOzContainer(
        container: containerBytes,
        contentType: "application/octet-stream",
      );

Não não chame OZSDK.analyze.

Seu backend envia o contêiner para Oz API em uma única operação síncrona POST solicitação.

Endpoint (Instant API):

POST {{host}}/api/instant/folders/

Endpoint (Full API):

POST {{host}}/api/folders/

Cabeçalhos:

• Content-Type: application/octet-stream (obrigatório).

• X-Forensic-Access-Token: {{access_token}}. (opcional, depende das configurações da instalação).

Corpo da solicitação: os bytes brutos do contêiner – sem envelope JSON, sem multipart, sem encapsulamento base64.

Solicitação (Instant API):

curl -X POST '{{host}}/api/instant/folders/' \\
  --header 'X-Forensic-Access-Token: {{access_token}}' ## opcional, depende das configurações da instalação
  -H 'Content-Type: application/octet-stream' \\
  --data-binary '@/path/to/container.dat'

Solicitação (Full API):

curl -X POST '{{host}}/api/folders/' \\
  --header 'X-Forensic-Access-Token: {{access_token}}' ## opcional, depende das configurações da instalação
  -H 'Content-Type: application/octet-stream' \\
  --data-binary '@/path/to/container.dat'

Em caso de sucesso: HTTP 201 com um objeto JSON de pasta descrevendo o resultado. Consulte Etapa 7.

Em caso de erro no nível do contêiner: HTTP 400 – consulte Exceções.

Este guia cobre a análise de Liveness. Para executar uma análise de Face Matching dentro do fluxo do OzCapsula, consulte Como Executar uma Análise de Face Matching no Fluxo do OzCapsula.

7

(seu código) Trate a resposta

Seu backend agora tem a resposta – um objeto JSON de pasta descrevendo o resultado.

Tome a decisão de aceitar/rejeitar usando apenas estes dois campos de nível superior:

$.resolution_status   // "FINISHED" – análises concluídas; "FAILED" – erro no processamento da análise
$.system_resolution   // "SUCCESS", "DECLINED" ou "FAILED"

Interprete system_resolution:

• SUCCESS – todas as verificações foram aprovadas; aceite o usuário.

• DECLINED – uma ou mais verificações falharam; rejeite o usuário.

• FAILED – um erro de sistema impediu que pelo menos uma análise fosse concluída; não trate como aceitação ou rejeição.

Para veredictos por análise (por exemplo, para saber se liveness foi aprovado, mas biometria falhou), leia $.analyses[*].resolution_status com os valores descritos acima.

Lista de verificação

• SDKs iOS, Android e Flutter 10.0.0+, Oz API 6.6.1+.

• A inicialização da licença da Etapa 2 é executada uma vez por inicialização do app.

• A Etapa 2 também conecta o receptor de telemetry com o host de eventos + token de serviço.

• A Etapa 3 obtém um novo session_token do seu backend antes de cada captura.

• A Etapa 4 passa esse session_token para createMediaCaptureScreen(...).

• A Etapa 5 retorna um DataContainer; nenhuma tentativa é feita para decodificar/inspecionar imagens no dispositivo.

• A Etapa 6 envia o contêiner para o seu próprio backend como application/octet-stream, e seu backend o envia para POST {{host}}/api/instant/folders/ (Instant API) ou POST {{host}}/api/folders/ (API completa).

• A análise nunca é executada diretamente a partir do mobile SDK.

• A decisão de aceitar/rejeitar usa apenas resolution_status e system_resolution.

• session_token nunca é armazenado em cache, reutilizado ou compartilhado entre sessões/usuários.

---

Com estas etapas, a integração básica dos Mobile SDKs está concluída. Você poderá acessar a mídia gravada e os resultados da análise na Web Console via navegador ou programaticamente via API.

Nos guias do desenvolvedor, você também pode encontrar instruções para personalizar a aparência do SDK e acessar a lista completa dos métodos do nosso Mobile SDK. Confira a tabela abaixo:

Android app de exemplo código-fonte	iOS app de exemplo código-fonte	Flutter app de exemplo código-fonte
Android SDK Guia do desenvolvedor	iOS SDK Guia do desenvolvedor	Flutter SDK Guia do desenvolvedor
app de demonstração no PlayMarket	app de demonstração no TestFlight