Base de conocimiento de GetMyBot

SDK para aplicaciones (iOS, Android, React Native)

Cómo añadir el chat, los mensajes y las notificaciones móviles de GetMyBot a tu aplicación. Instalación del SDK, identificación del usuario y uso sin conexión.

En esta página

El SDK es una biblioteca para los desarrolladores de tu aplicación. Añade un chat de soporte y mensajes dentro de la aplicación (contenido in-app). Por ejemplo, un cliente escribe desde la aplicación de iOS y un operador responde en el mismo panel de GetMyBot donde atiende las consultas del sitio web.

Está disponible para iOS, Android y React Native. Primero se explican sus funciones y la configuración del proyecto; después, la integración en el código, la identificación del usuario y el contrato técnico. El chat usa el canal web del bot y los mensajes dentro de la aplicación usan documentos de Estudio de contenido.

Qué hace el SDK

  • Registra la instalación: la aplicación se registra una vez, recibe un token de instalación duradero y lo guarda en Keychain o Android Keystore.
  • Identifica al usuario: mientras sea anónimo, tiene un registro de visitante. Después de identify, la instalación se une a la persona identificada y comparte su historial con las otras secciones de MyBot.
  • Guarda operaciones sin conexión: los eventos, las propiedades del perfil, los indicadores de escritura y las operaciones con el token de notificaciones se guardan en el dispositivo y se envían en lotes ordenados cuando vuelve la conexión.
  • Ofrece chat: historial, envío de mensajes, adjuntos, contador de mensajes sin leer y posición de lectura en la misma conversación que usan los operadores.
  • Actualiza el chat al instante: los mensajes nuevos, modificados y eliminados llegan por WebSocket. La conexión usa un permiso de un solo uso llamado ticket.
  • Muestra contenido in-app: documentos de pop-up de Estudio de contenido, con recibos de visualización, acción y conversión.
  • Recibe notificaciones móviles: registra el token del dispositivo para difusiones y campañas. La entrega depende de la configuración del servidor y de que el token siga vigente.

Plataformas: iOS (Swift, iOS 15+, con interfaz para Objective-C y un módulo de UI opcional), Android (Kotlin, minSdk 24, con interfaz para Java) y React Native (TypeScript sobre los dos SDK nativos). Las tres implementan la misma especificación y se prueban con los mismos ejemplos de referencia; consulta Contrato.

Activa el proyecto

El SDK se configura para cada bot en una pantalla propia del panel. Al activarlo, indicas qué aplicaciones pueden usarlo y recibes dos elementos.

Listas de aplicaciones. Indica los bundle ID de iOS y los nombres de paquete de Android. Para crear el proyecto hace falta al menos uno; cada lista admite como máximo 64. Si una aplicación no está autorizada, el servidor responde igual que si la clave del proyecto fuera desconocida. La respuesta no permite distinguir ambos casos.

Clave del proyecto. Tiene el formato sdk1_eu_<24 hex>_<32 hex>. Es pública, como la clave de instalación del widget: puede incluirse en la aplicación sin dar acceso a las conversaciones ni a los ajustes. Su región sirve para que el panel muestre a qué despliegue pertenece el proyecto. El SDK transmite la clave tal como está y nunca intenta interpretarla.

Secreto de identidad. Es distinto de la clave del proyecto y nunca debe incluirse en la aplicación. Se muestra una sola vez al activar el proyecto y una vez más tras cada rotación. Cópialo entonces al almacén de secretos de tu servidor: después ni el panel ni la API podrán mostrarlo.

Rotación del secreto de identidad. Genera otro secreto y mantiene válido el anterior durante un día, para que puedas actualizar tu servidor. La clave del proyecto no cambia y las instalaciones existentes siguen funcionando.

Revocación de una instalación. La lista muestra plataforma, identificador de la aplicación, versión del SDK, idioma, zona horaria, si hay un usuario identificado y última actividad, hasta 200 instalaciones recientes. Eliminar un registro revoca inmediatamente el acceso de esa instalación.

Muchas instalaciones nuevas. Registrar una instalación crea un visitante y está sujeto al mismo límite por cuenta que el widget del sitio: durante un pico, el servidor responde 429 con Retry-After: 60. Una instalación ya registrada sigue trabajando con su token y no está sujeta a ese límite. Volver a registrarse, por ejemplo tras reinstalar la aplicación o borrar el almacén de claves, cuenta como una instalación nueva. Consulta Widget del sitio.

Secreto del despliegue CUSTOMER_SDK_KEY_SECRET

Este es un tercer elemento, distinto de la clave del proyecto y del secreto de identidad. Pertenece al despliegue completo de MyBot, no a tu proyecto. La clave del proyecto está firmada con este secreto, y la firma se comprueba cada vez que se inicia el SDK.

Hay dos consecuencias que debes tener en cuenta:

El servidor necesita el secreto del SDK. Si CUSTOMER_SDK_KEY_SECRET está vacío, la firma de la clave del proyecto no se valida. El registro de la instalación devuelve 401, como si la clave fuera desconocida; activar un proyecto nuevo devuelve 503. Un despliegue de producción no arranca sin este secreto. El administrador del servidor propio o de pruebas debe comprobar su configuración.

Rotarlo invalida todas las claves de proyecto emitidas. Una clave antigua no coincide con la firma creada con el secreto nuevo, y no es posible volver a firmarla: se guarda ya firmada. Después de cambiar CUSTOMER_SDK_KEY_SECRET, las aplicaciones que incluyen una clave anterior empezarán a recibir 401. Se necesita una clave nueva en otra versión de la aplicación, con un nuevo lanzamiento en las tiendas. Planifica este cambio como una modificación incompatible.

El secreto de identidad es independiente. Su rotación, con un día de solapamiento, no afecta a las claves de proyecto emitidas.

Instala e inicia el cliente

El código del SDK está en el repositorio móvil, dentro de customer-sdk/: paquete Swift MyBotSDK (customer-sdk/ios), módulo Gradle mybot-sdk en el espacio de nombres dev.gelfand.mybot.sdk (customer-sdk/android) y paquete npm @mybot/customer-sdk-react-native (customer-sdk/react-native).

Para iniciar el cliente necesitas la clave del proyecto, la URL base de tu despliegue de MyBot y el identificador de la aplicación. La compilación usa un solo servidor: el SDK no elige otro según la región de la clave.

let client = try await MyBotClient.start(
    configuration: Configuration(
        projectKey: "sdk1_eu_…",
        baseURL: URL(string: "https://api.getmybot.dev")!,
        appIdentifier: "dev.getmybot.example",
        sdkVersion: "1.0.0"
    )
)
val client = MyBotClient.start(
    context,
    MyBotConfiguration(
        projectKey = "sdk1_eu_…",
        baseUrl = "https://api.getmybot.dev",
    ),
)
const client = await MyBotClient.start({
  projectKey: "sdk1_eu_…",
  baseURL: "https://api.getmybot.dev",
  appIdentifier: "dev.getmybot.example",
});

El primer inicio registra la instalación y guarda su token; los siguientes continúan con el mismo registro. El token se entrega una sola vez. Si se pierde o sospechas que se ha filtrado, el SDK lo renueva sin cambiar la identidad.

Identidad: la firma tu servidor, no el dispositivo

El dispositivo no puede declarar por sí mismo quién es su usuario. La identificación consiste en una declaración firmada por tu servidor con el secreto de identidad; la aplicación solo transmite esa declaración sin interpretarla:

  1. La aplicación consulta a tu servidor la identidad del usuario.
  2. Tu servidor, que ya lo autenticó, emite un JWT de corta duración firmado con el secreto de identidad.
  3. La aplicación pasa esa cadena a identify. El SDK no la analiza.

El servidor valida la declaración de forma estricta y la rechaza por completo si incumple cualquier regla:

{
  "alg": "HS256",
  "project_key": "sdk1_eu_…",
  "aud": "mybot-customer-sdk",
  "jti": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "iat": 1730000000,
  "exp": 1730000120,
  "user_id": "acct_10293",
  "properties": { "plan": "pro", "role": "admin" }
}
  • El algoritmo debe ser HS256 y la audiencia mybot-customer-sdk. No se admiten los campos iss, sub ni nbf.
  • jti debe ser un UUIDv4 canónico; iat no puede estar en el futuro y exp - iat no puede superar 300 segundos.
  • user_id es tu identificador estable y opaco, de 1 a 256 bytes, no un correo o teléfono introducido en el dispositivo.
  • properties es opcional y admite hasta 16 entradas. Solo se permiten account_id, plan, role y locale, con valores de texto de hasta 256 bytes.

Repetir identify para el mismo usuario no cambia nada; identificar a otro traslada la instalación a esa persona. Esta API no recibe datos de contacto sin procesar. La misma lista cerrada de propiedades se aplica a la ruta del perfil y a las operaciones en cola.

Cerrar sesión incrementa la época de identidad

Si varias personas usan el mismo teléfono, los mensajes pendientes de una no deben enviarse como si fueran de la siguiente. Por eso cada instalación guarda un número para la sesión actual, llamado época de identidad. Empieza en 1, aumenta en uno al cerrar sesión y el servidor lo comprueba en cada solicitud. Las solicitudes de épocas anteriores se rechazan inmediatamente:

  • Las operaciones de la época anterior se eliminan de la cola y no vuelven a aceptarse. Aunque el cliente no las borrara, el servidor rechazaría el lote completo.
  • El contador local de secuencia vuelve a empezar en 1.
  • La conexión en tiempo real se cierra enseguida y los tickets emitidos antes del cierre ya no se pueden usar.
  • Se cancelan los envíos pendientes de la época anterior.
  • El servidor revoca los tokens de notificaciones de la época anterior en la misma transacción en que incrementa la época. La aplicación no necesita hacerlo al cerrar sesión.
  • Se limpian los datos locales vinculados a la persona anterior: asignaciones de contenido, contador de mensajes sin leer y campos del perfil guardados.

La conexión WebSocket necesita una explicación: su solicitud inicial no puede llevar la cabecera de época que llevan las demás solicitudes. El SDK obtiene un ticket de un solo uso por HTTPS. Cuando se usa, el servidor vuelve a leer de la base de datos la época de la instalación y la compara con la época registrada al emitirlo. Si el usuario cerró sesión entre ambos momentos, se rechaza la conexión aunque el ticket no se haya usado. Así, una aplicación con la sesión cerrada no puede entrar en el chat de otra persona.

Renovar el token no equivale a cerrar sesión: la época y el usuario se conservan. Tampoco se realizan las limpiezas ni cancelaciones anteriores.

Cola sin conexión

Las operaciones guardadas sin conexión se envían en lotes ordenados. Cada lote lleva un identificador generado por el cliente, la época y un intervalo continuo de números de secuencia.

OperaciónQué hace
track_eventregistra un evento del producto; en la práctica, el nombre debe cumplir ^[a-z][a-z0-9_.]{0,63}$, la más estricta de dos validaciones
set_propertiesestablece propiedades del perfil tomadas de la lista cerrada account_id, plan, role, locale
register_push_tokenguarda cifrado un token APNs o FCM, de sandbox o producción
revoke_push_tokenrevoca un token; si es desconocido, la operación termina correctamente y sin aviso
notification_openedregistra la apertura de una notificación, sin garantía estricta de entrega
in_app_impression, in_app_actionrecibos correspondientes a una asignación de contenido in-app
typingindica que se está escribiendo en el chat

Reglas del servidor:

  • Cada lote contiene entre 1 y 100 operaciones. Los números siguen exactamente desde el último lote aceptado: una interrupción o superposición rechaza todo el lote.
  • Si el identificador del lote ya se aceptó para esa instalación y época, la respuesta indica «duplicado» y no ejecuta las operaciones otra vez. Reintentar tras perder una respuesta es seguro.
  • Una época incorrecta rechaza todo el lote. Los demás errores se informan por operación, con un código de una lista cerrada: una propiedad incorrecta no descarta todos los eventos válidos.

Los límites locales son iguales en las tres plataformas, para que una aplicación sin conexión durante semanas no llene el almacenamiento. Se eliminan primero las operaciones pendientes más antiguas:

  • 2000 operaciones en cola por instalación;
  • 2 MiB de almacenamiento de la cola serializada;
  • 7 días de antigüedad, independientemente de los otros dos límites.

Una operación que se está enviando no se elimina. Cada eliminación provoca una llamada de diagnóstico con el identificador local y el motivo (cantidad, bytes o antigüedad), sin incluir el contenido. Un envío fallido se reintenta con una espera inicial de 30 segundos, que se duplica hasta 240 segundos con variación aleatoria. Un error de autorización no se reintenta.

Chat

Cuando el historial vinculado del sitio y la aplicación está disponible y activado, los SDK de iOS y Android pueden leer páginas del historial del sitio con metadatos de archivos adjuntos normales y descargar archivos de hasta 32 MiB. La descarga requiere una sesión autenticada activa; no se ofrecen URL públicas de archivos. El reenvío privado aún no es compatible. El historial se lee por páginas; este método no ofrece actualizaciones compartidas en tiempo real ni marca las conversaciones como leídas automáticamente.

Mientras está abierta la sección del historial vinculado, el widget del sitio comprueba periódicamente los mensajes nuevos de la aplicación y las ediciones o eliminaciones de mensajes ya cargados. La aplicación móvil puede comprobar cambios mediante llamadas explícitas al SDK; el SDK no inicia consultas en segundo plano. Es una comprobación periódica, no un tiempo real compartido completo. Las lecturas y notificaciones siguen siendo independientes para cada canal.

Para obtener el estado inicial, usa linkedWebHistorySnapshot en iOS o getLinkedWebHistorySnapshot en Android. Conserva mutationCursor separado de page.nextAfter. Cuando sea necesario, llama a linkedWebHistoryUpdates / getLinkedWebHistoryUpdates con ambos cursores y hasta 500 ID de mensajes visibles. Si hasMutations es verdadero, vuelve a leer el intervalo mostrado con through, conserva el límite original de la página y aplica las eliminaciones. Si la página inicial está vacía y no tiene nextAfter, pasa nil/null o una cadena vacía como after: el SDK comprueba desde 0. Los servidores antiguos pueden omitir mutationCursor; descarta los cursores al cerrar sesión.

Para confirmar la visualización en la aplicación móvil, llama explícitamente a markLinkedWebHistorySeen(messageIds:) en iOS o a markLinkedWebHistorySeen(messageIds) en Android. Pasa hasta 500 ID solo de mensajes entrantes del operador (direction: "in") realmente mostrados al visitante. En la sección abierta y visible del historial vinculado, el widget del sitio marca automáticamente los mensajes visibles. Esto puede cancelar un correo de respaldo por respuesta no leída que aún no se haya enviado, pero no retira un correo ya enviado ni sincroniza el contador de no leídos del chat SDK.

Para obtener el contador independiente de mensajes del historial web vinculado sin confirmación de visualización, la aplicación llama a linkedWebUnreadCount() en iOS o a getLinkedWebUnreadCount() en Android. Cuenta los mensajes del operador creados después de confirmar la vinculación que no se hayan marcado como vistos. Marcar los mensajes realmente mostrados afecta al siguiente resultado. La lectura en el chat principal del SDK puede no reflejarse, por lo que no es un contador exacto de no leídos. nil/null significa que el servidor no admite el contador, no que sea cero. Este contador es independiente del contador principal de no leídos del chat SDK, no se actualiza automáticamente en segundo plano ni por push y la aplicación decide cuándo consultarlo.

Si la vinculación del sitio con el SDK está disponible y activada en el servidor (WEB_SDK_LINK_ENABLED, desactivado por defecto), se puede consultar una instantánea conjunta de ambos historiales. El chat normal sigue disponible y los operadores conservan diálogos separados. La instantánea devuelve primero los mensajes más recientes, usa nextCursor opaco para paginar e incluye bloques seguros y metadatos de adjuntos normales. unsupportedBlocks: true indica que se omitió parte del contenido; el reenvío privado no es compatible. Descarga los adjuntos con autorización mediante downloadMergedHistoryAttachment.

Para conservar una instantánea conjunta, usa versionedMergedWebHistory en iOS o getVersionedMergedWebHistory en Android. Compara linkVersion entre páginas y compruébalo explícitamente con mergedHistoryLinkVersion / getMergedHistoryLinkVersion antes de volver a mostrar el historial guardado y tras reanudar la aplicación. Si cambia la versión o no se puede verificar el acceso, borra páginas, cursores y adjuntos guardados; cerrar sesión también los invalida. La vista conjunta no ofrece tiempo real compartido, no marca mensajes como vistos ni inicia consultas en segundo plano.

Mientras la instantánea conjunta está abierta y visible, el widget comprueba periódicamente los cambios y ofrece actualizar el historial manualmente. Esta señal es orientativa, no una cola garantizada de eventos ni tiempo real; los diálogos de operadores siguen separados.

En la aplicación móvil, llama a observableMergedWebHistory en iOS o a getObservableMergedWebHistory en Android para obtener la primera página y conservar su updatesBaseline opaco. Si falta, el servidor no admite estas comprobaciones. Cuando sea necesario, llama a mergedWebHistoryChanges / getMergedWebHistoryChanges con ese baseline y hasta 500 ID de mensajes visibles. hasNew indica mensajes nuevos y hasChanged ediciones o eliminaciones entre los ID enviados; la respuesta no contiene los mensajes. Estas comprobaciones son orientativas y pueden omitir cambios confirmados simultáneamente; un valor falso no garantiza que la instantánea esté actualizada. Actualiza el historial cuando necesites datos actuales. Compara linkVersion con la instantánea y borra páginas, cursores y adjuntos si cambia o no se puede verificar el acceso. Tras actualizar, obtén la primera página con un baseline nuevo. El SDK no inicia consultas en segundo plano.

El chat es el canal web del bot visto desde la aplicación: comparte mensajes, bandeja de entrada del operador y activadores de automatización.

  • Historial: se recorre desde un cursor, hasta 50 mensajes por página. direction se define respecto al cliente: in indica que el mensaje viene del operador o del bot.
  • Envío: recibe un identificador de mensaje generado por el cliente y responde «en cola». Esto significa «aceptado para entregar», no «entregado». El estado real llega en tiempo real o al volver a consultar el historial. Repetir el mismo identificador y texto no crea otro mensaje; usar el mismo identificador con otro texto produce un conflicto y revela un error en la aplicación.
  • Adjuntos: se sube un archivo a la vez, de hasta 10 MiB. Dentro del bot se eliminan duplicados mediante el hash del contenido y se devuelve una URL lista para usar.
  • No leídos: se cuentan por instalación según su propia posición de lectura, independientemente de la lectura del operador. Esa posición solo avanza.
  • Tiempo real: transmite mensajes nuevos, modificados y eliminados, además de los indicadores de escritura. Al conectar, el servidor entrega hasta 50 eventos perdidos mientras no había conexión y después transmite los nuevos. El cliente no proporciona un cursor para reconectar.

Si el propietario del bot no ha conectado el canal web, todas las rutas de chat responden que la función no está disponible para ese bot. Muéstrala como una función desactivada, no como un error temporal.

Contenido in-app

GET /sdk/v1/content devuelve los elementos ya asignados: tipo, prioridad, demora, reglas de visitas y frecuencia, bloques y apariencia. Una lista vacía es una respuesta normal.

La segmentación decide quién recibe cada elemento. Un pop-up cuya selección de dispositivos excluya los móviles no aparecerá en el SDK; si no tiene ninguna restricción por dispositivo, se considera apto para todos. La variante se asigna de forma determinista para cada persona: un usuario anónimo sigue viendo la misma hasta que identify o el cierre de sesión vuelven a calcular la asignación.

Hay tres tipos de recibos: impression, action y conversion. Si el usuario descarta un mensaje deslizando el dedo, su estado final se guarda en el cliente, sin evento del servidor, igual que al cerrar un pop-up del sitio.

Tokens de notificaciones móviles

register_push_token guarda un token APNs o FCM para la instalación y la época de identidad actuales. El token se almacena cifrado y revoke_push_token lo revoca. Revocar uno desconocido cuenta como operación correcta, para que la respuesta no revele si el token de otra persona está registrado. Los datos de la instalación participan en la exportación y eliminación de datos del usuario, pero los tokens no se incluyen en la exportación.

La configuración del SDK devuelve pushEnabled: true: la plataforma admite la entrega de notificaciones móviles. Para enviarlas, el administrador del servidor debe configurar FCM; si también configura APNs, la plataforma puede enviar directamente a iOS. Un documento publicado de tipo Push puede enviarse por el canal mobile_push en una difusión o campaña. Las notificaciones para operadores del panel usan otra audiencia y otro almacén de dispositivos.

Al cerrar sesión, el servidor revoca los tokens activos de la época de identidad anterior. Tras iniciar otra sesión, registra de nuevo el token para la nueva época. Solo se puede enviar a una instalación activa con un token válido.

Errores

Cada error de /sdk/v1 es un objeto JSON de un solo campo. El SDK lo clasifica por su estado HTTP:

EstadoSignificadoQué hace el SDK
400datos de entrada incorrectosno reintenta; muestra un error del cliente
401autorización denegada: época anterior, token revocado, proyecto desconocido o ticket ya usadono reintenta con la misma credencial
404asignación de contenido desconocida o ajenala descarta como definitivamente no válida
409chat no disponible para ese bot o conflicto de idempotenciamuestra el error sin reintentar
413adjunto de más de 10 MiBmuestra el error antes de cualquier reintento
500, 503error temporalreintenta las operaciones idempotentes con una espera progresiva

Privacidad y diagnóstico

Ninguna ruta del SDK devuelve datos de contacto sin procesar y la lista de propiedades permitidas es cerrada. El diagnóstico está desactivado por defecto. Si se activa, solo incluye un código de evento de una lista cerrada, fecha y hora y metadatos numéricos sin datos personales. Nunca incluye tokens, declaraciones de identidad, tokens de notificaciones, URL ni el contenido de mensajes, propiedades o documentos. Las instalaciones del SDK pertenecen a la categoría de conservación sdk_diagnostics, con un plazo predeterminado de 180 días, y participan en la unificación, exportación y eliminación de los datos de suscriptores.

Contrato

El protocolo del SDK está separado de la API REST del propietario. Un token personal no funciona en /sdk/v1 y un token de instalación no funciona en /api. La descripción de las rutas en formato OpenAPI está disponible sin autenticación:

GET https://tu-servidor/sdk/openapi.yaml

Las reglas que deben implementar los clientes están en customer-sdk/contract/behavior.md del repositorio móvil: transiciones de estado, orden de operaciones, límites de la cola, tiempos de espera y tratamiento de errores. Junto a ellas hay una descripción de estructuras, enumeraciones, límites y patrones obtenida automáticamente del servidor, además de 75 ejemplos de prueba de referencia.

Un script vuelve a generar esa descripción a partir del backend y detecta cambios no reflejados en el contrato. Las pruebas de iOS, Android y React Native usan los mismos ejemplos para comprobar que se comportan igual.

API y MCP

Las rutas de gestión del proyecto están disponibles con un token personal; consulta API REST y tokens. Para leer se necesitan el alcance customer_sdk:read y el permiso customer_sdk.read del bot. Para modificar se necesitan customer_sdk:write y customer_sdk.write; activar el proyecto y rotar el secreto también requieren integrations.secrets. MCP ofrece dos herramientas de solo lectura; consulta MCP.

Siguientes pasos