6 - Onboarding Apple

Inicie o onboarding do Tap to Pay no iPhone apresentando o fluxo do SDK a partir da UIViewController visível no app.

O onboarding é um tutorial exibido pela Apple que explica ao usuário como funciona o Tap to Pay no iPhone e pode ser apresentado sob demanda.

① Obter a UIViewController atual  →  ② Chamar processOnboarding()  →  ③ Tratar erro no callback

Fluxo de onboarding do Tap to Pay no iPhone apresentado pelo SDK — Exemplo visual do onboarding exibido ao usuário no Tap to Pay no iPhone.

Contexto de tela

Recupere a UIViewController que está visível para apresentar o fluxo do SDK.

Onboarding

Chame TapOnPhone.processOnboarding(...) com a view controller atual.

Diagnóstico

Registre o erro retornado em onError para validar a integração.

Antes de começar

Adicione o SDK iOS ao projeto em 1 - Adicionar ao projeto.
Importe UIKit e TapOnPhoneSDK no arquivo em que fará a chamada.
Execute o onboarding a partir de uma tela com UIWindowScene e rootViewController disponíveis.

1. Obter a `UIViewController` visível

Antes de chamar o onboarding, recupere a UIViewController atualmente exibida. O SDK precisa desse contexto para apresentar o fluxo na interface.

private func getTopViewController() -> UIViewController? {
    guard let windowScene = UIApplication.shared.connectedScenes.first as? UIWindowScene,
          let rootViewController = windowScene.windows.first?.rootViewController else {
        return nil
    }

    var topViewController = rootViewController

    while let presentedViewController = topViewController.presentedViewController {
        topViewController = presentedViewController
    }

    return topViewController
}

O que esse método faz

Etapa	Descrição
`connectedScenes.first`	Busca a cena ativa da aplicação.
`windows.first?.rootViewController`	Obtém a view controller raiz da janela.
`presentedViewController`	Avança até a tela atualmente apresentada ao usuário.
`return topViewController`	Retorna a `UIViewController` que deve ser usada no onboarding.

2. Chamar `processOnboarding()`

Com a UIViewController em mãos, inicie o onboarding pelo SDK. Se ocorrer alguma falha, trate o retorno no callback onError.

if let viewController = getTopViewController() {
    TapOnPhone.processOnboarding(
        viewController: viewController,
        onError: { [weak self] error in
            guard self != nil else { return }
            print(error.error)
        }
    )
}

⚠️
Se getTopViewController() retornar nil, o onboarding não será apresentado. Nesse caso, valide se a aplicação já possui uma janela ativa e uma rootViewController disponível.

3. Exemplo completo

O exemplo abaixo organiza a implementação em um UIViewController, deixando a recuperação da tela atual e a chamada do onboarding no mesmo fluxo.

import UIKit
import TapOnPhoneSDK

final class OnboardingViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
    }

    func startOnboarding() {
        guard let viewController = getTopViewController() else {
            print("Não foi possível localizar uma UIViewController ativa para iniciar o onboarding.")
            return
        }

        TapOnPhone.processOnboarding(
            viewController: viewController,
            onError: { [weak self] error in
                guard self != nil else { return }
                print("Erro no onboarding: \(error.error)")
            }
        )
    }

    private func getTopViewController() -> UIViewController? {
        guard let windowScene = UIApplication.shared.connectedScenes.first as? UIWindowScene,
              let rootViewController = windowScene.windows.first?.rootViewController else {
            return nil
        }

        var topViewController = rootViewController

        while let presentedViewController = topViewController.presentedViewController {
            topViewController = presentedViewController
        }

        return topViewController
    }
}

Saída esperada em caso de erro

Erro no onboarding: <detalhes do erro>

4. Validar a implementação

Depois de adicionar o código, valide estes pontos no app:

Abra a tela que vai disparar o onboarding.
Chame startOnboarding() ou execute diretamente TapOnPhone.processOnboarding(...).
Confirme que a UIViewController atual foi encontrada com sucesso.
Se houver erro, verifique o valor impresso em error.error.

Troubleshooting

`getTopViewController()` retorna `nil`

Valide se existe uma UIWindowScene ativa e se windows.first?.rootViewController já está disponível no momento da chamada.

O callback `onError` foi acionado

Registre o conteúdo de error.error e use esse retorno como base para diagnóstico da integração.

Antes de começar

1. Obter a UIViewController visível

O que esse método faz

2. Chamar processOnboarding()

3. Exemplo completo

4. Validar a implementação

Troubleshooting

getTopViewController() retorna nil

O callback onError foi acionado

1. Obter a `UIViewController` visível

2. Chamar `processOnboarding()`

`getTopViewController()` retorna `nil`

O callback `onError` foi acionado