--- title: Android slug: cp-sdconn-android docTags: createdAt: 2026-03-11T16:00:58.147Z --- ## Integración ### Desde archivo .aar 1. Generar el .aar ejecutando el script de build: :::BlockQuote cd sdconn-android ./build-aar.sh ::: 1. Copiar dist/sdconn-release.aar al directorio libs/ del módulo de la aplicación. 2. Agregar la dependencia en build.gradle.kts: :::BlockQuote dependencies \{ implementation(files("libs/sdconn-release.aar")) *// Dependencias transitivas (requeridas)* implementation("com.github.mik3y\:usb-serial-for-android:3.8.1") implementation("com.squareup.okhttp3\:okhttp:4.12.0") implementation("org.jetbrains.kotlinx\:kotlinx-serialization-json:1.7.3") implementation("org.jetbrains.kotlinx\:kotlinx-coroutines-android:1.9.0") implementation("androidx.security\:security-crypto:1.1.0-alpha06") } ::: 1. Agregar el repositorio de JitPack en settings.gradle.kts (necesario para usb-serial-for-android): :::BlockQuote dependencyResolutionManagement \{ repositories \{ google() mavenCentral() maven \{ url = uri("https\://jitpack.io") } } } ::: ### Desde módulo local Si se prefiere incluir el SDK como módulo del proyecto: 1. Copiar la carpeta sdconn/ al proyecto. 2. Agregar en settings.gradle.kts: :::BlockQuote include("\:sdconn") ::: 1. Agregar la dependencia: :::BlockQuote dependencies \{ implementation(project("\:sdconn")) } ::: ## Permisos El SDK declara estos permisos en su manifiesto (se fusionan automáticamente): :::BlockQuote \ \ ::: - **INTERNET** — Necesario para comunicarse con el dispositivo por HTTP y con la API de Mobbex. - **USB Host** — Necesario solo para conexión serial. Declarado como required="false" para que la app funcione en dispositivos sin USB Host (usando solo HTTP). ### Permisos USB Cuando se conecta un dispositivo USB, Android muestra un diálogo pidiendo permiso al usuario. Si se desea aceptar automáticamente, agregar un intent-filter en la Activity principal: :::BlockQuote \ \ \ \ \ \ ::: Con res/xml/device\_filter.xml: :::BlockQuote \ \ \ \ ::: ## Inicialización :::BlockQuote import com.mobbex.sdconn.SDConn import com.mobbex.sdconn.model.SDConnConfig *// Con valores por defecto* val sdconn = SDConn(context) *// Con configuración personalizada* val sdconn = SDConn(context, SDConnConfig( serialBaudRate = 115200, mobbexApiBase = "https\://api.mobbex.com", debug = true )) ::: Se recomienda crear una única instancia de SDConn a nivel de Application o usando inyección de dependencias. ## Configurar credenciales Las credenciales son la **Clave API** y el **Token de Acceso** de Mobbex. Son necesarias para que el SDK pueda crear operaciones de pago. :::BlockQuote sdconn.setCredentials( apiKey = "clave\_api\_mobbex", accessToken = "token\_de\_acceso\_mobbex" ) ::: Las credenciales se almacenan cifradas con EncryptedSharedPreferences (AES-256). Persisten entre sesiones de la aplicación. ### Verificar si están configuradas :::BlockQuote if (sdconn.credentialsConfigured) \{ *// Listo para operar* } ::: ### Borrar credenciales :::BlockQuote sdconn.clearCredentials() ::: ## Conectar un dispositivo ### Opción 1: Serial (USB) :::BlockQuote try \{ sdconn.connectSerial() *// Conectado — el estado cambia a Connected(mode="serial", detail="portName")* } catch (e: SDConnException) \{ *// No se encontró dispositivo USB serial* } ::: El SDK: 1. Busca todos los drivers USB serial disponibles. 2. Abre cada puerto y envía un mensaje HELLO. 3. El primer dispositivo que responda queda conectado. 4. Si ninguno responde, lanza SDConnException. ### Opción 2: Red (HTTP) La conexión HTTP requiere un proceso de emparejamiento con PIN: :::BlockQuote *// 1. Solicitar emparejamiento — el dispositivo muestra un PIN de 6 dígitos* sdconn.requestPairing(ip = "192.168.1.50", port = 5000) *// 2. El usuario lee el PIN de la pantalla del dispositivo* *// 3. Confirmar con el PIN* val device = sdconn.confirmPairing( ip = "192.168.1.50", port = 5000, pin = "847293" ) *// Conectado — el dispositivo queda en modo pinpad* *// Se guarda un token de confianza para futuras reconexiones* ::: ### Conexión HTTP directa (sin emparejamiento) Si solo se necesita conectar sin el flujo de pairing (por ejemplo, para pruebas): :::BlockQuote sdconn.connectHttp(ip = "192.168.1.50", port = 5000) ::: ### Reconexión automática Una vez emparejado un dispositivo, se puede reconectar sin PIN: :::BlockQuote if (sdconn.hasSavedDevice()) \{ try \{ val device = sdconn.reconnect() *// Reconectado a ${device.name} en ${device.ip}:${device.port}* } catch (e: SDConnException) \{ *// Dispositivo no alcanzable o token rechazado* } } ::: ### Observar el estado de conexión :::BlockQuote lifecycleScope.launch \{ sdconn.connectionState.collect \{ state -> when (state) \{ is ConnectionState.Disconnected -> showDisconnected() is ConnectionState.Searching -> showSearching() is ConnectionState.Connected -> showConnected(state.mode, state.detail) is ConnectionState.Error -> showError(state.message) } } } ::: ## Leer una tarjeta La operación de lectura ejecuta internamente: 1. Obtiene información del dispositivo (serial number, modelo) 2. Obtiene la ubicación GPS del dispositivo 3. Crea una operación en la API de Mobbex (o usa un token externo si se proporciona) 4. Envía el token al dispositivo para que lea la tarjeta 5. Devuelve los datos de la tarjeta junto con el intentToken utilizado ### Flujo estándar (genera token contra API) :::BlockQuote import com.mobbex.sdconn.model.ReadRequest val result = sdconn.read(ReadRequest( total = 15.00, currency = "ARS", hideAmount = false, test = false *// true para operaciones de prueba* )) if (result.result) \{ val sourceData = result.sourceData val token = result.intentToken *// Token generado por la API de Mobbex* *// Datos de la tarjeta leída: pin, emvData, cryptogram, ksn, track2...* } else \{ val error = result.error *// "TIMEOUT", "CANCELLED", "NOT\_IN\_PINPAD\_MODE", etc.* } ::: ### Flujo con token externo Cuando ya se tiene un intentToken generado externamente (por ejemplo, desde un backend propio), se puede enviar directamente. En este caso el SDK **no contacta a la API de Mobbex** y además incluye la geolocalización del dispositivo en la respuesta: :::BlockQuote val result = sdconn.read(ReadRequest( total = 15.00, currency = "ARS", intentToken = "eyJhbGciOiJIUzI1NiIs..." *// Token externo* )) if (result.result) \{ val sourceData = result.sourceData val token = result.intentToken *// Mismo token enviado* val geo = result.geolocation *// \[latitud, longitud] o null* *// Procesar datos...* } ::: :::BlockQuote **Nota:** Cuando se usa un token externo no es necesario tener configuradas las credenciales de Mobbex. ::: ### Flujo QR Para pagos por QR, enviar el campo source con la referencia del medio de pago: :::BlockQuote val result = sdconn.read(ReadRequest( total = 15.00, currency = "ARS", source = "arg.qr" *// Activa el flujo QR* )) if (result.result) \{ val operationId = result.operationId *// ID de la operación* val source = result.source *// "arg.qr"* val status = result.status *// \{ code: "100", text: "Pendiente" }* val token = result.intentToken *// Token utilizado* *// El QR se muestra en el dispositivo POS automáticamente.* *// Consultar el estado de la operación externamente.* *// Cuando el usuario escanee el QR y pague, el estado cambiará.* } else \{ val error = result.error } ::: :::BlockQuote **Nota:** El flujo QR siempre requiere credenciales configuradas. La respuesta no contiene sourceData ya que no se lee una tarjeta. Para cancelar la visualización del QR, llamar a cancelRead(). ::: ### Cancelar lectura :::BlockQuote sdconn.cancelRead() ::: Funciona tanto para cancelar una lectura de tarjeta como para quitar un QR de la pantalla del dispositivo. ## Mostrar resultado en pantalla Después de procesar el pago en el servidor, mostrar el resultado en la pantalla del dispositivo: :::BlockQuote import com.mobbex.sdconn.model.DisplayRequest *// Vista "result" — Pago aprobado (fire-and-forget)* sdconn.display(DisplayRequest( view = "result", *// o simplemente omitir (es el defecto)* status = "success", title = "Pago Aprobado", subtitle = "Visa \*\*\*\* 1234", total = 15.00, currency = "ARS", text = "ID: 123456", timeout = 10 )) *// Vista "result" — Pago rechazado* sdconn.display(DisplayRequest( status = "error", title = "Rechazado", timeout = 5 )) *// Vista "loading" — Procesando (fire-and-forget)* sdconn.display(DisplayRequest( view = "loading", title = "Procesando pago...", subtitle = "No retire la tarjeta", timeout = 30 )) *// Vista "choose" — Selección de cuotas (bloqueante)* val displayResult = sdconn.display(DisplayRequest( view = "choose", title = "Seleccione cuotas", subtitle = "Visa \*\*\*\* 1234", values = listOf( DisplayOption(label = "1 Pago - $15.00", value = "1"), DisplayOption(label = "3 Cuotas - $5.75 c/u", value = "3"), DisplayOption(label = "6 Cuotas - $3.08 c/u", value = "6") ), timeout = 60 )) if (displayResult != null && displayResult.result) \{ val selected = displayResult.selected *// selected?.label = "3 Cuotas - $5.75 c/u"* *// selected?.value = "3"* } else \{ *// Timeout o error* } *// Ocultar pantalla antes del timeout* sdconn.dismissDisplay() ::: ### Vistas de display | Vista | Comportamiento | Retorna | | --------- | ----------------------------------------------------------- | ------------- | | "result" | Muestra resultado con animación. Fire-and-forget. | null | | "loading" | Muestra spinner de carga. Fire-and-forget. | null | | "choose" | Muestra opciones. **Bloqueante** hasta selección o timeout. | DisplayResult | ### Valores de status (para vista result) **Por nombre:** | Valor | Animación | | --------- | --------------------------- | | "success" | Círculo verde con check | | "error" | Círculo rojo con X | | "neutral" | Círculo naranja con reloj | | "none" | Sin animación, fondo blanco | **Por código numérico:** | Códigos | Se resuelve a | | ---------------------------- | ------------- | | 3, 4, 200, 300-302, 605, 800 | success | | 400-417, 500, 603, 604 | error | | 1, 2, 100, 210, 600-602, 610 | neutral | | Otros | none | ## Desconectar :::BlockQuote *// Desconectar sin borrar datos guardados* sdconn.disconnect() *// Desconectar y borrar dispositivo + token de confianza* sdconn.forgetDevice() ::: ## Cambiar modo del dispositivo :::BlockQuote sdconn.setMode("pinpad") ::: | Modo | Descripción | | ------- | ------------------------------------------------------- | | normal | Modo POS estándar con pantalla de ingreso de monto | | slave | Modo cola. Recibe trabajos de pago desde una cola | | transit | Lectura continua de tarjetas para peajes/transporte | | pinpad | Modo pinpad. Espera comandos de lectura del controlador | ## Información del dispositivo :::BlockQuote val info = sdconn.getDeviceInfo() *// info.type, info.serialNumber, info.deviceExtras* val location = sdconn.getDeviceLocation() *// location.latitude, location.longitude, location.accuracy* ::: La información del dispositivo se cachea tras la primera consulta. La ubicación se consulta en tiempo real. ## Flujo completo de ejemplo :::BlockQuote class PaymentActivity : AppCompatActivity() \{ private lateinit var sdconn: SDConn override fun onCreate(savedInstanceState: Bundle?) \{ super.onCreate(savedInstanceState) sdconn = SDConn(this, SDConnConfig(debug = true)) sdconn.setCredentials("mi\_api\_key", "mi\_access\_token") lifecycleScope.launch \{ *// 1. Conectar por serial* try \{ sdconn.connectSerial() } catch (e: Exception) \{ showError("No se encontró dispositivo USB") return\@launch } *// 2. Leer tarjeta* val result = sdconn.read(ReadRequest(total = 100.00)) if (result.result) \{ *// 3. Enviar sourceData al servidor para procesar el pago* val paymentOk = processPaymentOnServer(result.sourceData!!) *// 4. Mostrar resultado en el dispositivo* if (paymentOk) \{ sdconn.display(DisplayRequest( status = "success", title = "Aprobado", total = 100.00 )) } else \{ sdconn.display(DisplayRequest( status = "error", title = "Rechazado" )) } } else \{ showError(result.error ?: "Error desconocido") } } } override fun onDestroy() \{ super.onDestroy() sdconn.disconnect() } } ::: ## Troubleshooting ### No se detecta el dispositivo USB - Verificar que el dispositivo Android soporte **USB Host** (la mayoría de tablets y POS lo soportan). - Verificar que el cable USB sea de datos (no solo de carga). - Verificar que el usuario haya aceptado el diálogo de permisos USB. - Activar debug = true en la configuración para ver logs detallados en logcat. ### Error "Device not reachable" en conexión HTTP - Verificar que el dispositivo POS y el dispositivo Android estén en la **misma red Wi-Fi**. - Verificar que el puerto (por defecto 5000) esté correcto. - Probar la conexión con un navegador: http\://\:5000/device/hello. ### Error "Mobbex credentials not configured" - Llamar a sdconn.setCredentials(apiKey, accessToken) antes de ejecutar read(). - Verificar que las credenciales sean válidas. ### Error "TIMEOUT" en lectura de tarjeta - El dispositivo no detectó una tarjeta en 120 segundos. - Verificar que el dispositivo esté en modo **pinpad**. - Verificar que el lector de tarjetas del dispositivo funcione correctamente. # Descarga ::File{src="https://api.archbee.com/api/presign/wYlzYU9oe8HZjh9BkqeFY/t48HPneaIgJJl8OFFXxKM-20260320-185754.aar" label="sdconn-release.20260320155729.aar"}