RESUMEN

La demo de la App “iBKS Hello World” es un proyecto que contiene las funciones más importantes para comenzar a interactuar con un Beacon.

Este documento explica cómo está estructurado este proyecto, implementado para Android Studio, y cuáles son las funciones que se pueden encontrar en él.

PÚBLICO

Este documento está enfocado para desarrolladores de Apps que no tienen experiencia en la gestión de comunicación con beacons.

1. Antes de empezar
2. Proyecto iBKS Hello World
3. Permisos de la App
   1. Ubicación
   2. Bluetooth
4. Escanear dispositivos Bluetooth
5. Notificaciones
6. Escaneo en segundo plano

1.Antes de empezar

Todo lo que necesitas para comenzar a jugar con “iBKS Hello World”:

• Android Studio
• Dispositivo Android con versión 5.0 o superior
• Al menos un iBKS Beacon
• Descargar proyecto iBKS Hello World

2. Proyecto iBKS Hello World

Después de descargar el proyecto “iBKS Hello World”, solo tienes que abrirlo en Android Studio y compilarlo. Todas las bibliotecas necesarias están incluidas como dependencias y se descargan automáticamente.
El proyecto está estructurado para mostrar tres funcionalidades importantes, cada una en una clase diferente:

• ScanActivity: escanea y lista los beacons que están anunciando alrededor y permite el descubrimiento de servicios y características.
• NotificationDemo: Muestra un diálogo de notificación en la App activado por un paquete de beacon específico detectado.
• BackgroundScan: Inicia un escaneo en segundo plano que permite detectar beacons y realizar algunas acciones (enviar notificación, abrir la app, …) incluso cuando la app está detenida.
  La primera actividad iniciada en primer plano es “MainActivity” que muestra las diferentes opciones de la app y también verifica los permisos de la app.

 

3. Permisos de la App

Para gestionar Bluetooth en Android es necesario solicitar el permiso del usuario.

3.1. Ubicación

Si la versión de Android es 6.0 o superior, es necesario solicitar permiso de ubicación. Para hacer esto es necesario agregar permiso en AndroidManifest.xml

<uses-permission android_name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android_name="android.permission.ACCESS_FINE_LOCATION" />

El método que verifica los permisos de ubicación es checkLocBT() en MainActivity.

3.2. Bluetooth

Para usar Bluetooth en dispositivos Android, lo primero que hay que hacer es verificar si el dispositivo que ejecuta la app tiene Bluetooth Low Energy (los beacons funcionan con este tipo de protocolo) y si está habilitado. Para habilitar Bluetooth es necesario agregar permiso en AndroidManifest.xml

<uses-permission android_name="android.permission.BLUETOOTH" />
<uses-permission android_name="android.permission.BLUETOOTH_ADMIN" />

El método que verifica los permisos de ubicación es inicializeBluetooth() en MainActivity.

4. Escanear dispositivos Bluetooth

Todas las funciones necesarias utilizadas para escanear dispositivos Bluetooth están en ScanActivity. Los pasos para lograrlo son:

1. Inicializar el Adaptador Bluetooth y configurar los ajustes de escaneo: initBT()
2. Iniciar el Escaneo BLE con los ajustes definidos y el correspondiente ScanCallback: startLeScan()
3. Esperar paquetes Bluetooth en el callback ScanCallback (onScanResult) y realizar alguna acción dependiendo del RSSI, publicidad, etc.
4. Opcionalmente, conectar al dispositivo. En el proyecto, la conexión se realiza cuando se hace clic en un dispositivo de la lista: onItemClick¹.
5. Una vez realizada la conexión, se recibe un callback BluetoothGattCallback (onConnectionStateChange) y es posible descubrir servicios, leer y escribir las características y habilitar notificaciones (todas estas acciones generan un callback BluetoothGattCallback ). Al final de la clase ScanActivity hay algunos ejemplos de estas acciones.

¹ Nota: En dispositivos Samsung, la conexión debe hacerse en el hilo principal

 

La app muestra una lista de todos los dispositivos Bluetooth detectados con su propio RSSI y MAC.

5. Notificaciones

En algunos casos, es útil mostrar una notificación al usuario cuando se detecta un beacon específico en un rango de distancia particular. Este ejemplo se muestra en el NotificationDemo.

La forma más común de detectar un beacon específico es comprobando el identificador anunciado en el paquete Bluetooth, ya sea un paquete iBeacon o Eddystone-UID. Los pasos para lograrlo son:

1. Iniciar el escaneo como se ve en ScanActivity.
2. Esperar paquetes Bluetooth en el callback ScanCallback.
3. Comprobar si los datos de publicidad contienen el identificador deseado. En este proyecto, se utiliza el identificador introducido en el diálogo de configuración.
4. Opcionalmente, verificar el RSSI para activar la acción solo para un rango de distancia particular entre el beacon y el usuario. En este proyecto definimos tres rangos diferentes (Inmediato, Cercano, Lejano)
5. Si todas las condiciones son verdaderas, mostrar el diálogo con la información deseada: showDialog()

6. Escaneo en segundo plano

Otra función interesante es el escaneo en segundo plano. Este permite escanear publicidades cuando la app está en segundo plano y también iniciar algunas acciones cuando se detecta el beacon.
El ejemplo de un escaneo en segundo plano está en la clase BackgroundScan. Para ejecutar el proceso en segundo plano, es necesario agregarlo a AndroidManifest.xml (ya agregado en el proyecto):

<application android_name=".BackgroundScan"
...
</application>

El escaneo en segundo plano utiliza una biblioteca de código abierto externa. Para usar esta biblioteca es necesario agregar al app build.gradle la siguiente dependencia (ya agregada en el proyecto):

compile 'org.altbeacon:android-beacon-library:2+'

Los pasos para configurar el escaneo en segundo plano son:

1. Configurar Layouts de Beacon. En el proyecto hay un ejemplo de layouts iBeacon y Eddystone-UID, pero en la biblioteca de código abierto puedes encontrar más tipos de tramas.
2. Configurar el periodo de escaneo en primer plano y en segundo plano. Por favor, ten cuidado al elegir el periodo porque si es muy corto el dispositivo Android tendrá un alto consumo de batería debido a que Bluetooth está escaneando muy a menudo.
3. Crear las regiones. Es lo mismo que crear una lista de identificadores que se verificarán en cada periodo de escaneo.
4. Vincular la Actividad BackgroundScan al BeaconService (mBeaconManager.bind(this)). Cuando se recibe el callback onBeaconServiceConnection, habilitar las regiones e iniciar el escaneo (enableRegions()).
5. Esperar el callback llamado en cada periodo de escaneo, a través de la función didRangeBeaconsInRange, y verificar si se han encontrado los beacons.
6. Opcionalmente, se puede enviar una notificación al usuario cuando se detecta un beacon. Hay un código de ejemplo para crear una notificación en el proyecto.