Diagnostica por el protocolo, no por la pantallaDebug through the protocol, not the screen
Un SDK que se traga errores puede mostrar un mensaje que no tiene nada que ver con la causa.
An SDK that swallows errors can show a message that has nothing to do with the cause.
Un escáner dentro de una app se quedaba en 100 % y nunca entregaba resultado. La pantalla decía "acércate un poco". La primera conclusión fue que el usuario estaba lejos de la cámara.
Lo que decía el protocolo
En los mensajes del WebSocket, cada fragmento enviado regresaba con un error de licencia: la credencial no era válida para esa plataforma. El SDK descartaba ese estado y la interfaz seguía avanzando con su propio reloj. Lo que se veía en pantalla no tenía relación con la causa.
La regla que adoptamos
- Ante una integración que falla, primero lee las respuestas crudas: estado y cuerpo de cada llamada REST, y los mensajes del WebSocket.
- Compara un intento fallido con uno sano usando la misma entrada, por ejemplo un video grabado que alimenta una cámara simulada.
- Una credencial nueva se da por buena solo cuando el paso real que la usa responde bien, no cuando el registro dice "ok".
Si una conclusión no tiene evidencia del protocolo, es una hipótesis. Escríbela así.
A scanner inside an app stuck at 100% and never returned a result. The screen said "move a little closer". The first conclusion was that the user was too far from the camera.
What the protocol said
In the WebSocket frames, every chunk sent came back with a license error: the credential was not valid for that platform. The SDK discarded that status and the interface kept moving on its own timer. What the screen showed had nothing to do with the cause.
The rule we adopted
- When an integration fails, read the raw responses first: status and body of every REST call, and the WebSocket frames.
- Compare a failing attempt with a healthy one using the same input, for example a recorded video feeding a simulated camera.
- A new credential is accepted only when the real step that uses it succeeds, not when registration says "ok".
If a conclusion has no protocol evidence, it is a hypothesis. Write it down as one.