Customização

Configure a aparência visual do SDK Tap on Phone personalizando cores, animações, teclado PIN e tela de erros através do objeto TapOnPhoneTheme.

Configuração de Tema

A configuração visual é feita através do objeto TapOnPhoneTheme, que deve ser passado no objeto SdkConfig e aplicado via TapOnPhone.setConfig.

Cores e Layout

Personalize cores de fundo, textos e espaçamentos.

Animações

Configure animações Lottie para leitura de cartão.

Teclado PIN

Altere o tipo de exibição do teclado PIN.

Configuração de atributos de tela

A imagem abaixo ilustra os elementos da tela que podem ser personalizados através do TapOnPhoneTheme:

O TapOnPhoneTheme é um data class com todas as propriedades de personalização visual:

data class TapOnPhoneTheme(
    val logo: Drawable? = null,
    val backgroundColor: Int? = null,
    val footerBackgroundColor: Int? = null,
    val amountTextColor: Int? = null,
    val paymentTypeTextColor: Int? = null,
    val statusTextColor: Int? = null,
    val cardAnimation: Int? = null,
    val cardAnimationResources: Map<CardAnimationType, Int>? = null,
    val cardAnimationArrangement: CardAnimationArrangement = CardAnimationArrangement.MIDDLE,
    val cardAnimationSize: Int? = null,
    val brandBackgroundColor: String? = null,
    val pinPadType: PinPadType? = PinPadType.STANDARD,
    val marginTopDPStatusMessages: Float? = null,
    val headerTextContent: HeaderTextContent? = null,
    val marginTopDPAmount: Float? = null,
    val marginTopDPPaymentType: Float? = 8f,
    val topCancelIcon: Drawable? = null,
    val statusBarColor: Int? = null
)

Propriedades do tema

Propriedade	Tipo	Descrição	Padrão (quando `null`)
`logo`	`Drawable?`	Logo exibido na parte superior direita da tela	Sem logo
`backgroundColor`	`Int?`	Cor de fundo da tela	`android:colorBackground` do tema
`footerBackgroundColor`	`Int?`	Cor de fundo da área de informações de pagamento	`android:colorBackground` do tema
`amountTextColor`	`Int?`	Cor do texto de valor	`android:textColor`
`paymentTypeTextColor`	`Int?`	Cor do texto de método de pagamento	`android:textColor`
`statusTextColor`	`Int?`	Cor do texto de status	`android:textColor`
`cardAnimation`	`Int?`	Loader em formato JSON (Lottie)	`R.raw.card_animation`
`cardAnimationResources`	`Map<CardAnimationType, Int>`	Recursos de animação por tipo	`mapOf(AnimType => R.raw.anim)`
`cardAnimationArrangement`	`CardAnimationArrangement`	Posicionamento vertical do loader	`CardAnimationArrangement.MIDDLE`
`brandBackgroundColor`	`String?`	Cor de fundo da tela de animação Visa	`0x1434CB`
`pinPadType`	`PinPadType?`	Tipo de exibição do teclado PIN	`PinPadType.STANDARD`
`marginTopDPStatusMessages`	`Float?`	Margem entre `cardAnimation` e texto de status	`android:layout_marginTop`
`marginTopDPAmount`	`Float?`	Margem superior do texto de valor	`android:layout_marginTop`
`marginTopDPPaymentType`	`Float?`	Margem entre texto de valor e método de pagamento	`8dp`
`topCancelIcon`	`Drawable?`	Ícone de cancelamento no canto superior direito	Ícone default do SDK
`headerTextContent`	`HeaderTextContent?`	Conteúdo e configurações dos textos no header	—
`statusBarColor`	`Int?`	Cor de fundo da Status Bar	Cor default do sistema

HeaderTextContent

As propriedades title e subtitle utilizam a estrutura TextConfiguration para definir conteúdo e estilo.

Propriedade	Tipo	Descrição
`title`	`TextConfiguration?`	Configuração do texto de título
`subtitle`	`TextConfiguration?`	Configuração do texto de subtítulo
`updateFromEvents`	`Boolean?`	Habilita a atualização dos textos com o status (`true` ou `false`)

TextConfiguration

Propriedade	Tipo	Descrição	Padrão
`marginTop`	`Float?`	Margem superior do texto	`android:layout_marginTop`
`text`	`String?`	Conteúdo do texto	`android:text`
`textColor`	`Int?`	Cor do texto	`android:textColor`
`fontSize`	`Int?`	Tamanho da fonte	`android:fontSize`

Como configurar cores válidas para o tema

Os parâmetros backgroundColor, footerBackgroundColor, amountTextColor, paymentTypeTextColor e statusTextColor devem ser passados como valores inteiros no formato hexadecimal ou RGB.

Métodos disponíveis para definir cores:

Color.parseColor("#FF000000")   // Hexadecimal com alpha
0xFF000000.toInt()              // Hex literal convertido para Int
Color.rgb(255, 0, 0)           // RGB sem alpha
Color.argb(255, 255, 0, 0)     // ARGB com alpha

O SDK aceita dois formatos hexadecimais:

Formato	Descrição	Exemplo
`#AARRGGBB`	Com transparência (Alpha). `FF` = opaco, `00` = transparente	`#FF000000` (preto opaco)
`#RRGGBB`	Sem transparência (sempre opaco)	`#000000` (preto)

TapOnPhoneTheme(
    backgroundColor = Color.parseColor("#FFFFFFFF"),
    amountTextColor = Color.parseColor("#000000"),
    paymentTypeTextColor = Color.parseColor("#FFFF0000"),
    statusTextColor = Color.parseColor("#FF000000"),
    statusBarColor = Color.parseColor("#FF7300")
)

Customizar animação de ativação do terminal (cardAnimationResources)

⚠️
O recurso de animação deve ser um arquivo JSON no formato Lottie.

TapOnPhoneTheme(
    //...
    cardAnimationResources = mapOf(
        CardAnimationType.StartActiveTerminal to R.raw.start_activate_terminal,
        CardAnimationType.CompleteActiveTerminal to R.raw.complete_activate_terminal,
    ),
    messagesEventStatus = mapOf(
        MessagesEventStatus.StartActiveTerminal to MessageEvent(
            title = "Ativando o terminal",
            subtitle = "Por favor, aguarde..."
        ),
    )
    //...
)

Load na tela de pedir a leitura do cartão (cardAnimation)

Para adicionar uma animação durante o processo de leitura de cartão:

Adicione a biblioteca Lottie no build.gradle:

dependencies {
    implementation 'com.airbnb.android:lottie:$lottieVersion'
}

Coloque o arquivo .json da animação dentro da pasta app/res/raw.
Atribua o caminho do arquivo ao atributo cardAnimation:

TapOnPhoneTheme(
    cardAnimation = R.raw.card_animation
)

🎨
O SDK não aplica a cor do tema na animação (loader). Crie a animação com as cores desejadas diretamente no arquivo Lottie.

Posicionamento da animação na tela

Ajuste o posicionamento vertical da animação com o atributo cardAnimationArrangement:

// Anexada ao topo, logo abaixo da logo e do botão de cancelar
val topWithoutMargin = CardAnimationArrangement.TOP()

// Anexada ao topo com margem customizável (em dp)
val topWithMargin = CardAnimationArrangement.TOP(64)

// Centralizada no espaço livre (padrão)
val middle = CardAnimationArrangement.MIDDLE

// Anexada ao rodapé, logo acima do footer com o valor
val bottomWithoutMargin = CardAnimationArrangement.BOTTOM()

// Anexada ao rodapé com margem customizável (em dp)
val bottomWithMargin = CardAnimationArrangement.BOTTOM(64)

Animação anexada ao topo, sem margem.

Customização do teclado PIN (pinPadType)

Altere o tipo de exibição do teclado PIN atribuindo o valor desejado ao atributo pinPadType:

TapOnPhoneTheme(
    pinPadType = PinPadType.SHUFFLED
)

Tipo	Descrição
`PinPadType.STANDARD`	Teclado numérico na ordem padrão (1-9, 0)
`PinPadType.SHUFFLED`	Teclas numéricas embaralhadas aleatoriamente
`PinPadType.SHIFTED`	Teclas numéricas deslocadas

Configurando a tela de erros

Personalize a tela de erro através do objeto ErrorScreenConfiguration:

data class ErrorScreenConfiguration(
    var backIconConfiguration: BackIconConfiguration? = null,
    var screenBackgroundColor: Int? = null,
    var errorAnimation: Int? = null,
    var errorCodeTextStyle: ErrorCodeTextStyle? = null,
    var errorMessageTextStyle: ErrorMessageTextStyle? = null,
    var backButtonConfiguration: BackButtonConfiguration? = null
)

Estruturas auxiliares da tela de erros

data class BackIconConfiguration(
    val icon: Drawable? = null,
    val isVisible: Boolean? = true,
)

data class ErrorCodeTextStyle(
    val textColor: Int? = null,
    val fontSize: Int? = null,
)

data class ErrorMessageTextStyle(
    val text: String? = null,
    val textColor: Int? = null,
    val fontSize: Int? = null,
)

data class BackButtonConfiguration(
    val text: String? = null,
    val containerColor: Int? = null,
    val contentColor: Int? = null,
    val isVisible: Boolean? = false,
)

Propriedades da tela de erros

Propriedade	Tipo	Descrição	Padrão
`backIconConfiguration`	`BackIconConfiguration`	Ícone exibido no canto superior esquerdo	Ícone padrão do SDK, visível
`screenBackgroundColor`	`Int?`	Cor de fundo da tela de erro	`0xFFFFFFFF` (branco)
`errorAnimation`	`Int?` (JSON)	Animação Lottie de erro	Animação padrão do SDK
`errorCodeTextStyle`	`ErrorCodeTextStyle`	Estilo do texto do código de erro	`textColor: 0xFF000000`, `fontSize: 24.sp`
`errorMessageTextStyle`	`ErrorMessageTextStyle`	Estilo do texto da mensagem de erro	Texto padrão do SDK, `textColor: 0xFF000000`, `fontSize: 22.sp`
`backButtonConfiguration`	`BackButtonConfiguration`	Configuração do botão de retorno	`text: "Try again"`, `containerColor: 0xFF3700B3`, `contentColor: 0xFFFFFFFF`, `isVisible: false`

Exemplo completo

TapOnPhoneTheme(
    errorScreenConfiguration = ErrorScreenConfiguration(
        backIconConfiguration = BackIconConfiguration(
            icon = getDrawable(R.drawable.ic_arrow_back_24),
            isVisible = false
        ),
        screenBackgroundColor = Color.parseColor("#FFBFBFBF"),
        errorCodeTextStyle = ErrorCodeTextStyle(
            textColor = Color.parseColor("#FF8B0000"),
            fontSize = 26
        ),
        errorMessageTextStyle = ErrorMessageTextStyle(
            textColor = Color.parseColor("#FF000000"),
            fontSize = 24
        ),
        backButtonConfiguration = BackButtonConfiguration(
            isVisible = true,
            text = getString(R.string.return_to_home),
            containerColor = Color.parseColor("#FF8B0000"),
            contentColor = Color.parseColor("#FFFFFFFF")
        ),
    ),
)

💡
Todos os parâmetros são opcionais. Se não forem especificados, o SDK aplica as configurações padrão. O backButton só será exibido se isVisible estiver como true.