IBeacon Ionic - Así es cómo se usan

¿Tu app necesita recibir información desde otro dispositivo a través de IBeacon Ionic? O, quizás ya sabes cómo se hace, pero te falta algún detalle más para sacarle todo su rendimiento ¿verdad?

Mi nombre es Aitor Sánchez, soy desarrollador de apps 2014, y en el artículo de hoy aprenderás a utilizar, de manera sencilla y eficaz, el componente IBeacon Ionic dentro de tus aplicaciones y como lo vas a poder configurar a tu antojo.

Pero antes de continuar, esta es la Flutter Mafia. Es mi newsletter donde tu vas a aprender a hacer apps y a ganar dinero con ellas junto con otros genietes que ya están dentro. Y si te suscribes te regalo mi ebook "Duplica los ingreso de tus apps en 5 minutos" No es broma, quizás te interese.

Y ahora si, comenzamos. Let´s go!

Pero qué es iBeacon Ionic

iBeacon es una tecnología “inventada” por Apple que se implementó en la versión iOS 7. Y que nos permitirá, de manera totalmente transparente para el usuario, interactuar con otros dispositivos cercanos. Cómo, por ejemplo, mandar notificaciones push a estos.

El sistema de iBeacon Ionic utiliza una capa de Bluetooth de bajo consumo para tal fin. E imita el comportamiento de CLLocationManager de dicha plataforma.

Instalación del componente iBeacon para Ionic

Cómo con todos los componentes desacoplados del core del sistema, es necesario que instalemos el componente en nuestra app. Para ellos vamos a usar las dos siguientes líneas de consola.

ionic cordova plugin add cordova-plugin-ibeacon
npm install @ionic-native/ibeacon

La primera instalar el plugin que nos permite la comunicación con la parte nativa del sistema donde se esté ejecutando.

La segunda instalará el código TS que hará de puente entre nuestro código TypeScript y el plugin.

Configuración del módulo

En caso de que estemos utilizando una versión inferior a Ionic 4, o no estemos usando la librería NGX, tendremos que añadir nuestro componente iBeacon Ionic a los providers de nuestra clase.

providers: [

…,

IBeacon,

…

]

Aunque lo recuerdo siempre en los tutoriales, es muy recomendable que solo se coloque en los providers del componente que lo vaya a utilizar en lugar del módulo “AppModule” de nuestra app.

De esta manera incurrimos en buenas prácticas de desarrollo y mejoramos el rendimiento general de nuestra app.

Plataformas soportadas

Aunque hayamos dichos que esto es una tecnología creada por Apple también estará disponible para las siguientes plataformas:

• Android
• iOS

Sorpresita, Android está entre ellas. Así que mejor aún, más cosas podremos realizar.

Cómo usar iBeacon en Ionic

Ahora vamos con lo que nos interesa, el código de ejemplo. De aquí vamos a poder sacar la chicha y después comentamos en escrito.

import { IBeacon } from '@ionic-native/ibeacon/ngx';

constructor(private ibeacon: IBeacon) { }

...


// Request permission to use location on iOS
this.ibeacon.requestAlwaysAuthorization();
// create a new delegate and register it with the native layer
let delegate = this.ibeacon.Delegate();

// Subscribe to some of the delegate's event handlers
delegate.didRangeBeaconsInRegion()
  .subscribe(
    data => console.log('didRangeBeaconsInRegion: ', data),
    error => console.error()
  );
delegate.didStartMonitoringForRegion()
  .subscribe(
    data => console.log('didStartMonitoringForRegion: ', data),
    error => console.error()
  );
delegate.didEnterRegion()
  .subscribe(
    data => {
      console.log('didEnterRegion: ', data);
    }
  );

let beaconRegion = this.ibeacon.BeaconRegion('deskBeacon','F7826DA6-ASDF-ASDF-8024-BC5B71E0893E');

this.ibeacon.startMonitoringForRegion(beaconRegion)
  .then(
    () => console.log('Native layer received the request to monitoring'),
    error => console.error('Native layer failed to begin monitoring: ', error)
  );

• En primer lugar, importaremos la clase iBeacon del módulo “@ionic-native/ibeacon/ngx”.
• Posteriormente, inyectaremos una instancia de dicho componente a través del constructor de nuestra clase.
• requestAlwaysAuthorization() será la función que muestre el diálogo para solicitar los permisos de localización en iOS. No será necesaria en Android, de momento.
• En la siguiente línea, creamos una instancia de “IBeaconDelegate” que será la encargada de llevar a cabo todo el tinglado.
• Posteriormente nos suscribimos a los eventos que veamos necesarios en nuestra app. La lista la veremos más abajo en el artículo.
• Con la función “BeaconRegion” creamos un beacon para nuestro dispositivo y que así otros nos puedan encontrar.
• Y, por último, podremos el sistema en marcha y a la escucha con la función “startMonitoringForRegion”. Si todo ha ido bien, están bien los permisos y demás, la promesa se resolverá para avisarnos de que todo está guay.

Nota importante: Recuerdo que este código está sujeto a errores. Es un ejemplo rápido que hemos tomado para poder ilustrar mejor todo esto. Habría que refactorizarlo si queremos usarlo.

Lo he hecho así para que todo se vea mucho más claro y conciso.

Funciones y métodos de la clase

Ahora vamos a pasar a ver toda la información profunda del componente y así podremos saber hasta dónde puede llegar.

Recuerdo que solo serán funciones y campos de la clase. Los del padre no aparecerán aquí.

Delegate()

• No recibe parámetros.
• Retorna una instancia de la clase IBeaconDelegate cómo hemos visto en el ejemplo. La detallaré más abajo.

Básicamente nos devuelve una instancia de la clase que se va a encargar de realizar todo el trabajo que necesitemos realizar con el componente, IBeaconDelegate.

BeaconRegion(identifier, uuid, major, minor, notifyEntryStateOnDisplay)

• Parámetros:
  • Identifier: string -> Será el identificador de la región. En el caso de ejemplo “deskBeacon” y será mostrada en el otro dispositivo cuando se “vean”.
  • uuid: string -> Será el identificador del dispositivo. Basta con inyectar una instancia de “Device” y hacer algo así: this.device.uuid;
  • major: number -> La distancia principal que se usará para identificar el resto de beacons.
  • minor: number -> La distancia mínima que se usará para identificar un beacon.
  • notifyEntryStateOnDisplay: booleano -> Cómo su nombre indica, se notificará al usuario mediante una notificación push cuando algún dispositivo entre dentro de la distancia de reconocimiento.
• Retorna una instancia de “BeaconRegion” que nos servirá cómo filtro para la inicialización del sistema.

Con esta función crearemos el “filtro” que nos permitirá identificar otros beacons según lo que necesitemos.

getDelegate()

• No recibe parámetros.
• Retorna una instancia de IBeaconDelegate que hemos creado con anterioridad. A diferencia del método “Delegate” que nos devuelve una nueva.

setDelegate(delegate)

• Parámetros:
  • delegate: IBeaconDelegate -> Será una instancia de un delegado que setearemos al sistema del Ibeaon de Ionic.
• Retorna una instancia del nuevo delegado, IBeaconDelegate.

En caso de que queramos cambiar de delegado, por que le hemos cambiado, por ejemplo, la región, esta será la función que tenemos que utilizar.

onDomDelegateReady()

• Esta función no recibe parámetros.
• Retorna una promesa que tendremos que controlar.

Bien, esta promesa, aunque no la hayamos visto en el ejemplo, es muy importante. Nos permitirá, en definitivas cuentas, saber cuándo está todo listo para poder empezar a usar el sistema.

No la hemos usado en el ejemplo, por que cómo he dicho, necesitaba algo funcional, pero con esto será algo un poco más tedioso de programar, pero será mucho más seguro.

isBluetoothEnable()

• No recibe parámetros.
• Retorna una promesa que tendremos que controlar. Con ella llegará un booleano que nos permitirá conocer si está activo o no el Bluetooth.

Al igual que la anterior, nos sirve para checkear cosas, en este caso el Bluetooth, antes de hacer nada. Más seguridad y estabilidad para nuestra aplicación.

enableBluetooth()

• Solo disponible para Android.
• No recibe parámetros.
• Retornará una promesa que tendremos que controlar. En caso de que se resuelva, el bluetooth ser habrá activado. En caso contrario, fallará y saldrá por le catch.

Cómo el propio nombre indica, este método de iBeacon Ionic nos permite activar el Bluetooth del dispositivo. Y, cómo era de esperar, solo estará disponible para Android.

disableBluetooth()

• Solo disponible para Android.
• No recibe parámetros.
• Retornará una promesa que tendremos que controlar. En caso de que se resuelva, el bluetooth ser habrá desactivado. En caso contrario, fallará y saldrá por le catch.

Cómo el propio nombre indica, nos permite desactivar el Bluetooth del dispositivo. Y, cómo era de esperar, solo estará disponible para Android.

startMonitoringForRegion(region)

• Parámetros:
  • region: Region -> Una instancia de la clase Region, se creará cómo hemos visto más arriba, que servirá de filtro para nuestra búsqueda/región.
• Retorna una promesa que tendremos que controlar. Con ella llega una cadena que contiene los datos de la inicialización.

Bien, esta función es la que pone a funcionar todo el sistema para que nos puedan encontrar y nosotros encontrar al resto de dispositivos.

Se ejecutará de manera totalmente asíncrona a la ejecución normal del programa.

Por otro lado, en caso de que ya exista otro beacon con el mismo ID este se eliminará y se usará el último instanciado en su lugar.

Recordamos, que una vez lanzado el sistema priorizará las regiones con tamaños más pequeños frente a las regiones más grandes a la hora de trabajar. El tamaño se lo asignaremos cómo hemos visto más arriba en este artículo.

stopMonitoringRegion(region)

• Parámetros:
  • region: Region -> La instancia de la región que queremos parar de monitorizar.
• Retorna una promesa que tendremos que controlar. Se resolverá en caso de que todo haya ido bien y se haya dejado de monitorizar esa región.

Cómo su nombre indica, detendrá el seguimiento de la región que le pasemos cómo parámetros. Se podrá llamar incluso para detener escuchas lanzadas previamente y por un monitor distinto.

Esta función se ejecuta de manera totalmente asíncrona.

requestStateForRegion(region)

• Parámetros:
  • region: Region -> Será la región de la que queremos obtener el estado.
• Retorna una promesa que se resolverá en caso de que todo haya ido correctamente.

Esta función forzará una actualización del evento “didDetermineStateForRegion” si es que estamos suscritos a él. De lo contrario no hará nada.

Esta función de iBeacon Ionic se ejecutará de manera totalmente asíncrona.

startRangingBeaconsInRegion(region)

• Parámetros:
  • region: Region -> Una instancia de la región que queremos comenzar a medir.
• Retorna una promesa que se resolverá en caso de que haya ido todo bien.

Esta función nos permitirá comenzar a medir las distancias a las que se encuentran los beacons que estén dentro del área designada por la región que hemos pasado por parámetros.

En el caso de que haya una región siendo medida con el mismo ID, esta última que hemos llamado la remplazará.

Esta función se ejecuta de manera totalmente asíncrona.

stopRangingBeaconsInRegion(region)

• Parámetros:
  • region: Region -> Una instancia de la clase Region que queremos dejar de medir.
• Retorna una promesa que se resolverá en caso de que todo haya ido bien.

Al contrario que el método anterior, esta función nos permitirá dejar de medir las distancias de los dispositivos en una región para conocer los datos de los Beacons que hay dentro de ella. Se podrá usar para detener cualquier sistema de medición que hayamos inicializado antes en la app o en otro componente.

Esta función se ejecuta de manera totalmente asíncrona.

getAuthorizationStatus()

• Esta función no necesitas parámetros.
• Retornará una promesa que resolverá en caso de que todo haya ido bien. Con ella llegará una instancia de “IBeaconPluginResult” que más abajo del artículo veremos los campos que tiene.

Esta función solicitará a la parte nativa del sistema los permisos de los que disponemos para poder hacer uso del sistema.

requestWhenInUserAuthorization()

• Esta función no recibe parámetros.
• Retorna una promesa que tendremos que controlar. Se resolverá en caso de que todo haya ido bien.

Básicamente, solicita de forma explícita al sistema los permisos para poder usar esta funcionalidad. La diferencia, es que esta función pondrá en marcha toda la maquinaria una vez hayan sido aceptados los permisos.

Esta función de iBeacon Ionic solo será necesario usarla en SO iOS 8+ y en Android no será necesario que la utilicemos.

requestAlwaysAuthorization()

• Esta función no recibe parámetros.
• Retornará una promesa que se resolverá en caso de que todo haya ido correctamente. Dicha promesa se resolverá cuando el diálogo de la solicitud de permisos haya sido mostrado.

A diferencia del resto de solicitudes, esta función hará que el diálogo se muestre aún cuando los permisos ya han sido aceptados.

getMonitoredRegions()

• Esta función no recibe parámetros.
• Retornará una promesa que tenemos que controlar. En caso de que se resuelva todo habrá ido bien. Con ella llegará un array de regiones que son las que están siendo monitorizadas.

Esta función nos permitirá acceder a las regiones que están siendo monitorizadas para que podamos operar con ellas.

getRangedRegions()

• Esta función no recibe parámetros.
• Retornará una promesa que tendremos que controlar. En ella llegará un array con las regiones que están siendo medidas.

Esta función es muy similar a la anterior, pero la diferencia es que retorna las regiones que tienen sistema de medición de distancias en lugar de monitorizadas.

isMonitoringAvailableForClass(region)

• Parámetros:
  • region: Region -> Una instancia de la clase Region que queramos saber si puede ser usadas para montarla sobre el sistema.
• Retornará una promesa que hay que controlar. Con ella llegará un booleano que nos permitirá saber si se puede usar o no.

Básicamente, realizará una comprobación para ver si la región que estamos solicitando se podrá usar o no.

startAdvertising(region, measuredPower)

• Parámetros:
  • region: Region -> Será la región a la que queremos enviar la solicitud de contacto.
  • measuredPower: number (opcional) -> Nos permite definir el nivel del rango a donde queremos enviar la publicidad. Los rangos los hemos visto más arriba en el artículo.
    En caso de que no se especifique se usará el que esté por defecto en el dispositivo.
• Retorna una promesa que hay que controlar. En caso de que todo haya ido bien se resolverá.

Bien, esta función nos permite emitir el contacto desde el dispositivo emisor a todos los dispositivos que estén aceptados dentro de la región que le hemos solicitado.

stopAdvertising()

• Esta función no recibe parámetros.
• Retornará una promesa que tendremos que controlar. En caso de que se resuelva es que todo ha ido bien y se ha dejado de emitir el mensaje.

Al contrario que la función anterior, esta detiene la emisión del mensaje a los receptores autorizados dentro de cualquier región que esté incluida en las regiones monitorizadas.

isAdvertisingAvailable()

• Esta función no recibe parámetros.
• Retornará una promesa que tendremos que controlar. En caso de que se resuelva es que podremos enviar el mensaje. En caso contrario, no está disponible y saldrá por el reject.

Básicamente, nos permite conocer si podemos hacer uso del sistema de envío de mensajes que monta el sistema.

isAdvertising()

• Esta función no recibe parámetros.
• Retorna una promesa que tendremos que controlar. En caso de que se resuelva es que ya está enviado el mensaje a los receptores. En caso contrario saldrá por el reject.

Cómo su nombre indica, nos permitirá comprobar si ya se está emitiendo el mensaje o no. En caso de que la promesa se resuelva es que está emitiendo. En caso contrario, de que no se pueda, saldrá por el reject.

Si falla por alguna razón, saldrá por el catch.

disableDebugLogs()

• Esta función no recibe parámetros.
• Retorna una promesa que hay que controlar. En caso de que se resuelva es que todo ha ido bien y ya no se mostrarán más los logs.

Básicamente, y cómo su nombre indica, nos permite desactivar los logs del sistema.

enableDebugLogs()

• Esta función no recibe parámetros.
• Retorna una promesa que hay que controlar. En caso de que se resuelva, todo habrá ido bien y se comenzarán a mostrar los logs.

Al contrario que la función anterior, esta nos permite volver a activar los logs.

enableDebugNotifications()

• Esta función no recibe parámetros.
• Retorna una promesa que hay que controlar. En caso de que se resuelva es que todo habrá salido bien y a partir de ahora se empezarán a enviar notificaciones de depuración.

Con esta función podremos depurar el envío de notificaciones mediante métodos cómo “startAdvertising”.

disableDebugNotifications()

• Esta función no recibe parámetros.
• Retorna una promesa que hay que controlar. En caso de que se resuelva es que las notificaciones de depuración han sido desactivadas.

Al contrario que el método anterior, este dejará de enviar notificaciones de depuración.

appendToDeviceLog(message)

• message: string -> Será una cadena que será mostrada en el log del dispositivo.
• Retorna una promesa que hay que controlar. Si se resuelve es que todo habrá ido bien y se habrá mostrado el mensaje en el log.

Escribe un mensaje en el log del sistema dentro del dispositivo.

Campos de IBeacon para Ionic

Ahora, cómo hemos ido diciendo a lo largo de todo el artículo, vamos a ver los campos de los que disponemos en iBeacon Ionic y las propias interfaces que nos permiten hacer uso de todo el sistema.

Beacon

• uuid: string -> Será el identificador físico del dispositivo.
• major: number -> Será el principal identificador del beacon. Para profundizar un poco, será el rango normal de aparición.
• minor: number -> Será el mínimo identificador del beacon. Para profundizar un poco, será el rango mínimo de captación de otros beacons.
• proximity: string -> Será la proximidad a la que tienen que estar el resto de beacons para ser identificados. Tenemos los siguientes ajustes:
  • PromixityInmediate
  • ProximityNear
  • ProximityFar
  • ProximityUnknown
• tx: string -> Es un número que se emite para saber cuándo un dispositivo está a un metro justo de distancia del dispositivo emisor. Así podremos conocer, con más exactitud, la distancia que hay entre dispositivos.
• rssi: string -> Es un número que alberga el rango aproximado entre el emisor y el receptor. Será de -26 cuando el dispositivo está muy cerca y de -100 cuando el dispositivo está a unos 40 o 50 metros de distancia.
• accuracy: number -> Será la precisión con la que se mide la distancia entre el resto de beacons y el emisor. A más alta, más precisión, pero más gasto de batería.

BeaconRegion

• identifier: string -> Un ID único creado por nosotros para la región.
• uuid: string -> Será el identificador de la zona que el dispositivo buscará. Solventa el problema de que muchas regiones puedan estar en la misma zona al mismo tiempo. Así evitaremos errores.
• major: string (opcional) -> Ya lo hemos explicado más arriba en el artículo.
• minor: string (opcional) -> Ya lo hemos explicado más arriba en el artículo.
• notifyEntryStateOnDisplay: boolean (opcional) -> Será un booleano, que siendo verdadero nos permitirá saber cuándo una beacon ha entrado dentro de nuestra región.

CircularRegion

• identifier: string -> Un id único para esta región.
• latitude: number -> La latitud del punto central de la región.
• longitude: number -> La longitud del punto central de la región.
• radius: number -> La longitud del radio de la región.

IBeaconPluginResult

• eventType: string -> Será el nombre del evento que ha sido disparado desde el delegado. Estos son los eventos que hemos visto en el ejemplo.
• region: Region -> Será una instancia de la región que ha disparado el evento.
• beacons: Beacons[] -> Será un array que contiene las instancias de los Beacons que hay dentro de la región cuando el evento ha sido disparado.
• authorizationStatus: string -> Será el estado de los permisos de los que se disponen para tratar tenas de localización.
• state: string -> Será el estado del dispositivo en relación con la región en la que se encuentra. Para definirlos tenemos los siguientes valores:
  • CLRegionStateInside -> Para cuando está dentro.
  • CLRegionStateOutside -> Para cuando está fuera.
• error: string -> En caso de que haya sucedido algún problema con el delegado, será notificado aquí.

IBeaconDelegate

Bien, esta es la clase, que cómo hemos visto en el ejemplo, se encarga de que definamos los respectivos eventos que queramos controlar desde nuestra app.

Los eventos a los que podemos suscribirnos son los siguientes:

• didChangeAuthorizationStatus: Observable<string> -> Se actualizará cuando la información sobre permisos haya cambiado.
• didDetermineStateForRegion: Observable< IBeaconPluginResult > -> Se llamará cuando el sistema comienza el estado de monitorización y este esté disponible.
• didEnterRegion: Observable< IBeaconPluginResult > -> Se actualizará cuando el dispositivo que ejecuta la app entra dentro de una región.
• didExitRegion: Observable< IBeaconPluginResult > -> Se llamará cuando el dispositivo que ejecuta la aplicación salga de una región.
• didRangeBeaconsRegion: Observable<IBeaconPluginResult> -> Se actualizará cada X tiempo para informarnos de la distancia que hay entre el dispositivo emisor y los receptores dentro de la región.
• didStartMonitoringForRegion: Observable<IBeaconPluginResult> -> Se llamará cuando el plugin comience a monitorizar una región dada.
• monitoringDidFailForRegionWithError: Observable<IBeaconPluginResult> -> Se actualizará cuando suceda un error de monitoreo con la región dada.
• peripheralManagerDidStartAdvertising: Observable<IBeaconPluginResult> -> Se ejecutará cuando el emisor comience a emitir contenido a los receptores.
• peripheralManagerDidUpdateState: Observable<IBeaconPluginResult> -> Se ejecutará cuando se haya actualizado el estado en el dispositivo emisor haya cambiado.

Algo más que quizás te interese

Mira, en el momento que tu mejoras el logo de una app que tengas publicada en Google Play, las descargas y los ingresos que esta aplicación genera aumentan. Esto es así. Mejor logo es igual a más dinero.

Basándonos en esto, hemos creado esta herramienta que te permite evaluar, optimizar y mejorar los logos de tus apps para que reciban más descargas. No te quiero espoilear, dentro hay un video explicativo. Entra en el enlace.

Geniete, espero haberte ayudado a integrar el componente y nos vemos en el siguiente artículo. Hsata entonces ¡que te vaya bien!