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
| Plataforma | Roda em | Compila com |
|---|---|---|
| iOS | iOS 15 ou posterior, iPhone e iPad | Xcode 15 ou posterior (Swift 5.9) |
| Android | Android 5.0 (API 21) ou posterior | compileSdk 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:
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:
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.
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
}
}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.
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.
| iOS | Android | O 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.
// 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()// 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.
Deskwoot.setLauncherVisible(true) // show the round chat button
Deskwoot.inAppNotificationsEnabled = false // no card for new repliesDeskwoot.setLauncherVisible(true) // show the round chat button
Deskwoot.inAppNotificationsEnabled = false // no card for new repliesUsuá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.
// 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()// 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.
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.
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
}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).
Deskwoot.language = "de" // nil: the inbox's language, else your app's
Deskwoot.theme = .system // .system (default), .light, .dark or .inboxDeskwoot.language = "de" // null: the inbox's language, else your app's
Deskwoot.theme = Deskwoot.Theme.SYSTEM // SYSTEM (default), LIGHT, DARK or INBOXO 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
- 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.
- 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.
- 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.
- 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:
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:
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ê | iOS | Android |
|---|---|---|
| Tamanho | Cerca 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ões | Nenhuma. 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ências | Nenhuma 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 app | Nada 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 app | Sem 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.