Integración Android

guía rápida de integración del SDK de Android.

Indice

• ¿Qué necesitas para la integración?
• Integración
  • Añadiendo las dependencias del SDK
    • Gradle 7.0 o posterior
  • Añadiendo los Servicios de indigitall
  • Añadiendo los Servicios de Firebase
  • Añadiendo los Servicios de HMS
  • Estableciendo el Icono para las notificaciones
  • Inicializar el SDK
• Validar la integración
• Recursos

¿Qué necesitas para la integración?

• Una cuenta con la que poder acceder al panel de Indigitall, si aún no la tienes creada puedes crear una cuenta aqui.
• Lo siguiente es tener un proyecto asociado a la aplicación web(navegadores web) y/o movil (android, ios), si aún no lo tienes creado y configurado puedes crear un proyecto en tu cuenta de indigitall.

Es importante ya que el proyecto contiene los datos de configuración de tu aplicación, es decir, el dominio donde esta alojada tu web, los certificados de safari o iOS o la clave de firebase que usa android. Todo depende de las plataformas (web o app) que use el proyecto.

• Necesitarás el App Key del proyecto, que es la clave que usa nuestro sistema para identificarlo, por lo que es única para cada proyecto. Lo puedes encontrar en la consola de administración dentro de la sección Configuración en la pestaña Proyectos. Puedes verlo en la siguiente imagen, y para copiarlo están sencillo cómo hacer click en el icono que hay junto a la clave (App Key)

• Un Server Key de Firebase
• Un Server Key de HMS Push Kit (opcional)
• Android Studio
  • Un dispositivo Android o emulador con los servicios de Google Play instalados para ejecutar la app

Integración

Este artículo muestra el desarrollo mínimo que hay que hacer para comenzar a registrar dispositivos y poder realizar las primeras campañas push.

La SDK de Indigitall es compatible con los servicios de mensajería de Google, mediante la plataforma Firebase y con los servicios de HMS o Huawei Mobile Services de Huawei.

Puedes verlo en ente vídeo tutorial o leer las instrucciones más abajo:

Añadiendo las dependencias del SDK

Lo primero que hay que hacer es abrir el fichero app/build.gradle. En la captura de pantalla se puede comprobar dónde encontrar este fichero app/build.gradle.

Atención: es el fichero build.gradle que se encuentra en la carpeta app, NO el de la raíz del proyecto.

La librería está disponible a través del repositorio Maven Central. Maven es una de las herramientas de gestión de librerias más usadas en Android. Para integrar el SDK de indigitall es necesario añadir las siguientes dependencias:

• La libreria de AndroidX

• Los servicios de localización de Google Play Services

• La libreria de mensajes de Firebase

• La libreria de mensajes de HMS

• El SDK de indigitall

• La compatibilidad del SDK con Android es a partir de Android 5.0, o lo que es lo mismo el campo minSdkVersion del gradle de la aplicación sea 21, ya que es a partir de esta versión que es compatible con los certificados TLS.

// build.gradle (project)

buildscript {
    repositories {
        ...
        mavenCentral()
        // maven {
        //     url 'https://developer.huawei.com/repo/'
        // }
    }
    dependencies {
        ...
        classpath 'com.google.gms:google-services:4.3.10'
        // classpath 'com.huawei.agconnect:agcp:1.6.4.300'
    }
}
allprojects {
    ...
    mavenCentral()
    // maven{
    //     url 'https://developer.huawei.com/repo/'
    // }

}

// build.gradle (app)

plugins {
    id 'com.android.application'
    ...
    id 'com.google.gms.google-services'
}
// if you use apply plugin
// apply plugin: 'com.google.gms.google-services'

android {
    compileSdkVersion 31
    defaultConfig {
        minSdkVersion 19
        targetSdkVersion 31
    }
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'androidx.appcompat:appcompat:1.1.0'
    implementation 'com.google.android.gms:play-services-location:18.0.0'
    implementation 'com.google.firebase:firebase-messaging:22.0.0'
    // implementation 'com.huawei.hms:push:6.3.0.302'
    implementation 'com.indigitall:android:4.18.+'
}

Si estás con una versión de Kotlin menor a 1.5.21, deberás añadir la siguiente implementación de coroutines en las dependencias del gradle:

dependencies {
    implementation 'androidx.appcompat:appcompat:1.1.0'
    ...

    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.5.1'
}

Gradle 7.0 o posterior

Para saber qué versión de gradle tienes configurado en tu proyecto ve a File->Project Structure->Proyect en Gradle Version.
La compatibilidad con el Gradle JDK cambia con esta versión, en este caso debe usarse la versión 11. Para ello ve al menú Android Studio->Build, Execution, Deplyment->Build Tools->Gradle y seleccióna en Gradle JDK la versión 11.
La configuración que había en allprojects->repositories se ha movido al archivo settings.gradle. Por lo que hay que modificar el gradle del proyecto y el settings.gradle quedando de la siguiente forma:

// build.gradle (project)
buildscript {
    dependencies {
        classpath 'com.google.gms:google-services:4.3.10'
        // classpath 'com.huawei.agconnect:agcp:1.6.4.300'
        classpath 'com.android.tools.build:gradle:4.0.1'
    }
}
//no repositories field

//settings.gradle
pluginManagement {

    repositories {
        gradlePluginPortal()
        google() //if needed
        mavenCentral()
        // maven { url 'https://developer.huawei.com/repo/' }
    }
}
dependencyResolutionManagement {
    ...
    repositories {
        google() //if needed
        mavenCentral()
        // maven { url 'https://developer.huawei.com/repo/' }
    }
}

Añadiendo los servicios de Indigitall

Estos servicios son necesarios para que nuestro SDK pueda sincronizar los datos del dispositivo con los servidores de indigitall.

<manifest ...>
    <!-- ... -->

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

    <!-- To obtain the location of the device -->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION"/>

    <application ...>
        <!-- ... -->

        <!-- MANDATORY -->

        <!-- So that when the user presses a push, the metric is saved -->
        <service android:name="com.indigitall.android.services.StatisticService"/>

        <!-- Daily sync of device data -->
        <service android:name="com.indigitall.android.services.NightService"/>

        <!-- To start services when you restart the device -->
        <receiver android:name="com.indigitall.android.receivers.BootReceiver">
            <intent-filter>
                <action android:name="android.intent.action.BOOT_COMPLETED" />
            </intent-filter>
        </receiver>

        <!-- OPTIONAL -->

        <!-- So that when the user clicks an InApp message, the metric is saved.
        It is only necessary if you use the InApp message functionality -->
        <service android:name="com.indigitall.android.inapp.services.StatisticInAppService" />

        <!-- To obtain the location of the device.
        It is only necessary if you are going to ask for location permission
        to segment pushes by device location -->
        <receiver android:name="com.indigitall.android.receivers.LocationReceiver">
            <intent-filter>
                <action android:name="LocationReceiver.Action.LOCATION_UPDATE" />
            </intent-filter>
        </receiver>

    </application>
</manifest>

Añadiendo los servicios de Firebase

Nuestro SDK necesita integrarse con tu proyecto de FCM (Firebase Cloud Messaging).

FCM realiza la conexión con el dispositivo para poder enviarle notificaciones push. Esta conexión se establece con el Push Token, un token efímero, único y generado por Google para cada dispositivo.

<manifest ...>
    <!-- ... -->
    <application ...>
        <!-- ... -->

        <service android:name="com.indigitall.android.services.FirebaseMessagingService">
        <intent-filter>
            <action android:name="com.google.firebase.MESSAGING_EVENT" />
        </intent-filter>
        </service>

        <!-- DEPRECATED - NOT ADD
        <service android:name="com.indigitall.android.services.FirebaseInstanceIdService">
        <intent-filter>
            <action android:name="com.google.firebase.INSTANCE_ID_EVENT" />
        </intent-filter>
        </service>
        -->
    </application>
</manifest>

Añadiendo los servicios de HMS

Nuestro SDK necesita integrarse con tu proyecto de HMS (Huawei Mobile Services) para poder impactar en los últimos terminales de Huawei.

HMS realiza la conexión con el dispositivo para poder enviarle notificaciones push. Esta conexión se establece con el Push Token, un token efímero, único y generado por HMS para cada dispositivo.

Para poder impactar a los dispositivos Huawei con Harmony, deberás realizar los siguiente pasos:

1. Añade el servicio HMSMessagingService en el manifest del proyecto.

<manifest ...>
    <!-- ... -->
    <application ...>
        <!-- ... -->

        <service
            android:name="com.indigitall.android.services.HMSMessagingService"
            android:exported="false">
            <intent-filter>
                <action android:name="com.huawei.push.action.MESSAGING_EVENT" />
            </intent-filter>
        </service>
    </application>

</manifest>

2. Añadir el plugin de huawei en el gradle de la aplicación, recuerda que minSdkVersion que permite Huawei es la 19:

// build.gradle (app)

plugins {
    id 'com.huawei.agconnect'
}
// if you use apply plugin
// apply plugin: 'com.huawei.agconnect'

android {
    ...

     defaultConfig {
        minSdkVersion 19
     }

     ...
    dependencies {
        ...
        implementation 'com.huawei.hms:push:6.3.0.302'
    }
}

Estableciendo el icono de las notificaciones

Este icono se mostrará en la barra superior del sistema Android y en la cabecera de las pushes enviadas a través de tu app.

Debe ser un icono monocromo, es decir, que la imagen debe contener solo un color y alfa.

Te ponemos un ejemplo con nuestro logo en monocromo:

A continuación te mostramos cómo debería estar tu código en el AndroidManifest.xml (El icono tiene que ser un png)

<manifest ...>
    <!-- ... -->
    <application ...>
        <!-- ... -->

        <!-- Resource for monochrome icon -->
        <meta-data android:name="indigitall.icon" android:resource="@drawable/YOUR_MONOCHROME_ICON"/>

        <!-- Resource for icon color -->
        <meta-data android:name="indigitall.color" android:resource="@color/colorPrimary"/>
    </application>
</manifest>

* Para mayor aclaración sobre la creación de iconos, os dejamos este enlace a la documentación de Android que puede servir de ayuda: Product icons

Inicializar el SDK

Para inicializar el SDK es necesario llamar al método init. Esta llamada ha de producirse dentro del objeto Application.

La clase Application del SDK de Android es la clase base contenedora, y es lo primero que se ejecuta al abrir la aplicación. Por lo tanto, es necesario que nuestra aplicación tenga una clase personalizada que extienda de la clase Application.

Dentro de esta clase, en el método onCreate, debemos añadir las siguientes líneas de código:

Indigitall.init(this, "<your_indigitall_app_key>", "<your_firebase_sender_id")

• your_indigitall_app_key es una cadena alfanumérica que identifica tu proyecto de indigitall. Se obtiene desde la consola de indigitall
• your_firebase_sender_id es una cadena numérica que identifica tu proyecto de Firebase. Se obtiene desde la consola de Firebase

No olvides añadir el nombre de tu clase Application en el manifest AndroidManifest.xml:

<application android:name=".application.App">

Validar la integración

Para comprobar que la integración se ha realizado correctamente realiza lo siguiente:

1. Desde Android Studio, ves a la pestaña Logcat y busca la llamada PUT /device conteniendo los parámetros appKey, deviceId y pushToken y que devuelva HTTP 200.

2. Envia una notificación desde la consola de indigitall. Es posible que en la consola el contador de dispositivos aparezca a 0. No te preocupes, puede tardar unos minutos en actualizarse, pero no hace falta que esperes, la push debería llegar igualmente.

Recursos

• Aprende a utilizar la consola para enviar tus campañas push
• Descubre la potencia del SDK de indigitall con nuestra guía avanzada
• Comienza a automatizar tus comunicaciones gracias a nuestra API de administración