4 - Customização

Configure o TapOnPhoneTheme para personalizar mensagens, views, cores e o estilo de transição da experiência de Tap iOS.

O tema padrão segue a mesma base visual da view proprietária de leitura de cartão da Apple para manter uma transição visual mais fluida durante o pagamento.

Antes de começar

Importe Foundation e SwiftUI no arquivo em que você criará o tema.
Defina quais ApplicationEvent (eventos que representam cada etapa do fluxo) precisam de texto customizado.
Decida se você manterá o ProgressView padrão ou se exibirá uma View própria em etapas específicas.

Estrutura padrão do tema

O tema padrão usa o esquema abaixo:

import Foundation
import SwiftUI

public struct TapOnPhoneTheme {
    let stepMessages: [ApplicationEvent: String]
    let stepViews: [ApplicationEvent: AnyView]
    let textColor: Color
    let loadingColor: Color
    let backgroundColor: Color
    let gradientStops: [Gradient.Stop]
    let screenTransitionStyle: SdkScreenTransitionStyle

    public init(
        stepMessages: [ApplicationEvent : String] = [
            .terminalActivationStarted: "Iniciando",
            .authorizingPleaseWait: "Aguardando autorização",
            .transactionAborted: "Operação cancelada",
            .terminalActivationFinished: "Inicialização concluída",
            .cardReadingFinished: "Leitura concluída",
            .paymentProcessFinished: "Processamento concluído",
            .holdCardSteady: "Processando",
            .sessionActivationStarted: "Iniciando sessão",
            .zoopActivationStarted: "Autenticando",
            .zoopActivationSucceeded: "Autenticado",
            .cardReadingStarted: "Processando",
            .closeBuiltInScreen: "Processando",
            .pinInputStarted: "Digite o PIN",
            .pinInputFinished: "PIN confirmado",
            .kernelUpdateProgress(0): "Atualizando Kernel",
        ],
        stepViews: [ApplicationEvent : AnyView] = [:],
        textColor: Color = .white,
        loadingColor: Color = .white,
        backgroundColor: Color = .white,
        gradientStops: [Gradient.Stop] = [
            .init(color: .black.opacity(0.8), location: 0.0),
            .init(color: .black.opacity(0.75), location: 0.39),
            .init(color: .black.opacity(0.65), location: 0.61),
            .init(color: .black.opacity(0.35), location: 0.83),
            .init(color: .black.opacity(0), location: 1.0),
        ],
        screenTransitionStyle: SdkScreenTransitionStyle = .coverVertical
    ) {
        self.stepMessages = stepMessages
        self.stepViews = stepViews
        self.textColor = textColor
        self.loadingColor = loadingColor
        self.backgroundColor = backgroundColor
        self.gradientStops = gradientStops
        self.screenTransitionStyle = screenTransitionStyle
    }
}

Configurações disponíveis

Parâmetro	Descrição
`stepMessages`	Mapa de textos. Cada `ApplicationEvent` pode ter uma mensagem customizada associada.
`stepViews`	Mapa de `View`. Cada `ApplicationEvent` pode ter uma `View` própria. Se você não informar nenhuma (`[:]`), o fluxo usa um `ProgressView` por padrão.
`textColor`	Cor dos textos exibidos na interface.
`loadingColor`	Cor da view de carregamento padrão.
`backgroundColor`	Cor base de fundo da interface.
`gradientStops`	Fundo da view. Para usar uma cor sólida, passe apenas um `Gradient.Stop` com `location: 0.0`.
`screenTransitionStyle`	Define a animação usada para exibir a tela built-in do SDK durante etapas de loading e processamento.

1. Crie um tema com o padrão do SDK

Se você quer manter o comportamento visual padrão, crie a instância sem sobrescrever parâmetros.

let theme = TapOnPhoneTheme()

Esse formato já entrega:

mensagens padrão para os principais eventos;
ProgressView como view de carregamento padrão;
texto branco;
indicador branco;
fundo em gradiente escuro.

2. Customize as mensagens por evento

Use stepMessages para trocar os textos exibidos em cada etapa do fluxo.

import Foundation
import SwiftUI

let theme = TapOnPhoneTheme(
    stepMessages: [
        .terminalActivationStarted: "Preparando Tap",
        .authorizingPleaseWait: "Validando pagamento",
        .pinInputStarted: "Digite sua senha",
        .pinInputFinished: "Senha confirmada",
        .transactionAborted: "Pagamento cancelado",
        .kernelUpdateProgress(0): "Atualizando Kernel"
    ]
)

Quando você configura .kernelUpdateProgress(0), nós inserimos a porcentagem automaticamente até ("100%").

3. Optional: mostre uma view própria em etapas específicas

Use stepViews quando você quiser trocar o carregamento padrão por uma interface customizada em um evento específico.

import Foundation
import SwiftUI

let theme = TapOnPhoneTheme(
    stepViews: [
        .authorizingPleaseWait: AnyView(
            VStack(spacing: 12) {
                ProgressView()
                    .tint(.white)

                Text("Validando pagamento")
                    .font(.headline)
                    .foregroundColor(.white)
            }
            .padding()
        )
    ]
)

Se você não informar nenhuma view para um evento, o SDK continua usando ProgressView.

4. Ajuste as cores do texto, do loading e do fundo

Use textColor, loadingColor, backgroundColor e gradientStops para alinhar o visual da experiência ao seu app.

import Foundation
import SwiftUI

let theme = TapOnPhoneTheme(
    textColor: .white,
    loadingColor: .white,
    backgroundColor: .black,
    gradientStops: [
        .init(color: Color.black.opacity(0.90), location: 0.0),
        .init(color: Color.black.opacity(0.70), location: 0.55),
        .init(color: Color.black.opacity(0.15), location: 1.0)
    ]
)

Prefira combinações com bom contraste para manter a leitura clara em todas as etapas do pagamento.

5. Optional: defina o estilo de transição da tela built-in

Use screenTransitionStyle para controlar como a tela built-in do SDK entra e sai durante as etapas de loading e processamento.

Opção	Descrição
`.coverVertical`	Tela entra de baixo para cima. É o comportamento padrão de apresentação do iOS.
`.flipHorizontal`	Tela entra com animação de flip horizontal.
`.fromLeft`	Tela entra da esquerda para a direita.
`.fromRight`	Tela entra da direita para a esquerda.
`.fromTop`	Tela entra de cima para baixo.
`.none`	A tela aparece e some sem animação.

import Foundation
import SwiftUI

let theme = TapOnPhoneTheme(
    transitionStyle: .fromRight
)

Prefira estilos de transição mais discretos em fluxos de pagamento. Se a sua interface já usa animações laterais, .fromRight`` ou .fromLeft` podem deixar a navegação mais consistente.

Optional: use uma cor sólida no fundo

Se você não quiser gradiente, passe apenas um Gradient.Stop com location: 0.0.

import Foundation
import SwiftUI

let theme = TapOnPhoneTheme(
    gradientStops: [
        .init(color: .black, location: 0.0)
    ]
)

Nesse caso, o fundo será renderizado com uma única cor.

Exemplo completo

O exemplo abaixo combina mensagens customizadas, uma view própria para carregamento e ajustes de cor.

import Foundation
import SwiftUI

let theme = TapOnPhoneTheme(
    stepMessages: [
        .terminalActivationStarted: "Preparando Tap",
        .authorizingPleaseWait: "Validando pagamento",
        .transactionAborted: "Pagamento cancelado",
        .pinInputStarted: "Digite sua senha",
        .pinInputFinished: "Senha confirmada",
        .kernelUpdateProgress(0): "Atualizando Kernel"
    ],
    stepViews: [
        .authorizingPleaseWait: AnyView(
            VStack(spacing: 12) {
                ProgressView()
                    .tint(.white)

                Text("Aguarde enquanto validamos a transação")
                    .font(.headline)
                    .foregroundColor(.white)
            }
            .padding()
        )
    ],
    ],
    textColor: .white,
    loadingColor: .white,
    backgroundColor: .black,
    screenTransitionStyle: .coverVertical,
    gradientStops: [
        .init(color: .black.opacity(0.85), location: 0.0),
        .init(color: .black.opacity(0.60), location: 0.60),
        .init(color: .black.opacity(0.00), location: 1.0)
    ]
)

Boas práticas de customização

Use mensagens curtas para não disputar atenção com o fluxo de pagamento.
Mantenha contraste alto entre fundo e texto.
Evite criar views muito carregadas durante etapas críticas, como autorização e leitura.
Use um screenTransitionStyle coerente com o padrão de navegação do seu app para não criar quebras visuais entre telas.
Preserve uma transição visual próxima da experiência nativa quando quiser uma navegação mais fluida entre a sua interface e a interface da Apple.
Preserve uma transição visual próxima da experiência nativa quando quiser uma navegação mais fluida entre a sua interface e a interface da Apple.

A view proprietária de leitura de cartão da Apple não é customizável. O tema padrão foi definido nesse esquema de cores justamente para aproximar a transição entre a interface do seu app e a interface nativa.