iOS SDK

Requisitos#

• iOS 15.0+ (detents de sheet mais finas no iOS 16+, com um fallback do sistema abaixo).
• Swift 5.9+.
• Zero dependências de terceiros — apenas Foundation, Swift Concurrency, SwiftUI e UIKit.

Depende do produto RespondoSDK, que reexporta o RespondoCore multiplataforma.

Instalação#

Adicione o pacote com o Swift Package Manager. No Xcode: File → Add Package Dependencies… e introduza https://github.com/respondo-app/sdk-ios, ou declare-o no seu próprio Package.swift e depois dependa do produto RespondoSDK.

dependencies: [
    .package(url: "https://github.com/respondo-app/sdk-ios", from: "0.1.0")
],
targets: [
    .target(
        name: "MyApp",
        dependencies: [
            .product(name: "RespondoSDK", package: "sdk-ios")
        ]
    )
]

Depois importe-o no código:

import RespondoSDK

Inicializar#

Inicialize uma vez na inicialização e depois chame Respondo.open() em qualquer lugar. O método de ciclo de vida é initialize (a palavra init está reservada pela linguagem).

import SwiftUI
import RespondoSDK

@main
struct MyApp: App {
    init() {
        Respondo.initialize(
            RespondoConfig(
                agentId: "<agent-uuid>",
                channelId: "<channel-uuid>"
                // baseUrl nil -> https://api.respondo.ai
            )
        )
    }

    var body: some Scene {
        WindowGroup {
            Button("Support") { Respondo.open() }
        }
    }
}

A fachada Respondo é thread-safe. As chamadas feitas logo a seguir a initialize são enfileiradas e aplicadas assim que a init assíncrona termina.

Identificar usuários#

Por padrão, todos os visitantes são anônimos. Na primeira execução o SDK gera um visitor_id estável e o salva no keychain, para que um usuário que retorna encontre novamente a sua conversa. Não há nenhuma chave de API para embeber — cada conversa é protegida por um token de sessão por conversa que o backend cunha e faz avançar a cada mensagem, para que um visitante anônimo nunca tenha de se voltar a autenticar.

Chame identify assim que o seu usuário estiver autenticado. Isso associa a identidade real, para que o histórico o acompanhe entre dispositivos e reinstalações, e o nome e o e-mail apareçam junto à conversa na sua caixa de entrada em vez de um visitante anônimo.

O userHash é uma assinatura que o seu backend calcula a partir do identity_secret do agente — HMAC-SHA256(secret, userId) (ou o e-mail quando não há userId), codificado em hexadecimal minúsculo. O segredo prova que a identidade é genuína, por isso deve viver apenas no seu backend e nunca é enviado na app. Consulte a página Verificação de identidade para a fórmula completa e exemplos do lado do servidor.

// O userHash vem do seu backend (HMAC-SHA256 sobre o userId) —
// nunca o calcule no app.
Respondo.identify(
    RespondoIdentity(
        userId: session.userId,
        email: session.email,
        name: session.fullName,
        userHash: session.respondoUserHash
    )
)

// No logout: revogue a sessão e inicie um novo visitante anônimo.
Respondo.reset()

Se o hash estiver ausente ou errado, nada é lançado: o backend mantém silenciosamente o visitante anônimo, o chat continua funcionando, e apenas perde o vínculo entre dispositivos até ser fornecido um hash válido. A verificação só roda quando o agente tem um identity_secret definido — deixe-o vazio durante o desenvolvimento e userId / e-mail são aceites tal como estão.

Observáveis & delegate#

Leia o estado como getters síncronos, como AsyncStreams reativos, ou através de um RespondoDelegate. Os streams e os callbacks do delegate chegam no main actor.

// Stream reativo de contagens de não lidas.
Task {
    for await count in Respondo.unreadCountStream {
        updateBadge(count)
    }
}

// Delegate para badges e fallbacks de deep-link.
final class SupportCoordinator: RespondoDelegate {
    init() { Respondo.delegate = self }
    func respondoUnreadChanged(_ count: Int) {
        UIApplication.shared.applicationIconBadgeNumber = count
    }
}

Rastreamento de tela#

Informe a tela atual em cada navegação para que os teasers proativos e a segmentação no nível da página possam corresponder a ela (static func setCurrentScreen(_ name: String?)). Passe nil para limpá-la; a cada mudança, o teaser proativo é reavaliado para a nova tela.

Respondo.setCurrentScreen("pricing")

Próximos passos#

Configure as Notificações push e a Verificação de identidade. O wrapper UIKit RespondoChatViewController, a superfície completa do delegate e a resolução de problemas são abordados no guia de introdução do iOS SDK; o código-fonte do SDK é público no GitHub.