> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/caf-sdk/caf-sdk-pt-br/flutter/installation-guide.md). # 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. {% hint style="warning" %} 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](https://docs.caf.io/caf-sdk/flutter/getting-started-with-the-sdk). {% endhint %} ## 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](https://github.com/combateafraude/caf-sdk-flutter-exemple) 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 ```sh flutter pub add caf_sdk ``` A versão do pacote publicada é **2.4.0**. Importe a API Certta DevX com: ```dart import 'package:caf_sdk/certta_sdk.dart'; ``` {% hint style="info" %} 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](/caf-sdk/caf-sdk-pt-br/flutter/migrating-from-cafsdk.md). {% endhint %} ### 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: {% hint style="info" %} Se você omitir este arquivo, todos os módulos serão ativados por padrão e **`iproov-lite`** é usado como provedor de Face Liveness. {% endhint %} ```json { "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: ```json { "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. {% hint style="warning" %} 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. {% endhint %} **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): {% tabs %} {% tab title="Kotlin Script" %} ```kotlin repositories { maven { url = uri("https://repo.combateafraude.com/android/release") } } ``` {% endtab %} {% tab title="Groovy" %} ```groovy repositories { maven { url "https://repo.combateafraude.com/android/release" } } ``` {% endtab %} {% endtabs %} ### Etapa 4: configuração do iOS Navegue até o `diretório ios/` do seu projeto Flutter e execute: ```sh 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 | {% hint style="info" %} O Document Detector requer `READ_EXTERNAL_STORAGE` quando o envio de documentos está ativado. {% endhint %} ### 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: {% content-ref url="/pages/350b53d9674174220c34ca357260b91ef975ad64" %} [Autenticação](/caf-sdk/caf-sdk-pt-br/authentication.md) {% endcontent-ref %} Inicialize o Certta assim que tiver um token móvel válido (JWT) e o ID do usuário — normalmente após o login: ```dart 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](#color-theming). | {% hint style="info" %} `configureSdk` lança uma `PlatformException` com o código `BRIDGE_EXCEPTION` quando o mapeador nativo rejeita a configuração. {% endhint %} ### 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: ```dart await certta.updateUserId('novo-id-do-usuario'); await certta.updateMobileToken('novo-jwt-token'); ``` {% hint style="warning" %} 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. {% endhint %} ### Logs Os logs do pipeline do SDK são emitidos em `CerttaSdk.logStream`: ```dart 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`. ```dart 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', ), ), ); ``` {% hint style="info" %} Todos os campos de cor são opcionais. Substitua apenas as cores de que você precisa. {% endhint %} | 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](https://developer.apple.com/documentation/xcode/adding-support-for-languages-and-regions) * [CFBundleLocalizations](https://developer.apple.com/documentation/bundleresources/information-property-list/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. {% code title="proguard-rules.pro" expandable="true" %} ``` # 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.* ; } -dontwarn org.codehaus.mojo.animal_sniffer.IgnoreJRERequirement -dontwarn javax.annotation.** -dontwarn kotlin.Unit -dontwarn retrofit2.KotlinExtensions -dontwarn retrofit2.KotlinExtensions$* -if interface * { @retrofit2.http.* ; } -keep,allowobfuscation interface <1> -if interface * { @retrofit2.http.* ; } -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 { ; } -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 ################################################## ``` {% endcode %} *** ## Próximos passos {% content-ref url="/pages/27eb4d45188aecea60770da2e140e2268d279a61" %} [Face Liveness](/caf-sdk/caf-sdk-pt-br/flutter/face-liveness.md) {% endcontent-ref %} {% content-ref url="/pages/f9c21688ee93566696de0e14a6be2ee1e3252082" %} [Document Detector](/caf-sdk/caf-sdk-pt-br/flutter/document-detector.md) {% endcontent-ref %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.caf.io/caf-sdk/caf-sdk-pt-br/flutter/installation-guide.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.