En esta página
Android: Conectar mediante Bluetooth
Ejecuta @onekeyfe/hd-common-connect-sdk en una WebView y conecta su transporte de bajo nivel a BLE nativo. Empieza por el ejemplo nativo de Android y el contrato del Plugin de transporte de bajo nivel.
La capa nativa gestiona permisos, vinculación, conexión GATT, E/S de características y limpieza. El SDK gestiona detección de protocolo, tramas y firma. No añadas otro decodificador V1/V2 a la conexión nativa.
Permisos
Para una aplicación dirigida a Android 12 o posterior, solicita BLUETOOTH_SCAN y BLUETOOTH_CONNECT en tiempo de ejecución. BLUETOOTH_ADVERTISE no es necesario para un cliente que solo busca y conecta.
Usa neverForLocation solo si la aplicación no deduce la ubicación a partir de búsquedas BLE. Las versiones antiguas de Android requieren los permisos heredados de Bluetooth y ubicación correspondientes. No solicites incondicionalmente permisos exclusivos de Android 12 en dispositivos antiguos. Sigue la guía de permisos de Bluetooth de Android para tu SDK de destino y uso de ubicación.
No inicies búsquedas mientras el permiso esté pendiente. Devuelve un error de permiso al llamador JS si el usuario lo rechaza y permite un nuevo intento posterior iniciado por el usuario.
Compilar y cargar el bundle JavaScript
Desde el checkout de hardware-js-sdk:
cd packages/connect-examples/native-android-example/web
yarn
yarn buildCopia web_dist/ a app/src/main/assets/web_dist/. Registra los controladores del puente nativo antes de cargar file:///android_asset/web_dist/index.html. Conserva intactas las rutas de los recursos y carga únicamente el bundle de confianza de tu aplicación en una WebView con acceso al puente del dispositivo.
La demo incluye sus dependencias y la implementación de la conexión. Usa su configuración de paquetes/Gradle como punto de partida en vez de combinar fragmentos de versiones distintas de la biblioteca Nordic BLE.
Completar la conexión BLE antes de resolver
Una espera fija no demuestra que la vinculación, la conexión GATT, el descubrimiento o la suscripción a notificaciones hayan funcionado. Usa callbacks o las API suspendibles de finalización de la biblioteca BLE:
- Completa la vinculación necesaria e informa del rechazo del usuario o tiempo agotado.
- Espera a que se establezca la conexión GATT.
- Descubre el servicio OneKey y las dos características requeridas.
- Habilita notificaciones y espera a que se complete el descriptor o la suscripción.
- Resuelve la llamada
connectde la conexión solo cuando pueda enviar y recibir.
Android expone resultados de operaciones mediante BluetoothGattCallback. Que una llamada inicie una operación correctamente no significa que esta haya finalizado. Limita cada operación pendiente con un tiempo de espera; si falla, cierra la conexión y rechaza sus llamadas pendientes al puente.
| Finalidad | UUID |
|---|---|
| Servicio | 00000001-0000-1000-8000-00805f9b34fb |
| Escritura | 00000002-0000-1000-8000-00805f9b34fb |
| Notificar | 00000003-0000-1000-8000-00805f9b34fb |
Contrato de la conexión
| Método | Condición de finalización |
|---|---|
enumerate() | Devuelve una instantánea sin duplicados de los candidatos; detén la búsqueda y completa la solicitud una sola vez. |
connect(uuid) | Conexión, características y notificaciones listas. |
send(uuid, data, options) | Valida el hexadecimal, escribe los bytes en orden, respeta withoutResponse y propaga los errores de escritura. |
receive(uuid) | Devuelve como hexadecimal el siguiente bloque de notificación en cola, incluidos los recibidos antes de que hubiera un lector esperando. |
disconnect(uuid) | Cancela suscripciones, cierra la conexión seleccionada, rechaza lecturas pendientes y descarta notificaciones antiguas. |
Mantén colas y callbacks por conexión. Rechaza una característica ausente en vez de considerar correcta una escritura que puede no realizarse. Envía los callbacks de la conexión WebView en el hilo de interfaz apropiado.
Expón la capacidad real de escritura BLE mediante getProtocolV2PacketCapacity al implementar Protocol V2. No devuelvas la MTU ATT con su sobrecarga incluida. Consulta la interfaz completa del plugin.
Ciclo de vida del SDK y la interfaz
El bundle inicializa env: 'lowlevel' con tu plugin. Comprueba el resultado de inicialización, descubre una conexión y llama a getDeviceState(connectId) para obtener el identificador del ciclo de vida de la semilla deviceId.
Registra los controladores de eventos de interfaz antes de las llamadas protegidas. Responde solo a solicitudes de entrada y copia su correlación de respuesta. REQUEST_BUTTON y los avisos de PIN exclusivo del dispositivo son notificaciones; un botón nativo «Aceptar» no puede confirmar la operación en el hardware.
Pasa useEmptyPassphrase: true para la cartera estándar o el passphraseState de la cartera oculta seleccionada en llamadas de dirección y firma. Ejecútalas en serie por dispositivo.
Verificar la integración
Prueba denegación de permisos, cancelación de vinculación, fallos de descubrimiento y notificaciones, entrada con dispositivo bloqueado, desconexión y reconexión en un dispositivo físico. Confirma una dirección en el dispositivo e inspecciona el resultado del SDK. Encontrar un anuncio BLE no basta para superar una prueba completa.
No repitas automáticamente firmas ni actualizaciones de firmware tras un tiempo agotado. Consulta Desconexiones y reconexión.