Guia de Instalação

Instale e configure o Certta para Flutter. Aprenda sobre os requisitos do SDK, seleção de módulo, permissões, configuração de sessão, atualizações de token em tempo de execução e temas de cores.

Este guia aborda caf_sdk 2.4.0 e superiores (Certta DevX). Para a versão anterior CafSdk fluxo sequencial, consulte a documentação legada.

Instalando o SDK para Flutter

Este guia orienta você pela configuração necessária para baixar, configurar e inicializar Certta (caf_sdk 2.4.0+) em um app Flutter.

Confira o app de exemplo para um exemplo de implementação completo.

Requisitos

Requisito	Versão
Flutter	3.3.0+
Dart	3.9.0+
Android minSdk	26
Android compileSdk	36+
Kotlin	1.8+
Gradle	8.0+
Android Gradle Plugin (AGP)	8.0+
alvo de implantação do iOS	15.0+
Xcode	14.0+
Swift	5.0+

Etapa 1: Instale o SDK

flutter pub add caf_sdk

A versão do pacote publicada é 2.4.0. Importe a API Certta DevX com:

import 'package:caf_sdk/certta_sdk.dart';

A versão sequencial CafSdk / initializeCafSdk API ainda está disponível via package:caf_sdk/caf_sdk.dart. Prefira Certta para novas integrações. Veja Migrando do CafSdk.

Etapa 2: Configure a seleção de módulos

Crie um caf-modules-config.json arquivo na raiz do seu projeto (ao lado de pubspec.yaml) para escolher quais módulos nativos empacotar:

Se você omitir este arquivo, todos os módulos serão ativados por padrão e iproov-lite é usado como provedor de Face Liveness.

{
  "documentDetector": true,
  "faceLiveness": true,
  "documentDetectorUI": true,
  "faceLivenessUI": true,
  "livenessProviders": "iproov-lite",
  "fingerprint": true
}

Defina como true os módulos que você deseja usar.

Para um único provedor, livenessProviders pode ser uma string. Os valores permitidos são iproov-lite, iproov-full, payface, e facetec. Para usar vários provedores, use um array:

{
  "documentDetector": true,
  "faceLiveness": true,
  "documentDetectorUI": true,
  "faceLivenessUI": true,
  "livenessProviders": [
    "iproov-lite",
    "payface",
    "facetec"
  ],
  "fingerprint": true
}

iProov e Protobuf

• iproov-lite: use quando seu app tiver como alvo Protobuf JavaLite — a escolha usual para um binário Android menor.
• iproov-full: use quando você precisar de Protobuf Java (completo) junto com iProov.

Se você incluir o PayFace provedor, você também deve usar iProov Lite (iproov-lite). O PayFace é compilado com Protobuf JavaLite; misturá-lo com iproov-full causa conflitos de dependência do Protobuf na hora da compilação.

Fingerprint

O módulo Fingerprint é opcional (fingerprint, booleano). O padrão é false. Para ativá-lo, defina "fingerprint": true.

Fingerprint é coletado como parte do fluxo de liveness, então ele só é empacotado quando faceLiveness ou faceLivenessUI também está ativado. Definir "fingerprint": true sem um módulo de liveness não tem efeito.

Entre em contato com o Suporte CAF para solicitar a ativação no backend. Se isso não estiver habilitado do nosso lado, o SDK não acionará a biblioteca de fingerprint mesmo que a propriedade esteja true localmente.

Etapa 3: configuração do Android

Configure o bloco repositories no arquivo android/build.gradle.kts (geralmente na raiz):

Kotlin Script

repositories {
    maven { url = uri("https://repo.combateafraude.com/android/release") }
}

Groovy

repositories {
    maven { url "https://repo.combateafraude.com/android/release" }
}

Etapa 4: configuração do iOS

Navegue até o diretório ios/ do seu projeto Flutter e execute:

pod install

• Esta etapa é obrigatória para que o iOS possa vincular os módulos nativos.
• Execute novamente pod install sempre que dependências nativas forem adicionadas ou atualizadas.

---

Permissões

Android

Declare o seguinte em AndroidManifest.xml:

Face Liveness

Permissão	Descrição	Necessidade
android.permission.CAMERA	Acesso à câmera para verificação facial (liveness).	Obrigatória
android.permission.INTERNET	Comunicação com serviços de autenticação e verificação (HTTPS/WSS).	Obrigatória

Document Detector

Permissão	Descrição	Necessidade
android.permission.CAMERA	Acesso à câmera para capturar imagens de documentos.	Apenas para captura
android.permission.INTERNET	Enviar imagens capturadas para processamento e validação.	Obrigatória
android.permission.READ_EXTERNAL_STORAGE	Acessar arquivos armazenados quando o envio de documentos estiver ativado.	Apenas para upload

O Document Detector requer READ_EXTERNAL_STORAGE quando o envio de documentos está ativado.

iOS

Declare o seguinte em Info.plist:

Face Liveness

Permissão	Descrição	Necessidade
NSCameraUsageDescription	Acesso à câmera para verificação facial (liveness).	Obrigatória
Acesso à rede	Comunicação com serviços de autenticação e verificação (HTTPS/WSS).	Obrigatória

Document Detector

Permissão	Descrição	Necessidade
NSCameraUsageDescription	Acesso à câmera para capturar imagens de documentos.	Apenas para captura
Acesso à rede	Enviar imagens capturadas para processamento e validação.	Obrigatória
NSPhotoLibraryUsageDescription	Acessar arquivos armazenados quando o envio de documentos estiver ativado.	Apenas para upload

---

Configurando a sessão

Para gerar seu token móvel, siga este guia:

Autenticação

Inicialize o Certta assim que tiver um token móvel válido (JWT) e o ID do usuário — normalmente após o login:

import 'package:flutter/services.dart';
import 'package:caf_sdk/certta_sdk.dart';

final certta = CerttaSdk();

try {
  await certta.configureSdk(
    const CerttaConfiguration(
      mobileToken: 'seu-jwt',
      userId: 'id-do-usuario',
      environment: CafEnvironment.prod,
      securityEnabled: true,
    ),
  );
} on PlatformException catch (e) {
  // Trate BRIDGE_EXCEPTION
}

Você pode confirmar a sessão com await certta.isInitialized().

CerttaConfiguration parâmetros

Parâmetro	Tipo	Descrição
mobileToken	String	JWT móvel da CAF do seu backend.
userId	String	Identificador do usuário final.
environment	CafEnvironment	Ambiente de backend: prod, beta, ou dev.
securityEnabled	bool	Ativa verificações de segurança. Padrão true.
colorConfiguration	CafColorConfiguration?	Tema de cores opcional. Veja Tematização de cores.

configureSdk lança uma PlatformException com o código BRIDGE_EXCEPTION quando o mapeador nativo rejeita a configuração.

Atualizações de configuração em tempo de execução

userId e mobileToken podem ser atualizados após a configuração inicial configureSdk sem repetir a configuração completa. Chame estes após login, logout ou atualização do token:

await certta.updateUserId('novo-id-do-usuario');
await certta.updateMobileToken('novo-jwt-token');

Use esses métodos sempre que seu app fizer logout/login ou quando seu backend emitir um JWT atualizado, para que o Certta permaneça sincronizado com a sessão ativa.

Logs

Os logs do pipeline do SDK são emitidos em CerttaSdk.logStream:

certta.logStream.listen((log) {
  print('${log.level}: ${log.message}');
});

---

Tematização de cores

Face Liveness e Document Detector oferecem suporte a cores personalizadas para que a interface do SDK possa combinar com a sua marca. Passe strings hexadecimais (por exemplo "#RRGGBB") em CafColorConfiguration ao chamar configureSdk.

await certta.configureSdk(
  CerttaConfiguration(
    mobileToken: 'seu-jwt',
    userId: 'id-do-usuario',
    environment: CafEnvironment.prod,
    colorConfiguration: const CafColorConfiguration(
      primaryColor: '#FF0000',
      secondaryColor: '#00FF00',
      backgroundColor: '#FFFFFF',
      contentColor: '#000000',
      mediumColor: '#D1D1D1',
      dialogBackgroundColor: '#FFFFFF',
      dialogBorderColor: '#0C395E',
    ),
  ),
);

Todos os campos de cor são opcionais. Substitua apenas as cores de que você precisa.

Propriedade de cor	Descrição
primaryColor	Cor principal para botões e destaques.
secondaryColor	Cor secundária para elementos complementares.
backgroundColor	Cor de fundo da tela.
contentColor	Cor usada para textos e ícones.
mediumColor	Cor neutra para elementos como barras de progresso.
dialogBackgroundColor	Cor de fundo de diálogos e pop-ups.
dialogBorderColor	Cor da borda de diálogos e pop-ups.

---

Idioma

Android

O idioma segue a localidade do dispositivo sem configuração adicional.

iOS

Configure Localizações e CFBundleLocalizations no Xcode:

• Adicionando suporte para idiomas e regiões
• CFBundleLocalizations

Depois dessas configurações, o SDK usa o idioma do dispositivo.

---

Ofuscação de código

Adicione as seguintes regras do ProGuard/R8 ao android/app/proguard-rules.pro para que o SDK e suas dependências continuem funcionando após a ofuscação.

proguard-rules.pro

# Regras do ProGuard/R8 do Flutter para o Caf SDK
# Estas regras garantem que o plugin CAF SDK funcione corretamente em builds de release

# O pré-handler do Android para exceções é carregado por reflexão (via ServiceLoader).
-keep class kotlinx.coroutines.experimental.android.AndroidExceptionPreHandler { *; }

### GSON ##################################################################
-keepattributes Signature
-keepattributes *Annotation*
### FIM GSON ##################################################################

### Retrofit ##################################################################
-keepattributes Signature, InnerClasses, EnclosingMethod
-keepattributes RuntimeVisibleAnnotations, RuntimeVisibleParameterAnnotations
-keepattributes AnnotationDefault
-keepclassmembers,allowshrinking,allowobfuscation interface * {
    @retrofit2.http.* <methods>;
}
-dontwarn org.codehaus.mojo.animal_sniffer.IgnoreJRERequirement
-dontwarn javax.annotation.**
-dontwarn kotlin.Unit
-dontwarn retrofit2.KotlinExtensions
-dontwarn retrofit2.KotlinExtensions$*
-if interface * { @retrofit2.http.* <methods>; }
-keep,allowobfuscation interface <1>
-if interface * { @retrofit2.http.* <methods>; }
-keep,allowobfuscation interface * extends <1>
-keep,allowobfuscation,allowshrinking class kotlin.coroutines.Continuation
-if interface * { @retrofit2.http.* public *** *(...); }
-keep,allowoptimization,allowshrinking,allowobfuscation class <3>
-keep,allowobfuscation,allowshrinking class retrofit2.Response
### FIM Retrofit ##############################################################

### OkHttp ####################################################################
-dontwarn javax.annotation.**
-adaptresourcefilenames okhttp3/internal/publicsuffix/PublicSuffixDatabase.gz
-dontwarn org.codehaus.mojo.animal_sniffer.*
-dontwarn okhttp3.internal.platform.**
-dontwarn org.conscrypt.**
-dontwarn org.bouncycastle.**
-dontwarn org.openjsse.**
-keep class okhttp3.** { *; }
-dontwarn okhttp3.**
-keep class okio.** { *; }
-dontwarn okio.**
-dontwarn javax.annotation.Nullable
-dontwarn javax.annotation.ParametersAreNonnullByDefault
### FIM OkHttp ################################################################

### Serialização Kotlin ######################################################
-if @kotlinx.serialization.Serializable class **
-keepclassmembers class <1> {
    static <1>$Companion Companion;
}
-if @kotlinx.serialization.Serializable class ** {
    static **$* *;
}
-keepclassmembers class <2>$<3> {
    kotlinx.serialization.KSerializer serializer(...);
}
-if @kotlinx.serialization.Serializable class ** {
    public static ** INSTANCE;
}
-keepclassmembers class <1> {
    public static <1> INSTANCE;
    kotlinx.serialization.KSerializer serializer(...);
}
-keepclassmembers class kotlinx.serialization.json.** {
    *** Companion;
}
-keepclasseswithmembers class kotlinx.serialization.json.** {
    kotlinx.serialization.KSerializer serializer(...);
}
-keepclassmembers @kotlinx.serialization.Serializable class packeage.** {
    *** Companion;
    *** INSTANCE;
    kotlinx.serialization.KSerializer serializer(...);
}
### FIM Serialização Kotlin #################################################

### AutoValue ################################################################
-dontwarn com.google.auto.**
-dontwarn autovalue.shaded.com.**
-dontwarn sun.misc.Unsafe
-dontwarn javax.lang.model.element.Modifier
### FIM AutoValue ############################################################

### Plugin do Flutter ###########################################################
-keep class io.flutter.plugins.** { *; }
-keep class * extends io.flutter.plugin.common.MethodChannel$MethodCallHandler { *; }
-keep class * extends io.flutter.plugin.common.MethodChannel$Result { *; }
-keep class io.flutter.plugins.GeneratedPluginRegistrant { *; }
-keep class io.caf.sdk.flutter.** { *; }
### FIM Plugin do Flutter #######################################################

### CAF - Combate a Fraude ######################################################
-keepattributes Exceptions
-keep class com.caf.facelivenessiproov.** { *; }
-keep class com.combateafraude.documentdetector.** { *; }
-keep class com.combateafraude.** { *; }
-keep interface com.combateafraude.** { *; }
-keep class io.caf.** { *; }
-keep interface io.caf.** { *; }
-keepclassmembers class com.combateafraude.** { *; }
-dontwarn java.nio.file.*
-dontwarn com.squareup.okhttp.internal.Platform
-keepclassmembers class * extends com.google.crypto.tink.shaded.protobuf.GeneratedMessageLite {
  <fields>;
}
-keep class org.tensorflow.** { *; }
-keep class org.tensorflow.**$* { *; }
-dontwarn org.tensorflow.**
-keep public class com.iproov.sdk.IProov { public *; }
-keep class com.iproov.** { *; }
-keep class com.iproov.**$* { *; }
-keep class com.google.protobuf.** { *; }
-keep class com.google.protobuf.**$* { *; }
-dontwarn com.google.protobuf.**
-dontwarn java.util.concurrent.Flow*
-keep class kotlin.** { *; }
-keep class kotlinx.** { *; }
-keep class br.com.fortface.** { *; }
-keep interface br.com.fortface.** { *; }
-keepclassmembers class br.com.fortface.** { *; }
-keepclassmembers class br.com.fortface.**$* { *; }
-keep class org.json.** { *; }
-keepclassmembers class org.json.** { *; }
-keepclassmembers class * {
    @org.json.** *;
}
-dontwarn br.com.fortface.**
-dontwarn com.android.tools.lint.**
-dontwarn io.caf.sdk.common.jvmshared.lint.**
### FIM CAF - Combate a Fraude ##################################################

---

Próximos passos

Face LivenessDocument Detector