> ## Documentation Index
> Fetch the complete documentation index at: https://docs-platform.services-valid.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Customização

> Personalize a aparência da UI do FaceTec v10 no Android via LivenessFacetecSDKCustomization

A UI da captura é renderizada pelo próprio FaceTec SDK. Você consegue personalizá-la passando um `LivenessFacetecSDKCustomization` em `LivenessFacetecSDKConfig`. Cada propriedade é um espelho tipado da customização correspondente do FaceTec — quando você define um campo, ele é aplicado; quando deixa `null`, o FaceTec usa o padrão.

## Estrutura geral

```kotlin theme={"theme":"catppuccin-latte"}
import com.vcc.vendor.facetec.sdk.LivenessFacetecSDK
import com.vcc.vendor.facetec.sdk.models.LivenessFacetecSDKConfig
import com.vcc.vendor.facetec.sdk.models.LivenessFacetecSDKCustomization

val customization = LivenessFacetecSDKCustomization(
    cancelButton = /* CancelButtonCustomization */ null,
    feedback = /* FeedbackCustomization */ null,
    frame = /* FrameCustomization */ null,
    guidance = /* GuidanceCustomization */ null,
    initialLoadingAnimation = /* InitialLoadingAnimationCustomization */ null,
    oval = /* OvalCustomization */ null,
    overlay = /* OverlayCustomization */ null,
    orientationScreen = /* OrientationScreenCustomization */ null,
    resultScreen = /* ResultScreenCustomization */ null,
    vocalGuidance = /* VocalGuidanceCustomization */ null,
    messages = /* MessagesCustomization */ null,
    securityWatermarkImage = /* SecurityWatermarkImage */ null,
    // ... ver tabela abaixo
)

LivenessFacetecSDK.init(
    application = application,
    config = LivenessFacetecSDKConfig(customization = customization)
)
```

## Sub-customizações disponíveis

| Propriedade                        | Tipo                                    | O que controla                                                                       |
| ---------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------ |
| `cancelButton`                     | `CancelButtonCustomization?`            | Imagem, posição e visibilidade do botão de cancelar                                  |
| `feedback`                         | `FeedbackCustomization?`                | Cores, fonte e animação da barra de mensagens                                        |
| `frame`                            | `FrameCustomization?`                   | Cor de fundo, borda e cantos arredondados do frame                                   |
| `guidance`                         | `GuidanceCustomization?`                | Telas de "pronto" e "tente novamente" e seus botões                                  |
| `initialLoadingAnimation`          | `InitialLoadingAnimationCustomization?` | Animação inicial de carregamento ("Securing Camera")                                 |
| `messages`                         | `MessagesCustomization?`                | Sobrescreve os textos de resultado, feedback e retry do FaceTec                      |
| `orientationScreen`                | `OrientationScreenCustomization?`       | Tela exibida quando o dispositivo está em orientação não suportada                   |
| `oval`                             | `OvalCustomization?`                    | Cores e largura do oval guia e do indicador de progresso                             |
| `overlay`                          | `OverlayCustomization?`                 | Cor de fundo do overlay e imagem de marca                                            |
| `resultScreen`                     | `ResultScreenCustomization?`            | Animações e cores da tela de resultado                                               |
| `vocalGuidance`                    | `VocalGuidanceCustomization?`           | Modo de guia por voz e arquivos de áudio                                             |
| `securityWatermarkImage`           | `SecurityWatermarkImage?`               | Marca-d'água de segurança exibida durante a captura                                  |
| `exitAnimationSuccessCustom`       | `ExitAnimationStyle?`                   | Animação de saída em caso de sucesso                                                 |
| `exitAnimationUnsuccessCustom`     | `ExitAnimationStyle?`                   | Animação de saída em caso de falha                                                   |
| `exitAnimationSuccessResourceID`   | `Int?`                                  | Recurso `R.anim` da animação de sucesso (alternativa a `exitAnimationSuccessCustom`) |
| `exitAnimationUnsuccessResourceID` | `Int?`                                  | Recurso `R.anim` da animação de falha                                                |
| `activityThemeId`                  | `Int?`                                  | ID do tema Android aplicado à Activity da captura                                    |

## Temas alternativos

Além de `customization`, o `LivenessFacetecSDKConfig` aceita dois temas completos que a FaceTec aplica automaticamente conforme a condição do ambiente — ambos do mesmo tipo `LivenessFacetecSDKCustomization?`:

| Campo                         | Quando é aplicado                  |
| ----------------------------- | ---------------------------------- |
| `lowLightCustomization`       | Ambientes de pouca luz             |
| `dynamicDimmingCustomization` | Durante o dimming dinâmico da tela |

Se não forem definidos, a FaceTec usa o tema principal também nessas condições.

<Warning>
  `activityThemeId` e `messages` só têm efeito quando definidos em `customization` (o slot principal). A FaceTec expõe ambos como um único valor por processo, então os mesmos campos em `lowLightCustomization`/`dynamicDimmingCustomization` são **ignorados silenciosamente** — sem erro em tempo de build ou de execução.
</Warning>

## Enums de customização

**`CancelButtonLocation`**

| Valor       | Comportamento                             |
| ----------- | ----------------------------------------- |
| `TOP_LEFT`  | Botão cancelar no canto superior esquerdo |
| `TOP_RIGHT` | Botão cancelar no canto superior direito  |
| `CUSTOM`    | Posição customizada                       |
| `DISABLED`  | Botão cancelar oculto                     |

**`SecurityWatermarkImage`**

| Valor                | Comportamento                     |
| -------------------- | --------------------------------- |
| `FACETEC_ZOOM`       | Marca-d'água "FaceTec Zoom"       |
| `FACETEC`            | Marca-d'água "FaceTec"            |
| `FACETEC_POWERED_BY` | Marca-d'água "Powered by FaceTec" |

**`ExitAnimationStyle`** — usado em `exitAnimationSuccessCustom`/`exitAnimationUnsuccessCustom`

| Valor        |
| ------------ |
| `RIPPLE_OUT` |
| `RIPPLE_IN`  |
| `NONE`       |

**`VocalGuidanceMode`** — usado em `vocalGuidance.mode`

| Valor                    |
| ------------------------ |
| `MINIMAL_VOCAL_GUIDANCE` |
| `FULL_VOCAL_GUIDANCE`    |
| `NO_VOCAL_GUIDANCE`      |

## Exemplo: cores básicas e cancelamento no canto superior esquerdo

```kotlin theme={"theme":"catppuccin-latte"}
import android.graphics.Color
import com.vcc.vendor.facetec.sdk.models.LivenessFacetecSDKCustomization
import com.vcc.vendor.facetec.sdk.models.customization.CancelButtonCustomization
import com.vcc.vendor.facetec.sdk.models.customization.CancelButtonLocation
import com.vcc.vendor.facetec.sdk.models.customization.FrameCustomization
import com.vcc.vendor.facetec.sdk.models.customization.OvalCustomization

val customization = LivenessFacetecSDKCustomization(
    cancelButton = CancelButtonCustomization(
        location = CancelButtonLocation.TOP_LEFT,
        hideForCameraPermissions = false
    ),
    frame = FrameCustomization(
        backgroundColor = Color.WHITE,
        borderColor = Color.parseColor("#B72819"),
        borderWidth = 2,
        cornerRadius = 16
    ),
    oval = OvalCustomization(
        strokeColor = Color.parseColor("#B72819"),
        progressColor1 = Color.parseColor("#B72819"),
        progressColor2 = Color.parseColor("#e9454b")
    )
)
```

## Boas práticas

<Warning>
  Mudanças visuais profundas no fluxo do FaceTec precisam respeitar as diretrizes de marca da própria FaceTec — em especial, **a marca-d'água de segurança** (`securityWatermarkImage`) **não deve ser ocultada** sob risco de violar o contrato de uso do motor.
</Warning>

* **Mantenha contraste suficiente** entre o oval guia e o fundo para preservar a acessibilidade.
* **Evite fontes muito pequenas** em `guidance.headerFont`/`subtextFont` — o FaceTec já balanceia tamanhos para legibilidade em câmeras frontais.
* **Teste em devices com tela curta** (relação \~16:9) — alguns elementos posicionados manualmente (como `cancelButton.customLocation`) podem sobrepor o oval.
* **Reuse o mesmo `LivenessFacetecSDKCustomization`** entre o `init` e chamadas subsequentes; trocar a customização exige `stop()` seguido de um novo `init()`.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Implementação" icon="code" iconType="regular" href="/plataforma/liveness/facetec/v10/sdk/android/implementacao">
    Veja como passar a customização no `init`
  </Card>

  <Card title="Solução de problemas" icon="wrench" iconType="regular" href="/plataforma/liveness/facetec/v10/sdk/android/troubleshooting">
    Diagnostique problemas com cores, fontes e recursos
  </Card>
</CardGroup>