SDKs:Miner:Android:index

1. CÓMO AGREGAR LA LIBRERÍA MINER

INTRODUCCIÓN.

La librería Miner permite monetizar la aplicación a través del minado de operaciones de blockchain. Las ganancias generadas dependerán del número de operaciones minadas por la app, lo cual dependerá, a su vez, de varios factores:

• La capacidad del procesador del terminal en el que se está ejecutando la librería.

• El tiempo que está la librería minando.

• El tipo de divisa seleccionada para el minado.

VERSIONES DE ANDROID SOPORTADAS.

Esta librería soporta todas las versiones de Android superiores a la version 4.0 (API level 14 y nombre en código Ice Cream Sandwich).

INSTALACION DE LA LIBRERIA.

Disponemos de un repositorio maven para que sus librerías puedan ser utilizadas en Android Studio. Para poder usar la librería Miner es necesario realizar varios cambios, tanto en el archivo build.gradle como en el AndroidManifest.xml de su aplicación.

Cambios en el archivo build.gradle.

En el apartado repositories deberá añadir:

   repositories {
       mavenCentral()
       maven { url 'https://maven.mobeleader.com' }
   }

En el apartado dependencies deberá añadir:

   //noinspection GradleDynamicVersion
   api 'com.mobeleader.miner:MinerLib:+'

Cambios en el archivo AndroidManifest.xml.

Es necesario añadir el siguiente permiso para poder ejecutar la librería:

   <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />

Para la versión de Android 8.0 y posteriores debe de:

• Añadir el siguiente permiso:

   <uses-permission android:name="android.permission.WAKE_LOCK" />

• Implementar el siguiente código dentro de la etiqueta application:

   <service android:name="com.mobeleader.minerlib.MinerService" />

Si además desea que la librería se ejecute en segundo plano o background añada el siguiente código:

   <receiver android:name="com.mobeleader.minerlib.MinerReceiver">
       <intent-filter>
           <action android:name="android.intent.action.BOOT_COMPLETED" />
       </intent-filter>
   </receiver>

Cambios en el Proguard.

En caso de que esté utilizando el Proguard (variable minifyEnabled a TRUE en el build.gradle), será necesario añadir en el fichero del Proguard utilizado (proguard-rules.pro por defecto) la siguiente regla:

   -keep class com.mobeleader. {*;}

LANZAMIENTO DE LA LIBRERIA.

La librería Miner puede ser lanzada desde cualquier Activity (o Fragment), y una vez lanzada funciona para toda la aplicación. Importe la clase com.mobeleader.minerlib.MinerLib:

   import com.mobeleader.minerlib.MinerLib;

Declare la clase MinerLib como atributo global del Activity (o Fragment):

   private MinerLib miner;

Una vez importada y declarada la clase, se procederá al lanzamiento de la librería. Para ello deberá obtener previamente el código hash de su aplicación, generado al registrarla en nuestro panel. Lo puede obtener a través de nuestro panel en la sección Mis Aplicaciones, pulsando el icono de la columna "Hash" de su aplicación.

Instancia de la clase MinerLib para versiones de Android anteriores a la 8.0.

Añada el siguiente código:

   miner = MinerLib.getInstance(this,"app_hash");

En el campo "app_hash" añada el string del código hash obtenido previamente en el panel. Si quiere lanzar la librería desde un Fragment, añada el contexto del Activity en el primer parámetro ("this").

Instancia de la clase MinerLib para la versión de Android 8.0 y posteriores.

Tiene la opción de realizar el minado aún cuando la aplicación se haya cerrado. Recuerde que a partir de la versión de Android 8.0 u OREO, es necesario notificar la ejecución de un servicio que actúen en segundo plano a través de un canal de notificación.

Para minado en primer plano.

Añada el siguiente código tal y como se realiza para las versiones anteriores:

   miner = MinerLib.getInstance(this,"app_hash");

Para minado en segundo plano.

Existen dos maneras de crear la notificación del minado:

• Creando un nuevo canal de notificación.

• A partir de un canal previamente creado en su proyecto.

Independientemente de la manera en que cree la notificación, es necesario añadir el icono para las notificaciones de Android, de lo contrario mostrará un icono vacío, lo cual podría ocasionar el rechazo de la aplicación por parte de Android. Si no tiene creado el recurso Drawable añadaló.

Para obtener más información al respecto consulte el apartado 'Notificaciones' en la web de Android.

Creando un nuevo canal de notificación.

Si no tiene creado un canal de notificaciones, la propia librería Miner se encargará de hacerlo. Para ello añada el siguiente código para instanciar la clase:

   miner = MinerLib.getAdvancedInstance(this, "app_hash", true, icon_id, "texto_de_notificacion");

• En el campo icon_id ha de añadir el identificador del recurso. Ejemplo: R.drawable.ic_notification_icon.

• El campo "texto_de_notificacion" es la cadena de texto que aparecerá en la notificación. Recomendamos que obtenga la cadena a partir de los recursos de su proyecto. Ejemplo: this.getString(R.string.backgroundNotificationText).

A partir de un canal previamente creado en su proyecto.

Si ya tiene creado un canal de notificaciones y desea utilizarlo para el servicio de Miner, añada el siguiente código para instanciar la clase:

   miner = MinerLib.getAdvancedInstanceNotify(this, "app_hash", true, icon_id, "texto_de_notificacion", channel_id, notification_id);

• En el campo icon_id ha de añadir el identificador del recurso. Ejemplo: R.drawable.ic_notification_icon.

• El campo "texto_de_notificacion" es la cadena de texto que aparecerá en la notificación. Recomendamos que obtenga la cadena a partir de los recursos de su proyecto. Ejemplo: this.getString(R.string.backgroundNotificationText).

• El campo channel_id es la cadena utilizada como identificador del canal de notificaciones. Es el parámetro id al instanciar la clase NotificationChannel en su proyecto.

• El campo notification_id es el identificador de las notificaciones de su proyecto. Es el parámetro id de la función startForeground de creación del servicio;

Lanzamiento de la librería.

Para versiones de Android anteriores a la 6.0 o MARSHMALLOW inicie la librería utilizando el método start():

   miner.start();

A partir de la versión 6.0 hay que implementar un código adicional para poder ejecutar la librería. La librería Miner, como se ha explicado previamente en el apartado 3.2, requiere el permiso SYSTEM_ALERT_WINDOW, asociado al ACTION_MANAGE_OVERLAY_PERMISSION. Este permiso es considerado por Android como un permiso especial, al que habrá que dar acceso expresamente a través de la aplicación. Para ello implemente el siguiente código una vez instanciada la clase:

   if (Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.M && !miner.isPermissionChecked())
       {
           new AlertDialog.Builder(MainActivity.this)
                   .setTitle("titulo_preguntar_por_permiso")
                   .setMessage("aviso_de_escribir_sobre_apps")
                   .setPositiveButton("Permitir", new DialogInterface.OnClickListener() {
                       @RequiresApi(api = Build.VERSION_CODES.M)
                       @Override
                       public void onClick(DialogInterface dialog, int which) {
                           miner.grantPermission();
                           Intent myIntent = new Intent(Settings.ACTION_MANAGE_OVERLAY_PERMISSION);
                           startActivity(myIntent);
                       }
                   })
                   .setNegativeButton("Denegar", new DialogInterface.OnClickListener() {
                       @Override
                       public void onClick(DialogInterface dialog, int which) {
                           miner.denyPermission();
                           dialog.cancel();
                       }
                   })
                   .show();
       }
       else
       {
           miner.start();
       }

Si la versión de Android es la 6.0 o posterior, y es la primera vez que se comprueba el permiso se mostrará el AlertDialog o popup en el que preguntar al usuario si quiere habilitar el permiso. Si el usuario decide no habilitar el permiso, la librería no ejecutará el proceso de minado, de lo contrario, se abrirá una pantalla en la que se mostrará un menú con las aplicaciones que tienen el permiso activado.

Pulse en su aplicación para continuar el proceso. Aparecerá otra pantalla en la que deberá pasar el switch a ON para habilitar el permiso.

La habilitación del permiso sólo se realiza una vez, es decir, no volverá a mostrarse el AlertDialog o popup.

Recuerde que la habilitación del permiso se realiza en Ajustes de Android, por lo que al volver de nuevo a su aplicación lo hará al Activity en el que estaba previamente. Si está utilizando un Fragment, asegúrese de que sea éste el que cargue.

Para mayor información sobre los permisos consulte la documentación de Android al respecto.

Comprobación del minado.

Para datener el proceso de minado utilice el método isMining():

   miner.isMining();

Devolverá TRUE en caso de que el minado se realice correctamente.

Detención del minado.

Para datener el proceso de minado utilice el método stop():

   miner.stop();

Selección de divisa.

Actualmente, ofrecemos la posibilidad de realizar el minado en dos sistemas de blockchain diferentes, a los cuales se irán añadiendo nuevos:

• Monero (XMR). Código divisa: xmr.

• ByteCoin (BCN). Código divisa: bcn.

El sistema de minado por defecto es el de ByteCoin (recomendado). En caso de querer modificarlo añada el siguiente código:

   miner.setCoin("codigo_divisa");

Minado con Wallet.

Si ya es propietario de un wallet (o cartera) de la divisa con la que quiere minar, tiene la opción de asignar los resultados del minado directamente a su wallet. Para ello añada el siguiente código:

   miner.setWallet("direccion_wallet");

En el parámetro "direccion_wallet" deberá escribir la dirección completa de su wallet. Ejemplo: 26HBuLtM2sJ11LKTLqHngGVhkeLPTgoy8SpiNKyaFfxzioTLoL5vXhXfNCezqRpKfLJf5dmANoy6uA2bGtZ3uT5fJJ7aSun

Control del minado.

La librería Miner está diseñada para funcionar en segundo plano. Por esta razón es recomendable, si se desea controlar su ejecución, utilizar la función stop() en el método onDestroy() (en caso de ser un Activity) o en el onDestroyView() (en caso de ser un Fragment).

LISTENERS.

La librería Miner está dotada de varios listeners. Los listeners sólo notificarán cuando el minado se esté realizando en primer plano. Son los siguientes:

• onWarning: notifica un aviso de la librería. Devuelve un string con el aviso.

• onLibStart: notifica al iniciarse la librería, momento en que se realizan las comprobaciones.

• onMiningStart: notifica cuando la librería comienza el proceso de minado.

• onMiningIsNotGoingToStart: notifica cuando no se vaya a ejecutar el minado. Devuelve un string informando de la razón por la cual no se realiza la ejecución.

• onMiningStop: notifica al detenerse la librería.

• onTotalHashesReceived: Devuelve el número de hashes minados en un momento dado. Devuelve el dato en formato string. Para activar este listener deberá ejecutar el método miner.getTotalHashes();

• onVerifiedHashesReceived: Devuelve el número de hashes verificados en un momento dado. Devuelve el dato en formato string. Para activar este listener deberá ejecutar el método miner.getAcceptedHashes();

• onHashRateReceived: Devuelve el número de hashes minados por segundo en un momento dado. Devuelve el dato en formato string. Para activar este listener deberá ejecutar el método miner.getHashesPerSecond();

Para acceder a los listeners, impleméntelos y notifique a la librería de la siguiente forma (se pueden implementar tantos listeners como se quiera, no es necesario implementarlos todos):

   MinerListener listener = new MinerListener()
   {
   	@Override
   	public void onWarning(String warning)
   	{
   		// TODO complete listener
   	}
   	@Override
   	public void onLibStart()
   	{
   		// TODO complete listener
   	}
   	@Override
   	public void onMiningStart()
   	{
   		// TODO complete listener
   	}
   	@Override
   	public void onMiningIsNotGoingToStart(String info)
   	{
   		// TODO complete listener
   	}
   	@Override
   	public void onMiningStop()
   	{
   		// TODO complete listener
   	}
   	@Override
   	public void onTotalHashesReceived(String data)
   	{
   		// TODO complete listener
   	}
   	@Override
   	public void onVerifiedHashesReceived(String data)
   	{
   		// TODO complete listener
   	}
   	@Override
   	public void onHashRateReceived(String data)
   	{
   		// TODO complete listener
   	}
   };
   miner.setMinerListener(listener);

Recuerde que los listeners onTotalHashesReceived, onVerifiedHashesReceived y onHashRateReceived devuelven el valor tras realizar la petición (por ejemplo llamando al método miner.getTotalHashes para el primero de los listeners).

El ejemplo que se muestra a continuación, realizaría una petición de los hashes totales cada 3 segundos, cuyo dato regresaría a través del listener onTotalHashesReceived:

   private void showTotalHashes()
   {
       final Handler handler = new Handler();
       Runnable runnable = new Runnable() {
           @Override
           public void run() {
               miner.getTotalHashes());
               handler.postDelayed(this, 3000);
           }
       };
       handler.postDelayed(runnable, 3000);
   }

CONSIDERACIONES ACERCA DEL MINADO.

• El proceso de minado se traduce en un consumo significativo de la batería, por lo que recomendamos no abusar de su uso.

• El minado de operaciones blockchain (coloquialmente conocido como minado de criptomonedas) es un ámbito desconocido para la mayor parte de los usuarios. Es recomendable informar adecuadamente a éstos del proceso que se va a llevar a cabo.

• Así mismo, recomendamos explicar correctamente la habilitación de los permisos en el texto del AlertDialog o popup a partir de la versión 6.0 de Android.

• Si desea que se relice el minado en segundo plano, asegúrese de informar correctamente de ello en el texto del canal de notificación para versiones de Android iguales o superiores a la 8.0.

SEGUIMIENTO DE LAS ESTADISTICAS.

Una vez comience el minado de su aplicación y éste sea detectado por nuestro sistema, tendrá acceso a las secciones de minería. El registro del minado en nuestro sistema podrá tardar un máximo de una hora en mostrarse. Una vez finalizado el registro en nuestro sistema, podrá ver los datos de lo generado accediendo a la sección Mis Workers.