Migração para OzCapsula

Este guia descreve a migração para a arquitetura mais recente do OzCapsula: a abordagem em que se usa um contêiner criptografado para transmitir dados com segurança entre frontend e backend.

Requisitos de versão dos componentes

Antes de iniciar a migração, verifique se todos os componentes estão atualizados para as versões mínimas necessárias:

• API: 6.6.1.

• Web SDK: 1.9.10.

• SDKs nativos (iOS / Android) e Flutter: 10.0.0.

Recomenda-se fortemente o uso das versões mais recentes do software Oz.

Versões mais antigas são incompatíveis com o novo fluxo de captura e análise.

Para melhores resultados, migre todos os componentes simultaneamente e evite atualizações parciais.

Alterações na autenticação

Todas as sessões de captura agora exigem um session_token emitido pelo backend.

• O token deve ser obtido antes de antes de iniciar a captura de vídeo.

• Ele está vinculado à sessão atual e ao contêiner específico.

• O token tem um tempo de vida limitado.

Ações de migração

• Implemente uma chamada de backend para obter session_token.

• Passe o token explicitamente ao criar a tela de captura.

Alterações no fluxo

Antes do contêiner (fluxo legado)

1. Você inicia a captura de mídia.

2. A mídia é capturada.

3. A mídia, junto com os dados necessários, é enviada ao Oz API (usando seu backend como intermediário, se necessário).

Com contêiner (novo fluxo)

1. Você solicita session_token ao backend.

2. Coloque dados adicionais, como metadados (se necessário), no contêiner e inicie a captura de vídeo com session_token.

3. O SDK captura a mídia, a empacota no contêiner e retorna um arquivo criptografado.

4. O arquivo criptografado é enviado ao Oz API (usando seu backend como intermediário, se necessário).

Ações de migração

API

• Atualize para a v6.6.1 ou superior.

• Altere Content-Type o tipo de dado que você envia para application/octet-stream.

• Para o Instant API, obtenha as chaves privada e pública conforme descrito aqui.

Web SDK

• Atualize para a v1.9.10 ou superior.

• Garanta que o backend ofereça suporte a session_token.

• No arquivo de configuração, defina use_wasm_container como true e api_use_session_token como api ou client (consulte este artigo para mais detalhes).

Este modo destina-se apenas a desenvolvimento e testes. Para ambientes de produção, use api_use_session_token: "client".

• Atualize a inicialização para passar o token explicitamente.

• Se você usar a captura tipo de arquitetura, certifique-se de receber e enviar ao seu backend e, depois, para nós um blob objeto (application/octet-stream).

Mobile SDKs

• Atualize para a v10.0.0 ou superior.

• Garanta que o backend ofereça suporte a session_token.

• Implemente as novas interfaces conforme descrito abaixo.

Observe: não use "_" (underscore) nos nomes de arquivo para o fluxo de contêiner.

Android

1

Iniciando a tela de captura

Fluxo do OzCapsula

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

Fluxo antigo (antes do contêiner)

val intent = OzLivenessSDK.createStartIntent(listOf(OzAction.Blank))
startActivityForResult(intent, REQUEST_LIVENESS_MEDIA)

2

Assinatura de mídia

Fluxo do OzCapsula

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

Fluxo antigo (antes do contêiner)

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

3

Iniciando análise

Fluxo do OzCapsula

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

    AnalysisRequest.Builder()
        .addContainer(container)
        .build()
        .run(
            { result ->
                val isSuccess = result.analysisResults.all { it.resolution == Resolution.SUCCESS }
            },
            { /* exibir erro */ },
            { /* atualizar status */ },
        )
}

Fluxo antigo (antes do contêiner)

private fun runAnalysis(media: List<OzAbstractMedia>?) {
    if (media.isNullOrEmpty()) return
    AnalysisRequest.Builder()
        .addAnalysis(Analysis(Analysis.Type.QUALITY, Analysis.Mode.SERVER_BASED, media))
        .build()
        .run(
            { result ->
                val isSuccess = result.analysisResults.all { it.resolution == Resolution.SUCCESS }
            },
            { /* exibir erro */ },
            { /* atualizar status */ },
        )
}

iOS

1

Iniciando a tela de captura

Fluxo do OzCapsula

getSessionToken() { sessionToken in
            DispatchQueue.main.async {
                do {
                    let action:OZVerificationMovement = .selfie
                    let mediaRequest = MediaRequest.action(action)
                    let profile = AnalysisProfile(mediaList: [mediaRequest],
                                                  type: .quality,
                                                  params: [:] )
                    let request = CaptureRequest(analysisProfileList: [profile], cameraPosition: .front)
                    let ozLivenessVC = try OZSDK.createMediaCaptureScreen(self, request, sessionToken: sessionToken)
                    self.present(ozLivenessVC, animated: true)
                } catch let error {
                    print(error.localizedDescription)
                }
            }
        }

Fluxo antigo (antes do contêiner)

do {
    let ozLivenessVC : UIViewController = try OZSDK.createVerificationVCWithDelegate(self, actions: .selfie)   
    self.present(ozLivenessVC, animated: true)
} catch let error {
    print(error.localizedDescription)
}

2

Assinatura de mídia

Fluxo do OzCapsula

extension ViewController: LivenessDelegate {
    func onResult(container: DataContainer) {
    }
    
    func onError(status: OZVerificationStatus?) {
    }
}

Fluxo antigo (antes do contêiner)

extension ViewController: OZLivenessDelegate {
    func onOZLivenessResult(results: [OZMedia]) {
    }
  
    func onError(status: OZVerificationStatus?) {
    }
}

3

Iniciando análise

Fluxo do OzCapsula

func onResult(container: DataContainer) {
  let analysisRequest = AnalysisRequestBuilder()
  analysisRequest.addContainer(container)
  analysisRequest.run(
            statusHandler: { status in
            },
            errorHandler: { error in
            }
        ) { result in
            
        }
}

Fluxo antigo (antes do contêiner)

func onResult(results: [OZMedia]) {
        let analysisRequest = AnalysisRequestBuilder()
        let analysis = Analysis(media: results,
                                type: .quality,
                                mode: .serverBased,
                                params: nil)
        analysisRequest.addAnalysis(analysis)
        analysisRequest.run { status in
        } errorHandler: { error in
        } completionHandler: { results in
            
        }
    }

Flutter

1

Iniciando a tela de captura

Fluxo do OzCapsula

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

Fluxo antigo (antes do contêiner)

OZSDK.startLiveness(<list of actions>);

2

Assinatura de mídia

Fluxo do OzCapsula

@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
  });
}

Fluxo antigo (antes do contêiner)

@override
void initState() {
  super.initState();
  _subscription = OZSDK.livenessResult.listen((result) {
    if (result is List) {
      final mediaList = result.toList().cast<Media>();
    }
  }, onError: (Object error) {
    // tratar o erro, na maioria dos casos PlatformException
  });
}

3

Iniciando análise

Fluxo do OzCapsula

try {
  final Uint8List? containerBytes = await OZSDK.getContainerBytes(dataContainer);
  final List<RequestResult> analysisResult = await OZSDK.analyze(
      analysis: [],
      dataContainer: dataContainer,
    );
} catch (e) {
  _showErrorDialog(e);
}

Fluxo antigo

List<Analysis> analysis = [ Analysis(Type.quality, Mode.serverBased, <media>, {}), ];
final analysisResult = await OZSDK.analyze(analysis, [], {});

Lista de verificação da migração

• A API está atualizada para 6.6.1 ou superior, com session_token com suporte.

  • Content-Type é alterado para application/octet-stream.

  • Para o Instant API, as chaves privada e pública são obtidas.

• Os SDKs móveis estão atualizados para 10.0.0 ou superior.

  • Adicionado o session_token chamada de backend.

  • A nova interface pública é implementada: createMediaCaptureScreen com CaptureRequest.

• O Web SDK está atualizado para 1.9.10 ou superior.

  • use_wasm_container está definido como true.

  • api_use_session_token está definido como api ou client.

  • Se api_use_session_token = client, session_token é solicitado antes da sessão e passado em open.options().