SDK de chat para iOS e Android

Leve o seu chat ao vivo do Deskwoot para o seu próprio app para iOS ou Android como uma tela nativa. A sua equipe e o seu bot de IA respondem no Deskwoot, como no chat do seu site.

Nesta página

O que é o SDK

O SDK leva o chat da caixa de entrada do seu site para o seu app como uma tela nativa. Ele é desenhado com UIKit no iOS e com as views do próprio Android no Android, e não carregado como página web; só o texto de um artigo de ajuda aparece em uma web view do sistema. Os visitantes escrevem para a sua equipe e para o seu bot de IA, pesquisam na sua central de ajuda e leem as respostas dentro do seu app.

É o mesmo chat do seu site. Ele lê as mesmas configurações da caixa de entrada (cor da marca, textos, equipe, bot de IA, central de ajuda) e mostra o visual que você escolheu para a caixa: Claro, Recepção ou Direto. Ele fala os 10 idiomas de visitantes do chat do site.

As conversas do app chegam a essa caixa de entrada, onde a sua equipe responde como sempre.

Requisitos

PlataformaRoda emCompila com
iOSiOS 15 ou posterior, iPhone e iPadXcode 15 ou posterior (Swift 5.9)
AndroidAndroid 5.0 (API 21) ou posteriorcompileSdk 34 ou superior, Android Gradle Plugin 8 ou posterior, Kotlin 1.9 ou posterior, ou Java. Funciona em apps feitos com Views e em apps feitos com Jetpack Compose.

Você também precisa de uma caixa de entrada do Deskwoot do tipo Chat ao vivo (o chat do site). O SDK usa o token do widget dela.

Instalação

iOS: no Xcode, escolha File → Add Package Dependencies, informe https://github.com/Deskwoot/deskwoot-ios e adicione a biblioteca Deskwoot ao target do seu app. Ou adicione o pacote ao seu Package.swift:

iOS (Swift)
dependencies: [
    .package(url: "https://github.com/Deskwoot/deskwoot-ios", from: "1.0.0"),
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [.product(name: "Deskwoot", package: "deskwoot-ios")]
    ),
]

Android: o SDK está no Maven Central. Adicione-o ao build.gradle.kts do módulo do seu app:

Android (Kotlin)
dependencies {
    implementation("com.deskwoot:deskwoot-android:1.0.0")
}

O pacote para iOS vem como código fonte e compila com o seu Xcode. A biblioteca para Android funciona com Kotlin e com Java.

Configuração

O SDK precisa do token do widget de uma caixa de entrada do tipo Chat ao vivo. No Deskwoot, abra Configurações → Caixas de entrada → sua caixa de entrada → Chat no seu app para iOS e Android: o token está no topo, pronto para copiar.

Chame setup uma vez com esse token, tão cedo quanto quiser: em application(_:didFinishLaunchingWithOptions:) no iOS, em Application.onCreate no Android. Ele não usa disco nem rede na thread principal, e uma segunda chamada com o mesmo token não faz nada.

iOS (Swift)
import Deskwoot
import UIKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        Deskwoot.setup(widgetToken: "YOUR_WIDGET_TOKEN")
        return true
    }
}
Android (Kotlin)
import android.app.Application
import com.deskwoot.sdk.Deskwoot

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        Deskwoot.setup(this, "YOUR_WIDGET_TOKEN")
    }
}

No iOS, chame o SDK na thread principal (uma chamada de outra thread fica registrada no log e roda na thread principal um instante depois). No Android, toda chamada funciona de qualquer thread.

Um widgetToken = uma caixa de entrada. Com o token do seu site, os chats do app chegam à mesma caixa de entrada que os chats do site. Com o token de uma segunda caixa de chat ao vivo, você os mantém separados.

Abrir o chat

Abra o chat pelo seu próprio botão de ajuda. Toda chamada funciona logo depois de setup, mesmo antes de as configurações da caixa de entrada carregarem.

iOSAndroidO que abre
present()present(activity)A página inicial.
presentConversation()presentConversation(activity)A conversa em andamento mais recente do visitante, ou uma nova.
presentNewConversation(text:)presentNewConversation(activity, text)Uma conversa nova com o seu texto no campo de mensagem. O visitante pode editar e envia ele mesmo; o SDK não envia nada por ele.
presentHelpCenter()presentHelpCenter(activity)A central de ajuda, ou a página inicial quando a caixa de entrada não tem uma.
dismiss()dismiss()Fecha o chat se ele estiver aberto.

No iOS o chat abre como uma folha sobre a tela do topo do seu app; passe from: para escolher a tela. No Android ele abre como uma Activity própria; passe a Activity de onde você chama, assim o chat fica na tarefa do seu app e pega dela o modo claro ou escuro.

iOS (Swift)
// For example behind your "Help" button
Deskwoot.present()                       // the start page
Deskwoot.present(from: self)             // the same, over this screen
Deskwoot.presentConversation()
Deskwoot.presentNewConversation(text: "I have a question about order 1042")
Deskwoot.presentHelpCenter()
Deskwoot.dismiss()
Android (Kotlin)
// In an Activity, for example behind your "Help" button
Deskwoot.present(this)                   // the start page
Deskwoot.presentConversation(this)
Deskwoot.presentNewConversation(this, "I have a question about order 1042")
Deskwoot.presentHelpCenter(this)
Deskwoot.dismiss()

O launcher

setLauncherVisible(true) mostra o botão redondo de chat do widget do site sobre o conteúdo do seu app: na cor da sua marca, no lado definido para a caixa de entrada, com um selo de respostas não lidas. Um toque abre o chat. Ele fica oculto por padrão, porque a maioria dos apps abre o chat pelo próprio botão.

Uma resposta com o chat fechado

Quando chega uma resposta com o seu app aberto e o chat fechado, um pequeno cartão sobe na parte de baixo do seu app com a foto e o nome de quem escreveu e 2 linhas da resposta. Um toque abre essa conversa. O cartão não precisa de nenhuma permissão e nunca aparece sobre o chat. Ele vem ligado por padrão; inAppNotificationsEnabled = false desliga.

iOS (Swift)
Deskwoot.setLauncherVisible(true)            // show the round chat button
Deskwoot.inAppNotificationsEnabled = false   // no card for new replies
Android (Kotlin)
Deskwoot.setLauncherVisible(true)            // show the round chat button
Deskwoot.inAppNotificationsEnabled = false   // no card for new replies

Usuários logados

Sem identify, o visitante conversa de forma anônima e a conversa fica naquele celular. Quando o seu usuário estiver logado, identifique-o: assim as conversas dele o acompanham em todos os dispositivos e no chat do seu site na mesma caixa de entrada, e a sua equipe vê quem ele é.

O Deskwoot só confia em um usuário com identifierHash: o HMAC SHA256 de identifier com o segredo de assinatura da sua caixa de entrada, em hexadecimal. O seu servidor calcula e repassa ao app. É a mesma assinatura do site, com e-mail, nome e atributos assinados opcionais: Verificação de identidade na página do widget.

iOS (Swift)
// After your own sign in, with the hash from your server
Deskwoot.identify(DeskwootUser(
    identifier: user.id,
    identifierHash: hashFromYourServer,
    email: user.email,   // optional
    name: user.name      // optional
))

// When the user signs out of your app
Deskwoot.logout()
Android (Kotlin)
// After your own sign in, with the hash from your server
Deskwoot.identify(
    DeskwootUser(
        identifier = user.id,
        identifierHash = hashFromYourServer,
        email = user.email,   // optional
        name = user.name,     // optional
    ),
)

// When the user signs out of your app
Deskwoot.logout()

Chame identify a cada início do app assim que ele souber quem é o usuário, e de novo depois de um login. No Android, se o seu app tem o usuário e o hash guardados, chame-o em Application.onCreate logo depois de setup: o Android pode iniciar o seu app por um toque em uma notificação sem abrir nenhuma das suas telas. Chame logout() quando o usuário sair, também em um início em que o seu app não encontra mais a sessão dele, e só nesses casos: o SDK apaga o que guardou sobre o visitante, também o chat de quem nunca fez login, e o próximo chat começa como um visitante novo e anônimo.

Nunca coloque o segredo de assinatura no seu app. Qualquer pessoa que descompactar o app poderia lê-lo e conversar como qualquer um dos seus usuários.

Respostas não lidas

unreadCount é o número de respostas que o visitante ainda não leu, em todas as conversas dele, por exemplo para um selo no seu botão de ajuda. Leia uma vez para ter o primeiro valor: unreadCountDidChange no iOS e um UnreadCountListener no Android só avisam mudanças.

iOS (Swift)
let count = Deskwoot.unreadCount

NotificationCenter.default.addObserver(
    forName: Deskwoot.unreadCountDidChange, object: nil, queue: .main
) { note in
    let count = note.userInfo?["count"] as? Int ?? 0
    // show count on your help button
}
Android (Kotlin)
val count = Deskwoot.unreadCount

val listener = UnreadCountListener { count ->
    badge.text = count.toString()
}
Deskwoot.addUnreadCountListener(listener)
// when the screen goes away
Deskwoot.removeUnreadCountListener(listener)

Idioma e tema

O chat fala o idioma fixo da caixa de entrada quando ela tem um. Senão, ele segue o seu app: no iOS o idioma em que o seu app roda, no Android o idioma do celular ou o que o usuário escolheu para o seu app. Defina language com uma tag de idioma como "de" ou "pt-BR" para escolher você mesmo no lugar do idioma do app; vale enquanto o app estiver rodando e nunca é salvo. Um idioma que o chat não conhece vira inglês.

O chat conhece os 10 idiomas de visitantes do chat do site: inglês, alemão (com o du ou o Sie que a caixa de entrada usa), espanhol, francês, português do Brasil, árabe (da direita para a esquerda), hindi, italiano, japonês e chinês simplificado. Todo texto e todo rótulo para leitores de tela fica nesse idioma.

As cores vêm da cor da marca da caixa de entrada, em uma variante clara e uma escura. Por padrão o chat segue o seu app: claro ou escuro como a tela sobre a qual ele abre. theme define system (padrão), light, dark ou inbox (a configuração da própria caixa de entrada, como no site).

iOS (Swift)
Deskwoot.language = "de"   // nil: the inbox's language, else your app's
Deskwoot.theme = .system   // .system (default), .light, .dark or .inbox
Android (Kotlin)
Deskwoot.language = "de"                 // null: the inbox's language, else your app's
Deskwoot.theme = Deskwoot.Theme.SYSTEM   // SYSTEM (default), LIGHT, DARK or INBOX

O texto usa a fonte do sistema e cresce com o tamanho de texto do celular. No Android, se o seu app mantém só alguns idiomas (localeFilters), o chat só pode usar esses.

Notificações push

Sem push, uma resposta chega ao visitante enquanto o seu app está aberto: no contador de respostas não lidas, no cartão e no selo do launcher. Com push, ela chega também com o app fechado. O SDK nunca fala com a Apple ou o Google por conta própria e não traz o Firebase: o seu app obtém o token do dispositivo como já faz e repassa ao SDK. Ele também não pede a permissão de notificações; isso fica com o seu app, na hora que fizer sentido.

No Deskwoot

  1. Abra Configurações → Caixas de entrada → sua caixa de entrada → Chat no seu app para iOS e Android da caixa de entrada cujo token o seu app usa.
  2. Para iOS: crie uma chave de autenticação do APNs na sua conta do Apple Developer, em Keys. Cole ou envie a chave em Chave de autenticação do APNs (.p8) e informe o ID da chave, o ID da equipe e o Bundle ID do seu app.
  3. Para Android: no Firebase, abra Configurações do projeto, depois Contas de serviço, e gere uma nova chave privada. Cole ou envie esse arquivo em JSON da conta de serviço.
  4. Clique em Salvar abaixo de cada bloco. O Deskwoot confere a chave com a Apple ou com o Google antes de guardá-la, e o bloco passa a mostrar Conectado.

No seu app para iOS

Ative a capability Push Notifications no target do seu app. Peça a permissão e registre o app na Apple como ele já faz para as próprias notificações, e passe o token do dispositivo para setPushToken a cada início. No delegate do notification center, deixe o SDK cuidar das notificações dele:

iOS (Swift)
import Deskwoot
import UIKit
import UserNotifications

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        Deskwoot.setup(widgetToken: "YOUR_WIDGET_TOKEN")
        UNUserNotificationCenter.current().delegate = self
        // Ask for permission when it suits your app, then:
        application.registerForRemoteNotifications()
        return true
    }

    func application(
        _ application: UIApplication,
        didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
    ) {
        Deskwoot.setPushToken(deviceToken)
    }
}

// The system calls both on the main thread. Written this way they
// compile in the Swift 5 and the Swift 6 language mode.
extension AppDelegate: UNUserNotificationCenterDelegate {
    // A notification while your app is in front
    nonisolated func userNotificationCenter(
        _ center: UNUserNotificationCenter,
        willPresent notification: UNNotification,
        withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void
    ) {
        MainActor.assumeIsolated {
            if let options = Deskwoot.presentationOptions(for: notification) {
                completionHandler(options)
            } else {
                completionHandler([.banner, .list, .sound])   // one of your own
            }
        }
    }

    // A tap on a notification
    nonisolated func userNotificationCenter(
        _ center: UNUserNotificationCenter,
        didReceive response: UNNotificationResponse,
        withCompletionHandler completionHandler: @escaping () -> Void
    ) {
        MainActor.assumeIsolated {
            if !Deskwoot.handleNotificationResponse(response) {
                // one of your own: handle it here
            }
            completionHandler()
        }
    }
}

presentationOptions(for:) responde nil para uma notificação que não é do Deskwoot. Para uma do Deskwoot, não mostra banner enquanto o visitante vê aquela conversa. handleNotificationResponse abre a conversa e responde true; para as suas próprias notificações responde false. isDeskwootNotification(_:) separa as duas em qualquer outro lugar. O SDK descobre sozinho se um token é do sandbox da Apple ou de produção.

Em um app SwiftUI, conecte este app delegate com @UIApplicationDelegateAdaptor. O SDK não faz swizzling de nenhum método: o seu app faz essas chamadas por conta própria.

No seu app para Android

O seu app precisa do Firebase Cloud Messaging. Passe o token de registro do FCM para setPushToken uma vez no início e em onNewToken, e repasse as mensagens do Deskwoot em onMessageReceived:

Android (Kotlin)
class PushService : FirebaseMessagingService() {
    override fun onNewToken(token: String) {
        Deskwoot.setPushToken(token)
    }

    override fun onMessageReceived(message: RemoteMessage) {
        if (Deskwoot.isDeskwootPush(message.data)) {
            Deskwoot.handlePush(this, message.data)
            return
        }
        // one of your own: handle it here
    }
}

// Once at start, for example in Application.onCreate after Deskwoot.setup
FirebaseMessaging.getInstance().token.addOnSuccessListener { token ->
    Deskwoot.setPushToken(token)
}

O SDK desenha a notificação por conta própria, no próprio canal de notificações e com o ícone do seu app (setNotificationIcon(resId) define outro). Um toque abre a conversa, e nada aparece enquanto o visitante vê aquela conversa. A partir do Android 13, o seu app pede POST_NOTIFICATIONS na hora que fizer sentido; sem essa permissão nenhuma notificação aparece.

Quando um push sai

O Deskwoot envia um para cada resposta da sua equipe ou do seu bot de IA, nunca para as mensagens do próprio visitante. Se o visitante estava online um instante antes, o Deskwoot espera 12 segundos e não envia nada se ele já tiver lido a resposta. O título diz quem escreveu, e o texto mostra até 160 caracteres da resposta. Quando o seu usuário sai, o SDK remove as notificações daquele visitante e tira o celular dos pushes dele.

O que o SDK adiciona ao seu app

O quêiOSAndroid
TamanhoCerca de 1,24 MB comprimido (o app zipado, perto do que a App Store entrega). Sem compressão, 2,67 MB de código e 0,17 MB de textos em 10 idiomas.Cerca de 0,7 MB com tudo o que ele traz: um app mínimo compilado com R8 vai de 23 KB para 724 KB. Um app que já traz Kotlin, coroutines e androidx paga menos. O AAR em si tem 1,7 MB.
PermissõesNenhuma. Adicione NSCameraUsageDescription só se os visitantes puderem enviar fotos tiradas com a câmera; sem essa chave o menu de anexos oferece a fototeca e arquivos, que não precisam de permissão.Só INTERNET. As fotos vêm do seletor de fotos do sistema e os arquivos do seletor de documentos do sistema; nenhum dos dois precisa de permissão. A câmera passa pelo app de câmera do sistema, e o SDK só pede a permissão de câmera quando o seu app a declara por conta própria.
DependênciasNenhuma além dos frameworks da Apple.kotlinx-coroutines-android, androidx.annotation, androidx.core, androidx.activity, androidx.recyclerview, com o que elas mesmas trazem (androidx lifecycle, savedstate, collection e similares), mas sem androidx.profileinstaller. Sem OkHttp, sem Retrofit, sem biblioteca de JSON ou de imagens, sem Firebase, sem Compose.
No seu appNada roda antes de setup, e o SDK não faz swizzling de nenhum método.1 Activity (DeskwootActivity) e 1 FileProvider (DeskwootFileProvider), ambos não exportados. Nenhum service e nenhum receiver. Antes de setup, o SDK só guarda o contexto do seu app no FileProvider dele, e nenhum dos seus temas ou estilos é alterado.
Na abertura do appSem custo: setup faz cada etapa de disco e de rede em segundo plano.Sem custo: setup faz cada etapa de disco e de rede em segundo plano.

Medido na versão 1.0.0. iOS: dois apps vazios que só diferem pelo SDK, build Release para iPhone (arm64); o binário sem símbolos tem 2.744.720 bytes contra 73.248 bytes sem o SDK. Android: um app mínimo com 1 Activity.

Perguntas frequentes

As respostas curtas estão aqui. Para qualquer outra coisa, pergunte ao Fynn abaixo.

Existe um SDK para React Native ou Flutter?

Não. O Deskwoot tem SDKs nativos para iOS (Swift) e Android (Kotlin e Java) e nenhum pacote para React Native ou Flutter. Em um app feito com eles, você pode mostrar o chat do site em uma web view com o modo embedded do widget, descrito na página do SDK do widget.

O chat funciona sem notificações push?

Sim. Enquanto o seu app está aberto, uma resposta aparece no contador de respostas não lidas, no cartão na parte de baixo do seu app e no selo do launcher. As notificações push somam as respostas que chegam com o app fechado.

Onde aparecem as conversas do app?

Na caixa de entrada cujo token do widget você passa para setup. Com o mesmo token do seu site, os chats do app e os do site dividem uma caixa de entrada, as configurações dela, a sua equipe e o seu bot de IA.

Demo interativa do Deskwoot