SDK de chat para iOS y Android

Lleva tu chat en vivo de Deskwoot a tu propia app para iOS o Android como una pantalla nativa. Tu equipo y tu bot de IA responden en Deskwoot, como en el chat de tu sitio web.

En esta página

Qué es el SDK

El SDK lleva el chat de la bandeja de entrada de tu sitio web a tu app como una pantalla nativa. Se dibuja con UIKit en iOS y con las vistas propias de Android en Android, no se carga como página web; solo el texto de un artículo de ayuda aparece en una web view del sistema. Los visitantes le escriben a tu equipo y a tu bot de IA, buscan en tu centro de ayuda y leen las respuestas dentro de tu app.

Es el mismo chat que en tu sitio web. Lee la misma configuración de la bandeja de entrada (color de marca, textos, equipo, bot de IA, centro de ayuda) y muestra el diseño que elegiste para la bandeja: Sencillo, Bienvenida o Directo. Habla los 10 idiomas para visitantes del chat del sitio web.

Las conversaciones de la app llegan a esa bandeja de entrada, donde tu equipo las responde como siempre.

Requisitos

PlataformaFunciona enSe compila con
iOSiOS 15 o posterior, iPhone y iPadXcode 15 o posterior (Swift 5.9)
AndroidAndroid 5.0 (API 21) o posteriorcompileSdk 34 o superior, Android Gradle Plugin 8 o posterior, Kotlin 1.9 o posterior, o Java. Funciona en apps hechas con Views y en apps hechas con Jetpack Compose.

También necesitas una bandeja de entrada de Deskwoot del tipo Chat en vivo (el chat del sitio web). El SDK usa su token del widget.

Instalación

iOS: en Xcode elige File → Add Package Dependencies, ingresa https://github.com/Deskwoot/deskwoot-ios y agrega la biblioteca Deskwoot al target de tu app. O agrega el paquete a tu 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: el SDK está en Maven Central. Agrégalo al build.gradle.kts del módulo de tu app:

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

El paquete de iOS se distribuye como código fuente y se compila con tu Xcode. La biblioteca de Android funciona desde Kotlin y desde Java.

Configuración

El SDK necesita el token del widget de una bandeja de entrada del tipo Chat en vivo. En Deskwoot, abre Configuración → Bandejas de entrada → tu bandeja de entrada → Chat en tu app para iOS y Android: el token está arriba, listo para copiar.

Llama a setup una vez con ese token, tan pronto como quieras: en application(_:didFinishLaunchingWithOptions:) en iOS, en Application.onCreate en Android. No usa el disco ni la red en el hilo principal, y una segunda llamada con el mismo token no hace 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")
    }
}

En iOS, llama al SDK desde el hilo principal (una llamada desde otro hilo queda registrada y se ejecuta en el hilo principal un momento después). En Android, cada llamada funciona desde cualquier hilo.

Un widgetToken = una bandeja de entrada. Con el token de tu sitio web, los chats de la app llegan a la misma bandeja de entrada que los chats del sitio. Con el token de una segunda bandeja de chat en vivo, los mantienes separados.

Abrir el chat

Abre el chat desde tu propio botón de ayuda. Cada llamada funciona justo después de setup, incluso antes de que cargue la configuración de la bandeja de entrada.

iOSAndroidQué se abre
present()present(activity)La página de inicio.
presentConversation()presentConversation(activity)La conversación en curso más reciente del visitante, o una nueva.
presentNewConversation(text:)presentNewConversation(activity, text)Una conversación nueva con tu texto en el campo de mensaje. El visitante puede editarlo y lo envía él mismo; el SDK no envía nada por él.
presentHelpCenter()presentHelpCenter(activity)El centro de ayuda, o la página de inicio si la bandeja de entrada no tiene uno.
dismiss()dismiss()Cierra el chat si está abierto.

En iOS el chat se abre como una hoja sobre la pantalla superior de tu app; pasa from: para elegir la pantalla. En Android se abre como su propia Activity; pasa la Activity desde la que llamas, así el chat se queda en la tarea de tu app y toma de ella el modo claro u oscuro.

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()

El botón del chat

setLauncherVisible(true) muestra el botón redondo de chat del widget web sobre el contenido de tu app: en tu color de marca, del lado configurado para la bandeja de entrada, con un indicador de respuestas sin leer. Un toque abre el chat. Está oculto por defecto, porque la mayoría de las apps abren el chat desde su propio botón.

Una respuesta con el chat cerrado

Cuando llega una respuesta mientras tu app está abierta y el chat cerrado, sube una pequeña tarjeta en la parte inferior de tu app con la foto y el nombre de quien escribió y 2 líneas de la respuesta. Un toque abre esa conversación. La tarjeta no necesita ningún permiso y nunca aparece sobre el chat. Viene activada por defecto; inAppNotificationsEnabled = false la desactiva.

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

Usuarios con sesión iniciada

Sin identify, el visitante chatea de forma anónima y la conversación se queda en ese teléfono. Cuando tu usuario inició sesión, identifícalo: así sus conversaciones lo siguen a cada dispositivo y al chat de tu sitio web en la misma bandeja de entrada, y tu equipo ve quién es.

Deskwoot solo confía en un usuario con identifierHash: el HMAC SHA256 de identifier con el secreto de firma de tu bandeja de entrada, en hexadecimal. Tu servidor lo calcula y se lo pasa a la app. Es la misma firma que en el sitio web, con el correo, el nombre y los atributos firmados opcionales: Verificación de identidad en la página del 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()

Llama a identify en cada inicio de tu app en cuanto sepa quién es su usuario, y otra vez después de un inicio de sesión. En Android, si tu app tiene guardados el usuario y el hash, llámalo en Application.onCreate justo después de setup: Android puede iniciar tu app por un toque en una notificación sin abrir ninguna de tus pantallas. Llama a logout() cuando el usuario cierre sesión, también en un inicio en el que tu app ya no encuentre su sesión, y solo entonces: el SDK borra lo que guardó del visitante, también el chat de uno que nunca inició sesión, y el próximo chat empieza como un visitante nuevo y anónimo.

Nunca pongas el secreto de firma en tu app. Cualquiera que desempaque la app podría leerlo y chatear como cualquiera de tus usuarios.

Respuestas sin leer

unreadCount es la cantidad de respuestas que el visitante aún no leyó, en todas sus conversaciones, por ejemplo para un indicador en tu botón de ayuda. Léelo una vez para el primer valor: unreadCountDidChange en iOS y un UnreadCountListener en Android solo avisan de los cambios.

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 y tema

El chat habla el idioma fijo de la bandeja de entrada cuando tiene uno. Si no, sigue a tu app: en iOS el idioma en el que corre tu app, en Android el idioma del teléfono o el que el usuario eligió para tu app. Asigna a language una etiqueta de idioma como "de" o "pt-BR" para elegirlo tú en lugar del de la app; vale mientras la app esté en ejecución y nunca se guarda. Un idioma que el chat no conoce pasa a inglés.

El chat conoce los 10 idiomas para visitantes del chat del sitio web: inglés, alemán (con el du o el Sie que usa la bandeja de entrada), español, francés, portugués de Brasil, árabe (de derecha a izquierda), hindi, italiano, japonés y chino simplificado. Cada texto y cada etiqueta para lectores de pantalla está en ese idioma.

Los colores salen del color de marca de la bandeja de entrada, en una variante clara y una oscura. Por defecto el chat sigue a tu app: claro u oscuro como la pantalla sobre la que se abre. theme lo fija en system (por defecto), light, dark o inbox (la configuración propia de la bandeja, como en el sitio web).

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

El texto usa la fuente del sistema y crece con el tamaño de texto del teléfono. En Android, si tu app conserva solo algunos idiomas (localeFilters), el chat solo puede usar esos.

Notificaciones push

Sin push, una respuesta le llega al visitante mientras tu app está abierta: en el contador de respuestas sin leer, en la tarjeta y en el indicador del botón del chat. Con push, también le llega con la app cerrada. El SDK nunca habla con Apple ni con Google por su cuenta y no trae Firebase: tu app obtiene su token del dispositivo como ya lo hace y se lo pasa al SDK. Tampoco pide el permiso de notificaciones; eso lo hace tu app cuando le convenga.

En Deskwoot

  1. Abre Configuración → Bandejas de entrada → tu bandeja de entrada → Chat en tu app para iOS y Android de la bandeja de entrada cuyo token usa tu app.
  2. Para iOS: crea una clave de autenticación de APNs en tu cuenta de Apple Developer, en Keys. Pégala o súbela en Clave de autenticación de APNs (.p8) e ingresa su ID de clave, tu ID de equipo y el Bundle ID de tu app.
  3. Para Android: en Firebase, abre Configuración del proyecto, luego Cuentas de servicio, y genera una nueva clave privada. Pega o sube ese archivo en JSON de la cuenta de servicio.
  4. Haz clic en Guardar debajo de cada bloque. Deskwoot verifica la clave con Apple o con Google antes de guardarla, y el bloque muestra Conectado.

En tu app para iOS

Activa la capability Push Notifications del target de tu app. Pide el permiso y regístrate con Apple como tu app ya lo hace para sus propias notificaciones, y pásale el token del dispositivo a setPushToken en cada inicio. En el delegate del notification center, deja que el SDK se encargue de sus propias notificaciones:

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 una notificación que no es de Deskwoot. Para una de Deskwoot no muestra ningún banner mientras el visitante ve esa conversación. handleNotificationResponse abre la conversación y responde true; para tus propias notificaciones responde false. isDeskwootNotification(_:) distingue las dos en cualquier otro lugar. El SDK detecta solo si un token pertenece al sandbox de Apple o a producción.

En una app de SwiftUI, conecta este app delegate con @UIApplicationDelegateAdaptor. El SDK no hace swizzling de ningún método: tu app hace estas llamadas por su cuenta.

En tu app para Android

Tu app necesita Firebase Cloud Messaging. Pásale el token de registro de FCM a setPushToken una vez al inicio y en onNewToken, y reenvía los mensajes de Deskwoot en 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)
}

El SDK dibuja la notificación por su cuenta, en su propio canal de notificaciones y con el ícono de tu app (setNotificationIcon(resId) define otro). Un toque abre la conversación, y no aparece nada mientras el visitante ve esa conversación. Desde Android 13, tu app pide POST_NOTIFICATIONS cuando le convenga; sin ese permiso no aparece ninguna notificación.

Cuándo sale un push

Deskwoot envía uno por cada respuesta de tu equipo o de tu bot de IA, nunca por los mensajes del propio visitante. Si el visitante estuvo en línea un momento antes, Deskwoot espera 12 segundos y no envía nada si ya leyó la respuesta. El título dice quién escribió, y el texto muestra hasta 160 caracteres de la respuesta. Cuando tu usuario cierra sesión, el SDK quita las notificaciones de ese visitante y da de baja el teléfono de sus notificaciones push.

Qué agrega el SDK a tu app

QuéiOSAndroid
TamañoUnos 1.24 MB comprimido (la app en un zip, cerca de lo que entrega la App Store). Sin comprimir, 2.67 MB de código y 0.17 MB de textos en 10 idiomas.Unos 0.7 MB con todo lo que trae: una app mínima compilada con R8 pasa de 23 KB a 724 KB. Una app que ya incluye Kotlin, corrutinas y androidx paga menos. El AAR en sí pesa 1.7 MB.
PermisosNinguno. Agrega NSCameraUsageDescription solo si los visitantes pueden enviar fotos tomadas con la cámara; sin esa clave el menú de adjuntos ofrece la fototeca y archivos, que no necesitan permiso.Solo INTERNET. Las fotos vienen del selector de fotos del sistema y los archivos del selector de documentos del sistema; ninguno necesita permiso. La cámara pasa por la app de cámara del sistema, y el SDK pide el permiso de cámara solo cuando tu app lo declara por su cuenta.
DependenciasNinguna fuera de los frameworks de Apple.kotlinx-coroutines-android, androidx.annotation, androidx.core, androidx.activity, androidx.recyclerview, con lo que traen ellas mismas (androidx lifecycle, savedstate, collection y similares), pero sin androidx.profileinstaller. Sin OkHttp, sin Retrofit, sin biblioteca de JSON ni de imágenes, sin Firebase, sin Compose.
En tu appNada se ejecuta antes de setup, y el SDK no hace swizzling de ningún método.1 Activity (DeskwootActivity) y 1 FileProvider (DeskwootFileProvider), ambos sin exportar. Ningún service y ningún receiver. Antes de setup, el SDK solo guarda el contexto de tu app en su FileProvider, y no cambia ninguno de tus temas o estilos.
Al iniciar la appSin costo: setup hace cada paso de disco y de red en segundo plano.Sin costo: setup hace cada paso de disco y de red en segundo plano.

Medido para la versión 1.0.0. iOS: dos apps vacías que solo se diferencian por el SDK, build Release para iPhone (arm64); el binario sin símbolos tiene 2,744,720 bytes frente a 73,248 bytes sin el SDK. Android: una app mínima con 1 Activity.

Preguntas frecuentes

Aquí tienes las respuestas cortas. Para todo lo demás, pregúntale a Fynn abajo.

¿Hay un SDK para React Native o Flutter?

No. Deskwoot tiene SDKs nativos para iOS (Swift) y Android (Kotlin y Java) y ningún paquete para React Native ni Flutter. En una app hecha con ellos puedes mostrar el chat del sitio web en una web view con el modo integrado del widget, que se explica en la página del SDK del widget.

¿El chat funciona sin notificaciones push?

Sí. Mientras tu app está abierta, una respuesta aparece en el contador de respuestas sin leer, en la tarjeta de la parte inferior de tu app y en el indicador del botón del chat. Las notificaciones push suman las respuestas que llegan con la app cerrada.

¿Dónde aparecen las conversaciones de la app?

En la bandeja de entrada cuyo token del widget le pasas a setup. Con el mismo token que tu sitio web, los chats de la app y los del sitio comparten una bandeja de entrada, su configuración, tu equipo y tu bot de IA.

Demo interactiva de Deskwoot