4 - Customização
Configure tema, cores, animações, teclado PIN, tela de erros e volume do beep no SDK Tap on Phone.
Configure a aparência visual e o comportamento do SDK Tap on Phone personalizando cores, animações, teclado PIN, tela de erros, volume do beep e timeouts.
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.
Personalize cores de fundo, textos e espaçamentos.
Configure animações Lottie para leitura de cartão.
Altere o tipo de exibição do teclado PIN.
Customize ícones, cores e botões da tela de erro.
Configure o volume do som de leitura do cartão.
Defina tempos limites para cada etapa do pagamento.
Configuração de atributos de tela
A imagem abaixo ilustra os elementos da tela que podem ser personalizados através do TapOnPhoneTheme:

Mapeamento dos atributos customizáveis na tela de pagamento
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 alphaO 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
.jsonda animação dentro da pastaapp/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:

Tela de erros padrão do SDK
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
backButtonsó será exibido seisVisibleestiver comotrue.
Volume do Beep
Configure o volume do som emitido pelo dispositivo durante a leitura do cartão através do objeto BeepVolumeConfig, passado no SdkConfig.
data class BeepVolumeConfig(
val beepVolume: Float // Valor entre 0.0f e 1.0f
)| Propriedade | Tipo | Descrição | Intervalo |
|---|---|---|---|
beepVolume | Float | Nível de volume do beep de leitura | 0.0f a 1.0f |
0.0f— Mudo (sem som)0.5f— 50% do volume1.0f— Volume máximo
Exemplo
val beepVolumeConfig = BeepVolumeConfig(
beepVolume = 0.5f // 50% do volume
)
val sdkConfig = SdkConfig(
beepVolume = beepVolumeConfig
)
TapOnPhone.setConfig(ConfigParameters(..., sdkConfig = sdkConfig))Configurações de Timeout
Configure os tempos limites para diferentes etapas do processo de pagamento através do objeto TimeoutConfig, passado no SdkConfig.
data class TimeoutConfig(
val discoveryTimeout: Int? = null,
val processingTimeout: Int? = null,
val networkTimeout: Int? = null,
val totalElapsedTimeout: Int? = null
)Todos os valores são em milissegundos. Parâmetros não informados utilizam o valor padrão.
| Parâmetro | Descrição | Padrão | Mín. | Máx. |
|---|---|---|---|---|
discoveryTimeout | Tempo máximo para detecção/leitura do cartão (aproximação) | 120.000 | 5.000 | 120.000 |
processingTimeout | Tempo máximo para processamento da transação após leitura | 30.000 | 5.000 | 120.000 |
networkTimeout | Tempo máximo para requisições de rede | 45.000 | 5.000 | 45.000 |
totalElapsedTimeout | Tempo total máximo para todo o fluxo de pagamento | 180.000 | 30.000 | 180.000 |
Exemplo
val timeoutConfig = TimeoutConfig(
discoveryTimeout = 30_000, // 30 segundos para ler o cartão
processingTimeout = 20_000 // 20 segundos para processar
)
val sdkConfig = SdkConfig(
timeout = timeoutConfig
)
TapOnPhone.setConfig(ConfigParameters(..., sdkConfig = sdkConfig))Updated 28 minutes ago
