TipKit para Swift: Guia completo para criar dicas contextuais

TipKit é uma biblioteca moderna e poderosa da Apple, apresentada na WWDC 2023, projetada para criar dicas contextuais e treinar usuários em aplicativos SwiftUI e UIKit. Ela permite que desenvolvedores implementem facilmente dicas interativas que ajudam os usuários a aprender a interface mais rapidamente, descobrir novos recursos e aumentar o engajamento geral com o aplicativo.

O principal objetivo do TipKit é substituir soluções de onboarding antigas e complexas (como views personalizadas ou bibliotecas de terceiros) por uma ferramenta padronizada, flexível e de alto desempenho. O TipKit gerencia automaticamente a exibição das dicas: mostra-as no momento certo, oculta-as após a interação, leva em conta a frequência de exibição e permite personalizar a lógica de aparecimento com base nas ações do usuário ou no estado do aplicativo.

A biblioteca é ideal para iOS 17+, macOS 14+, tvOS 17+ e watchOS 10+. Ela se integra perfeitamente aos frameworks da Apple, suporta animações, adaptabilidade a diferentes tamanhos de tela e funciona tanto com SwiftUI quanto com UIKit (através de UIViewRepresentable). Neste artigo, vamos detalhar todos os recursos do TipKit, desde a instalação até cenários de uso avançados.

Instalação

O TipKit faz parte do ecossistema da Apple e não requer instalação por gerenciadores de pacotes de terceiros. Para usar a biblioteca, basta adicioná-la ao seu projeto Xcode através do Swift Package Manager (SPM) padrão ou manualmente.

Através do Xcode (método recomendado)

1. Abra seu projeto no Xcode.
2. Selecione File → Add Package Dependencies....
3. Na barra de pesquisa, digite: https://github.com/apple/sample-tipkit.git (repositório oficial da Apple com exemplos) ou use o pacote integrado, se disponível na sua versão do Xcode.
4. Certifique-se de selecionar o branch main ou a versão estável mais recente.
5. Clique em Add Package e escolha seu target.

Importante: A partir do Xcode 15, o TipKit já vem embutido no SDK, então na maioria dos casos basta importar o módulo no código. Se você estiver usando uma versão mais antiga do Xcode, adicione o pacote manualmente.

Através do Package.swift (para projetos SPM)

// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    name: "SeuProjeto",
    dependencies: [
        .package(url: "https://github.com/apple/sample-tipkit.git", from: "1.0.0")
    ],
    targets: [
        .target(
            name: "SeuTarget",
            dependencies: ["TipKit"]
        )
    ]
)

Após adicionar o pacote, importe a biblioteca no arquivo desejado:

import TipKit

Início rápido: exemplo funcional mínimo

Vamos criar uma dica simples que aparecerá na primeira vez que o aplicativo for iniciado e explicará ao usuário como usar um botão.

import SwiftUI
import TipKit

// 1. Defina a estrutura da dica
struct WelcomeTip: Tip {
    var title: Text {
        Text("Bem-vindo!")
    }
    
    var message: Text? {
        Text("Clique neste botão para começar a usar o aplicativo.")
    }
    
    var image: Image? {
        Image(systemName: "hand.wave")
    }
}

// 2. Use a dica na view
struct ContentView: View {
    // 3. Crie uma instância da dica
    private let welcomeTip = WelcomeTip()
    
    var body: some View {
        VStack {
            Button("Começar") {
                // Ação do botão
                print("Botão clicado!")
            }
            .popoverTip(welcomeTip) // 4. Vincule a dica ao botão
            .padding()
        }
        .padding()
        .task {
            // 5. Configure o TipKit na inicialização
            try? await Tips.configure()
        }
    }
}