Integración Android

  ¿Por qué utilizar el SDK de EMMA en tu APP?

Descarga e Integración básica

Integración Acquisition

Integración Behavior

Integración Notificaciones Push

Integración Messaging

Deshabilitar seguimiento publicitario

Depurando el código

 

¿Por qué utilizar el SDK de EMMA en tu App?

El SDK de EMMA proporciona funcionalidad única para el seguimiento completo de los usuarios de tu App. Hemos desarrollado un SDK muy resistente, seguro y ligero con más de 2.000 Millones de instalaciones hasta la fecha. Y por supuesto, fácil de integrar.

EMMA_1.png

EMMA puede medir origen de instalaciones (incluyendo Facebook, Twitter y Google), sesiones, eventos que realizan los usuarios, localización, ... con un potente módulo de segmentación para poder evaluar el ROI y la retención de tus usuarios y fidelizarlos gracias a nuestras herramientas de comunicación Push e In-App Messaging.

EMMA Android SDK es compatible con todos los dispositivos a partir de la versión 4.0.3 (Ice Cream Sandwich MR1) de Android.

 

Descarga e integración básica

Descarga EMMA Android SDK

Ver el Changelog

Puedes descargar e instalar EMMA a través de Gradle.

Utilizar Gradle para la descarga

Si estás utilizando Gradle como como gestor de dependencias puedes integrar el SDK de forma fácil:

  1.  Añade al archivo /app/build.gradle el repositorio en el cual se encuentra EMMA.
    repositories {
      maven { url 'https://repo.emma.io/emma' }
    } 

    Importante

    Para usar https es importante tener instalada una versión de Java 7 >= 7u111 y/o Java 8 >= 8u101. 

    En caso de no disponer de una versión compatible, puedes descargar una versión de java reciente del siguiente enlace:
    https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html

    O bien usar la siguiente url: http://repo.emma.io/emma

  2. Añade la dependencia en el mismo archivo .gradle.
    dependencies {
       implementation 'io.emma:eMMaSDK:4.3.+'		    
    }
  3. Si tu app ya tiene el paquete com.google.android.gms:play-services-gcm y entra en conflicto con la dependencia de tu app, puedes utilizar la dependencia de tu app y excluir la de EMMA.
    implementation ('io.emma:eMMaSDK:4.3.+') {
       exclude group: 'com.google.android.gms', module:'play-services-gcm'
    }

    Info

    Este es solo un procedimiento que puede cambiar con una versión nueva de Gradle. Antes de lanzar tu versión a producción es importante refrescar la descarga de dependencias y comprobar que la dependencia de gcm se incluye en la apk.

  4. Por último, compilar el proyecto con gradle. 

 

Permisos de la aplicación y EMMA Session Key

Actualmente el SDK contiene por defecto los siguientes permisos obligatorios. Estos permisos no se tienen que añadir en el AndroidManifest.xml de la aplicación:

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

Si quieres habilitar la localización tienes que añadir los siguientes permisos al AndroidManifest.xml de tu aplicación:

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

Añade tu EMMA SESSION_KEY al AndroidManifest.xml, para ello, dentro del elemento application añade

<meta-data android:name="io.emma.SESSION_KEY" android:value="@string/emma_session_key" />

Y en el archivo res/strings.xml añade dentro de resources:

<string name="emma_session_key">example0ikl98</string>

Si no sabes cómo obtener tu EMMA Session Key sigue estas instrucciones

 

Inicialización del SDK & Evento Install (Requerimiento Mínimo)

En tu clase Application, importa EMMA:

import io.emma.android.EMMA;

En tu método de Application onCreate() añade la siguiente llamada:

EMMA.getInstance().startSession(this);

Opcional

En algunos, es necesario cambiar la url de API EMMA  (p.e proxies), para ello hay que añadir lo siguiente justo antes del método startSession(...):

EMMA.getInstance().setWebServiceUrl("https://www.your_proxy_url.com/");

 

Medición de la instalación

Google Play Install Referrer API

A partir de la versión 4.3 del SDK se introduce internamente la API de Google Play para realizar la medición de la instalación. Todos los dispositivos que tengan una versión de la app de Google Play igual o superior a la 8.3.73 automáticamente se medirán a través de la API.

La ventaja de usar esta API es que permite identificar los clicks fraudulentos (click injection).

Importante

Aunque la versión del SDK integrado sea superior a la 4.3.0 es necesario integrar el Install Referral Receiver para dar soporte a aquellos dispositivos que no tengan la versión de la app de Google Play que integra la API

Install Referral Receiver

Cuando se dirija al usuario a Google Play, se puede utilizar el Install Referrer Receiver para conseguir la máxima exactitud en la medición. 

Una vez instalada la app a través Google Play Store se lanzará la acción: com.android.vending. INSTALL_REFERRER. Esto ocurre antes de que se abra la aplicación por primera vez. Para capturar esta información:

Añade el EMMAReferralReceiver broadcast receiver a su AndroidManifest.xml:

<receiver android:name="io.emma.android.referral.EMMAReferralReceiver" android:exported="false">
<intent-filter>
<action android:name="com.android.vending.INSTALL_REFERRER"/>
</intent-filter>
</receiver>

A partir de la version 2.5 del SDK se incluye el EMMAInstallsBroadcastReceiver permite tener más de un receiver con la acción com.android.vending.INSTALL_REFERRER. El receiver se tiene que declarar como el primer receiver, con esta acción, del AndroidManifest.xml. 

<receiver android:name="io.emma.android.referral.EMMAInstallsBroadcastReceiver" android:exported="false">
    <intent-filter>
       <action android:name="com.android.vending.INSTALL_REFERRER" />
    </intent-filter>
</receiver>

Nota: si se esta utilizando otro receiver de otro proveedor para gestionar la múltiple acción (p.e el MultipleInstallBroadcastReceiver de Appsflyer) no hará falta utilizar el receiver anterior.

 

Publica tu App en Google Play

Ahora ya está listo para empezar a trackear con EMMA.

Continúa con este artículo para la integración avanzada si quieres ampliar la medición e implementación de herramientas de fidelización de EMMA en su app.

*Excepto Facebook App Installs y Twitter App Promotion

 

Actualización a la versión 4.4

Las versiones previas que se actualicen a la 4.4 deberán es recomendable que realicen los siguientes cambios.

Cambios en Eventos

Los siguientes métodos quedan deprecados: 

public void trackEvent(String token)    
public void trackEvent(String token, Map<String, Object> attributes)

Ambos se remplazan por el siguiente método:

public void trackEvent(@NonNull EMMAEventRequest eventRequest)

Ejemplo de uso:

EMMAEventRequest eventRequest = new EMMAEventRequest("<token>");
//Optional: custom attributes
eventRequest.setAttributes(attributes);
//Optional: request status delegate
eventRequest.setRequestDelegate(requestDelegate);
//Optional: cumtom id for request delegate
eventRequest.setCustomId(customId);

EMMA.getInstance().trackEvent(eventRequest);

Cambios en InApp

Los siguientes métodos quedan deprecados:

public void getInAppMessage(EMMACampaign.Type campaignType)
public void getInAppMessage(EMMACampaign.Type campaignType, EMMAInAppRequest request)
public void getInAppMessage(EMMACampaign.Type campaignType, EMMAInAppRequest request, EMMAInAppMessageInterface listener)

Ambos se remplazan por los siguientes métodos:

public void getInAppMessage(@NonNull EMMAInAppRequest params) 
public void getInAppMessage(@NonNull EMMAInAppRequest requestParams, EMMAInAppMessageInterface listener)

Ejemplo de uso:

EMMAInAppRequest * inAppRequest = EMMAInAppRequest(EMMACampaign.Type.STARTVIEW);
//Optional: custom attributes
inAppRequest.setAttributes(attributes);
//Optional: request status delegate
inAppRequest.setRequestDelegate(requestDelegate);
//Optional: cumtom id for request delegate
inAppRequest.setCustomId(customId);

EMMA.getInstance().getInAppMessage(inAppRequest);

Info

Si el mensaje es para solicitar un Native Ad es obligatorio usar EMMANativeAdRequest (subclase de EMMAInAppRequest) para añadir el templateId y su callback específico.

Push Options (añadido en versión 4.3)

Los siguientes métodos quedan deprecados:

public void startPushSystem(Class activityClass, int icon)
public void startPushSystem(Class activityClass, int icon, int notificationColor)
public void startPushSystem(Class activityClass, int icon, boolean customNotification)
public void startPushSystem(Class activityClass, int icon, int notificationColor, boolean customNotification)

Ambos se remplazan por el siguiente método:

public void startPushSystem(EMMAPushOptions pushOptions)

Ejemplo de uso:

EMMAPushOptions pushOpt = new EMMAPushOptions.Builder(PushActivity.class, R.drawable.notification_icon)
   .setNotificationColor(ContextCompat.getColor(this, R.color.colorPrimary)) //Optional
   .setNotificationChannelId("custom id") //Optional
   .setNotificationChannelName("custom channel") //Optional

 

Integración Acquisition

En la sección de Acquisition podrás tener los datos de todas las campañas gestionadas con EMMA. A continuación se detalla la documentación específica para que puedas gestionar las campañas que desarrolles con Twitter y, además, la documentación detallada de cómo integrar la funcionalidad de Powlink.

 

Medición de Twitter App Promotion

EMMA está 100% integrada para el tracking de Twitter vía Appsflyer. Con esta integración serás capaz de medir el origen de los anuncios en EMMA sin necesidad de integrar el SDK propio de Twitter.

Para integrar el SDK de Appsflyer hay que añadir lo siguiente al /app/build.gradle:

repositories {
    mavenCentral()
}
dependencies {
implementation 'com.appsflyer:af-android-sdk:4+@aar'
}
String devKey = "<EMMA Social Key>"
AppsFlyerLib.getInstance().init(dev_key, conversionDataListener, getApplicationContext()); AppsFlyerLib.getInstance().startTracking(this);

El EMMA Social Key que tienes que introducir es el ID que se necesita para realizar un seguimiento de las campañas de Twitter App Promotion.

Para solicitar el EMMA Social Key debes seguir estos pasos:

1.  Haz login en la página web de EMMA y dirígete a My Account > Configuration > Edit app.

Captura_de_pantalla_2018-10-08_a_las_10.44.51.png

 

 

2.  Dirígete a la zona de Media Source Settings y añade la siguiente información sobre tu aplicación:

Captura_de_pantalla_2018-10-08_a_las_10.45.17_copia.png

Para sacar el App Store ID puedes copiar el ID a través del enlace generado en AppStore, como en el siguiente ejemplo:

EMMA_4.png

Para sacar el Google Play ID puedes copiar el ID a través del enlace generado en GooglePlay, como en el siguiente ejemplo:

EMMA_5.png

3.  Selecciona la opción Guardar (Submit) para guardar los cambios.

4.  Envíanos un email a support@emma.io para solicitarnos el EMMA Social Key.

5.  Si todo se ha realizado correctamente, encontrarás las campañas Twitter en la sección Acquisition > AppTracker. Una vez la campaña esté activa, los datos de rendimiento entrarán automáticamente EMMA.

EMMA_6.png

 

 

Integración del Powlink

Para soportar Powlink en Android, primero, es necesario configurar en el Dashboard de EMMA el subdominio en powlink.io que usará tu aplicación, y cubrir los datos del Google Play ID y el Fingerprint del certificado con el que debes firmar tu aplicación en formato SHA256. Esto se configura en el apartado de My Account, en la sección de Media Source Settings de tu aplicación.

4.png

Conociendo el subdominio que corresponde a tus Powlinks, debes añadir una activity nueva al AndroidManifest.xml de tu aplicación tal y como indicamos a continuación. Esta actividad es la que se tiene que utilizar también para el deeplink, como explicamos más abajo.

 <activity
       android:name="io.emma.android.activities.EMMADeepLinkActivity"
       android:noHistory="true"
       android:theme="@android:style/Theme.NoDisplay">
<intent-filter> <action android:name="android.intent.action.VIEW"/>
<category android:name="android.intent.category.DEFAULT"/> <category android:name="android.intent.category.BROWSABLE"/>
<data android:scheme="{YOUR_DEEPLINK_SCHEME}"/> </intent-filter>
<intent-filter android:autoVerify="true"> <action android:name="android.intent.action.VIEW"/> <category android:name="android.intent.category.DEFAULT"/> <category android:name="android.intent.category.BROWSABLE"/> <data android:host="subdomain.powlink.io" android:scheme="https"/> <data android:host="shortsubdomain.pwlnk.io" android:scheme="https"/> </intent-filter> </activity>

Como explicamos más abajo en el apartado de deeplink, también hay que añadir el metadato con la activity a ajecutar para tratar la url del powlink.

<meta-data
    android:name="io.emma.DEEPLINK_OPEN_ACTIVITY"
    android:value="com.your.package.CustomDeeplinkActivity"/>

En el apartado de Deeplink se muestra como puedes manejar los Powlinks o Deeplinks recibidos para procesarlos y mostrar la parte correspondiente de tu aplicación.

Nota: Si estas usando un tracker con un dominio que no es el de EMMA (.powlink.io o .pwlnk.io), es necesario añadir el dominio al iniciar la libreria:

 EMMA.Configuration configuration = new EMMA.Configuration.Builder(this)
            ...
.setPowlinkDomains("<custom_domain>") .setShortPowlinkDomains("<custom_domain>") .build() EMMA.getInstance().startSession(configuration);

o

EMMA.getInstance().startSession(this);
EMMA.getInstance().setPowlinkDomains("<custom_domain>");
EMMA.getInstance().setShortPowlinkDomains("<custom_domain>");

Integración Behavior

Con EMMA puedes realizar una integración completa del SDK que te permita conocer la localización de tus usuarios, cómo se registran en tu App, cuántas transacciones realizan y hasta sus características propias. Es decir, toda la información de tus usuarios que obtendrás en la sección de Behavior

En los siguientes artículos se especifica la integración de la medición de cada uno de estos aspectos:

 

Medición Eventos

La plataforma de EMMA hace la diferenciación entre dos tipos de eventos. Los que la plataforma incluye por defecto y los eventos Custom que quieras integrar según la estructura de tu aplicación.

Eventos por defecto

En los eventos por defecto EMMA permite medir Leads (o registros), usuarios registrados fuera de la app, registros antiguos y cualquier etiqueta que desees vincular a un usuario de cara a poder crear segmentos personalizados y los Login (usuarios que han iniciado sesión a través de un correo ya existente o bien a través de alguna plataforma social).

Sigue los siguientes pasos para su integración:

Sign Up/Registros/Leads

EMMA.getInstance().registerUser(userId, mail);

RegisterUser establece un registro completo del dispositivo en la BBDD de EMMA para un userId (String) y un e-mail (String).

Login

EMMA.getInstance().loginUser(userId, mail);

LoginUser registra el usuario en la base de datos de EMMA mediante un userId (String) y un correo electrónico (String). Cuando se encuentre registrado puede utilizar asimismo EMMA.getInstance().loginDefault() para registrar otro 'Sign In' para el usuario con los mismos datos.

Eventos custom

Con EMMA puedes medir cada acción del usuario como un evento personalizable.

EMMAEventRequest eventRequest = new EMMAEventRequest("<token>");
//Optional: custom attributes
eventRequest.setAttributes(attributes);
//Optional: request status delegate
eventRequest.setRequestDelegate(requestDelegate);
//Optional: cumtom id for request delegate
eventRequest.setCustomId(customId);

EMMA.getInstance().trackEvent(eventRequest);

Usar trackEvent para contar el número de veces que ciertos eventos ocurren durante una sesión de su aplicación. Esto puede ser útil para medir la frecuencia con que realizan acciones de interés o para crear segmentos en la plataforma sobre los que trabajar. 

Actualmente el número máximo de eventos a trackear es de treinta.

Para obtener lo necesarios tokens de eventos creandolos en la plataforma de EMMA. Si se envía un token inexistente en EMMA, este devolverá un error.

Para la request de eventos se puede añadir un listener para mostrar el estado de la petición y si esta devuelve datos (p.e una rule) o no. Para añadir el listener:

EMMAEventRequest eventRequest = new EMMAEventRequest("<token>");
//Optional eventRequest.setCustomId("my custom id")
eventRequest.setRequestListener(new EMMARequestListener() {
      @Override
      public void onStarted(String id) {
      }

      @Override
      public void onSuccess(String id, boolean containsData) {     
      }

      @Override
      public void onFailed(String id) {
      }
 });

 EMMA.getInstance().trackEvent(eventRequest);

Medición transacciones

EMMA permite medir cualquier transacción o compra que se realice en tu app. 

Start Order 

EMMA.getInstance().startOrder(String orderId, String customerId, float totalPrice, String coupon, Map<String,String> extras, String currencyCode);

Este método habilita una orden para añadir productos. Es posible pasar los siguientes parámetros:

  • orderID

: Encadena el orderID de la transacción

customerId

: Encadena el ID de cliente. Si no lo envías EMMA usará el ID del login (si existe)

totalPrice

: Etiqueta con el precio total

coupon

: Enlaza con un cupón si es necesario

extras

: Mapa con hasta veinte parámetros extra, como la divisa, categoría de productos, etc. 

currencyCode

: Encadena un código de moneda válido (EUR,USD,GBP..) Si el código de moneda no es válido se utilizará EUR

Si no se necesitan todos los parámetros también se pueden usar métodos abreviados. Estos se pueden encontrar al final del documento o en eMMa.jar.

Añadir productos a una orden

EMMA.getInstance().addProduct(String productId, String name, float qty, float price, Map<String,String> extras);

Añadir productos a una orden iniciada actual. El startOrder siempre debería ser llamado antes. Se pueden pasar los siguientes parámetros.

productId

: Encadena el identificador del producto

name

: Encadena el nombre del producto

qty

: Etiqueta con su Product QTY.

price

: Etiqueta con el precio del producto.

extras

: Mapa con hasta veinte parámetros o categorías extra 

Medición de la transacción

EMMA.getInstance().trackOrder();

Mide la orden actual. Debería ser llamada después del startOrder y después de que se hayan añadido todos los productos.

La secuencia de la medición de la transacción en EMMA es siempre:

EMMA.getInstance().startOrder>EMMA.getInstance().addProduct(*distinct products)>EMMA.getInstance().trackOrder()

Cancelación de la transacción 

EMMA.getInstance().cancelOrder(String orderId);

Cancelar la orden referenciada por un orderID. Si su aplicación permite cancelar pedidos, este método actualiza la información de las transacciones registradas en función de estas posibles cancelaciones.

 

Medición Tags

Extra Info o Tags

EMMA.getInstance().trackExtraUserInfo(extras);

Este método actualiza o añade parámetro extra para usuarios ya logueados permitiendo así una mejor base de datos segmentados. Puede ser utilizado en cualquier lugar.

Si quieres usar la EMMA RULE On his Birthday envía la fecha de cumpleaños con el método para el TAG en el siguiente formato: 

Nombre: BIRTHDAY

Valor: YYYY-MM-DD

Info

Recuerda revisar los logs del SDK para consultar el listado de TAGS que no pueden ser usados por estar reservados para el sistema de EMMA.

 

Medición localización 

Si tu aplicación cuenta con permisos de localización, EMMA podrá medir desde dónde se está utilizando su app.

Para inhabilitar la posibilidad de obtener un reporting detallado de dichas localizaciones incluso cuando su app permita esta opción, llama a EMMA.disableTrackingLocation() antes de hacer lo propio a EMMA.startSession(this).

 

Información del usuario [Get User Info]

Get User ID

EMMA.getInstance().getUserID();

Este método devolverá el EMMA ID del usuario. Este ID es único para cada usuario y puede ser empleado para filtrar cuando se utilicen acciones de Push, StartView y DynamicTabs.

Tu actividad debe implementar la interfaz eMMaUserInfoInterface y el método OnGetUserID(int id) al que se llamará con el identificador del usuario esté disponible.

Get User Info

EMMA.getInstance().getUserInfo();

Info

Los datos que devuelve la llamada se obtienen de la propia información que recopila el SDK. En un primer arranque puede tardar unos segundos en recopilar la información, si la llamada se realiza justo después después del startSession podría devolver null.

El método devuelve la información del usuario en EMMA en formato JSON.

Su actividad debe implementar la interfaz EMMAUserInfoInterface y el método OnGetUserInfo(JSONObject json) al que se llamará cuando la información del usuario esté disponible.

El JSON incluirá los siguientes parámetros:

id  El mismo ID único que en el método (getUserID)
udid  ID único por instalación de la app (IDFA/AAID habitualmente)
emma_build  Identifica la versión del SDK de EMMA que se está usando
email  Email del usuario en caso de que el registro o el login estén integrados
customerid  ID asignado al usuario tras el registro o login
device  Modelo del dispositivo del usuario
app_version  Versión de la app
os_version  Versión del sistema operativo
os_build  Build del SO
token  Identificador del push (token)
latitude  Latitud del usuario en el caso de que se permita y mida la geolocalización
longitude  Longitud del usuario en el caso de que se permita y mida la geolocalización
emma_carrier  Operador de telefonía
emma_connection  Tipo de conexión (wifi o 3g)
emma_city  Ciudad del usuario en el caso de que se permita y mida la geolocalización
emma_country  País del usuario en el caso de que se permita y mida la geolocalización
emma_state  País del usuario en el caso de que se permita y mida la geolocalización
emma_accept_language   Lenguaje establecido en la app
emma_timezone_name  TimeZone del dispositivo
emma_device_id  Android device ID
{tagX....tagY}  Tags de usuario que se traquean en la llama trackExtraUserInfo

 

Para usar este método es necesario tener contratada la feature Raw Export en tu sección de My Account > My Plan. 

 

Información de la atribución de instalación 

A través del método explicado más abajo, podremos obtener los datos de la atribución de la instalación de cada usuario, pudiendo obtener la siguiente información:

  • Status {String}: Nos devuelve el estado de la atribución. Éste puede tener varios tipos:
    • pending: La instalación todavía está pendiente de atribución esto se debe a la ventana de atribución, máximo 2 días).
    • campaign: Significa que la instalación ha sido atribuida a una campaña, source y provider concreto. 
    • organic: La instalación ha sido orgánica. Si la atribución es orgánica, significa que la instalación no estará vinculada a una campaña y por lo tanto la campaña será nula. 
  • Id de la campaña {Number}
  • Nombre de la campaña {String}
  • Id de la fuente {Number}
  • Nombre de la fuente {String}
  • Id del proveedor {Number}
  • Nombre del proveedor {String}

Para poder obtener está información sobre la atribución de la instalación, es necesario que se añada el siguiente método: 

EMMA.getInstance().getInstallAttributionInfo(attribution -> {
    final EMMAInstallAttribution attr = attribution;
    if (attr != null) {
        // process attribution
    }
 });  

 

Integración Notificaciones Push

NOTA: Para diferenciar una notificación de nuestro sistema de push respecto otros sistemas, el payload enviado por EMMA contiene un flag denominado "eMMa".

EMMA ofrece un completo sistema de envío y reporting de Notificaciones Push fácil de integrar usando el Google Cloud Messaging for Android (GCM)

Obtén en primer lugar tu propio Project Number y API key para el GCM como se especifica en este artículo, y establece estos parámetros para la app en su cuenta de EMMA.

IMPORTANTE: usa el Server API Key para GCM, no el Browser o el Android-iOS API Key.

La versión 4.2 incluye cambios en esta sección.

En tu aplicación, necesitas configurar el AndroidManifest.xml.

Permisos requeridos: 

<uses-permission android:name="{your_own_application_id}.C2D_MESSAGE"/>
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE">
<permission
    android:name="{your_own_application_id}.permission.C2D_MESSAGE"
    android:protectionLevel="signature"/> 

También se debe indicar el receiver que gestionará la notificación:

<receiver
    android:name="io.emma.android.push.EMMAGCMBroadcastReceiver"   
android:permission="com.google.android.c2dm.permission.SEND">
<intent-filter>
<action android:name="com.google.android.c2dm.intent.RECEIVE"/>
<category android:name="{your_own_application_id}"/>
</intent-filter>
</receiver>

El EMMAPushBroadcastReceiver se ha deprecado. Por lo tanto se puede eliminar.

Para que el token pueda refrescarse en caso de caducidad, añade el siguiente servicio:

<service
android:name="io.emma.android.push.EMMAInstanceIDListenerService"
android:exported="false">
<intent-filter>
<action android:name="com.google.android.gms.iid.InstanceID"/>
</intent-filter>
</service>

Inicie el sistema de push debajo del inicio de sesión en el Application:

@Override
public void onCreate() {
super.onCreate();
EMMA.getInstance().startSession(this);
EMMA.getInstance().startPushSystem(MyActivity.class, R.drawable.icon, customDialog);
}
MyActivity.class

: Actividad que desea que se abra cuando se recibe el Push 

R.drawable.icon

: (Opcional) El resource id de la imagen que desea mostrar con la notificación Push. Si no se especifica ningún icono, el Push utilizará el icon de la app.

customDialog

: (Opcional) Establecerlo para asegurar que se desea utilizar su Custom Dialog. 

Añadir el método de Activity's onNewIntent() llamando a eMMa.onNewNotification(), que verificará si el usuario ha recibido una notificación cuando la app esta abierta.

@Override
public void onNewIntent(Intent intent) {
super.onNewIntent(intent);
    EMMA.getInstance().onNewNotification(this, intent, true);
}

Nota: El boolean que tiene como parámetro el método onNewNotification comprueba que el push contiene Rich Push Url en el caso de estar a true.

Para comprobar el richPushUrl cuando se abre la app desde la notificación, añade en la activity de push lo siguiente:

public class YOUR_ACTIVITY extends Activity{

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    EMMA.getInstance().checkForRichPushUrl();
}

Nota: El checkForRichPushUrl también se puede utilizar en cualquier parte de la app si se prefiere.

Si tu aplicación se basa en un WebView, tienes que añadir el checkForRichPushUrl en el siguiente método:

webView.setWebViewClient(new WebViewClient(){
.......
@Override
public void onPageFinished(new WebViewClient() { EMMA.getInstance().checkForRichPushUrl(); });

Opcionalmente, si deseas controlar qué recibe de un Push, su Activity debe implementar la interfaz EMMANotificationInterface y los métodos pushTag(String pushTag) y pushMessage(String message) que serán llamados cuando el usuario abra la notificación (incluso aunque no establezcas un pushTag en la plataforma de EMMA). Asimismo, puedes indicar si quiere mostrar el EMMA Dialog o su propio Custom Dialog.

@Override
public void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  EMMA.getInstance().getNotificationInfo();
} @Override
public void pushTag(String pushTag) {
//Do whatever you want with pushTag
} @Override
public void pushMessage(String message) {
//Create your own dialog with the push message
}

Para inhabilitar las notificaciones de un dispositivo, use EMMA.getInstance().unregisterPushService() y asegúrate de no llamar de nuevo a EMMA.getInstance().startPushSystem(...).

Puedes utilizar métodos abreviados si no necesitas todos los parámetros. Puede encontrarlos aquí.

Push Image

Puedes seleccionar el color que quieras en las notificaciones push incluyendo la siguiente línea de código: 

EMMA.getInstance().startPushSystem(PushActivity.class, R.drawable.notification_icon,
ContextCompat.getColor(this, R.color.colorPrimary), true);

Rich Push, sonidos personalizados en las notificaciones push. Se necesita la versión del SDK 2.5.5 o una superior

Para usar sonidos personalizados en las notificaciones que envíes con EMMA, tienes que añadir los archivos de sonido que quieras a la carpeta raw de los recursos de tu app (carpeta res). Recuerda que debes emplear para los sonidos los mismos nombres de archivo en iOS y Android.

Rich Push URL uso DeepLinking

Puedes redireccionar las aperturas de las notificaciones push a una sección en tu app. Para ello debes usar una estructura como esta: 

scheme://host/page1/page2/page3...

La versión 4.2 trae cambios referentes a la gestión del deep link. Para integrarlo sigue los siguientes pasos:

1) Añade la siguiente actividad en el AndroidManifest.xml :

<activity
android:name="io.emma.android.activities.EMMADeepLinkActivity"
android:theme="@android:style/Theme.NoDisplay">

<intent-filter>
<action android:name="android.intent.action.VIEW"/>

<category android:name="android.intent.category.DEFAULT"/>
<category android:name="android.intent.category.BROWSABLE"/>

<data android:scheme="YOUR_SCHEME"
                   android:host="YOUR_HOST"/>
</intent-filter>
</activity>

2) Añade la actividad a ser lanzada, en forma de meta-data dentro del tag <application></application> en AndroidManifest.xml. Esta actividad sera lanzada cuando el SDK ejecute un deep link:

<meta-data
android:name="io.emma.DEEPLINK_OPEN_ACTIVITY"
android:value="com.your.package.CustomDeeplinkActivity"/>

Recuerda que en caso de ser una actividad que se pueda encontrar abierta en la app cuando un deep link se ejecute, se tiene que declarar en el AndroidManifest.xml como singleTask:

<activity
android:name=".activities.MainActivity"
android:launchMode="singleTask" />

En este caso, si la actividad esta en la pila cuando se ejecuta el deep link, el intent con la información de este vllegará al método de la actividad onNewIntent. En caso de no tener el "launchMode" como singleTask ocasiona que la actividad se instancie nuevamente, lo que produce duplicaciones.

3) Para que el deep link que se introduce en el campo Rich Push URL (en la web de EMMA) se ejecute correctamente, es importante añadir el siguiente método en la actividad que es abierta por el push o alguna otra que sea consecuente de esta, pero que se ejecute al abrir la app desde la notificación:

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
EMMA.getInstance().checkForRichPush();
} @Override
protected void onNewIntent(Intent intent) {
super.onNewIntent(intent);
EMMA.getInstance().onNewNotification(intent, true);
}

El método checkForRichPush y onNewNotification comprueban el campo Rich Push enviado en el payload de la notificación y realizan las acciones pertinentes. En el caso de ser un deep link lo ejecutarán abriendo la actividad definida en el metadato del AndroidManifest.xml.

4) Definir el comportamiento de la actividad que ha de abrir el deep link. En este caso CustomDeepLinkActivity:

    @Override
   protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       setContentView(R.layout.view);

        if (getIntent() != null && getIntent().getData() != null){
            processDeepLink(getIntent().getData());
        }
finish();
   } private void processDeepLink(Uri uri){
       if (uri != null && uri.getHost().equals("home")){
          goHome();
       }
   }

   @Override
   public void onNewIntent(Intent intent){
       processDeepLink(intent.getData());
   }

5) Por último, declara en EMMA el scheme o schemes definidos:

    EMMA.getInstance().setDeepLinkSchemes(YOUR_SCHEME);

 

IMPORTANTE: sigue los siguientes pasos para la extracción del Server Key de Google.

1. Dirígete a la web de Firebase

2. Si no estás registrado, regístrate con una cuenta de google y vete a GO TO CONSOLE

server_1.png

3. Crea un proyecto nuevo:

server_2.png

4. Una vez creado el nuevo proyecto, dirígete a la sección de Project Settings

server_3.png

5. Una vez ahí, pulsa sobre la pestaña de CLOUD MESSAGING

server_4.png

6. Una vez dentro de esta pestaña, copia los valores del Server Key y Sender ID

server_5.png

7. Por último, vuelve a EMMA y dirígete a la sección de My Account. Pega los valores que copiaste en el paso anterior en el apartado de Android de la configuración de tu aplicación:

server_6.png

 

Integración Messaging

Messaging incluye 7 formatos comunicativos diferentes que puedes integrar para impactar a tus usuarios:

 En muchos de estos formatos comunicativos puedes delimitar las url's de redirección que quieres introducir. Con la funcionalidad de EMMA Whitelist puedes delimitar qué contenido quieres que se muestre en las webviews programadas. 

 

Revisar Campaña 

EMMAInAppRequest inAppRequest = new EMMAInAppRequest(EMMACampaign.Type.BANNER);
EMMA.getInstance().getInAppMessage(inAppRequest);

Usa getInAppMessage para revisar la campaña creada en la plataforma de EMMA correspondiente al Type especificado

Para mostrar el estado de la petición y si esta devuelve una datos de una campaña datos es necesario añadir el siguiente listener:

EMMAInAppRequest inAppRequest = new EMMAInAppRequest(EMMACampaign.Type.STARTVIEW);
//Optional inAppRequest.setCustomId("my custom id")
inAppRequest.setRequestListener(new EMMARequestListener() {
   @Override
   public void onStarted(String id) {
   }

   @Override
   public void onSuccess(String id, boolean containsData) {
   }

   @Override
   public void onFailed(String id) {    
   }
}); EMMA.getInstance().getInAppMessage(inAppRequest);

Campaña con etiqueta

EMMAInAppRequest inAppRequest = new EMMAInAppRequest(EMMACampaign.Type.BANNER);
inAppRequest.setLabel("label");
EMMA.getInstance().getInAppMessage(inAppRequest);

Si lo deseas puedes pasar un custom String que etiquete la campaña en caso de que utilices más de una campaña del mismo tipo en tu app y necesites distinguirlas.

Añadir interfaz

EMMA.getInstance().addInAppMessageListener(new EMMAInAppMessageInterface() {
@Override
public void onShown(EMMACampaign campaign) {

}

@Override
public void onHide(EMMACampaign campaign) {

}

@Override
public void onClose(EMMACampaign campaign) {

}
});

EMMAInAppRequest inAppRequest = new EMMAInAppRequest(EMMACampaign.Type.BANNER);
inAppRequest.setLabel("label");
EMMA.getInstance().getInAppMessage(inAppRequest);

Si lo deseas puedes añadir una (o varias) interfaces para recibir los diferentes eventos referentes a las  campañas de tu app.

 

Usando EMMA Banner 

EMMA Banner le muestra al usuario un banner en su app con información promocional personalizable. El banner se mostrará y esconderá dependiendo de la configuración que se establezca en la plataforma. Si se presiona dicho banner se abrirá una webview con contenido en HTML.

EMMA_13.png

 

Revisar Banner 

EMMAInAppRequest inAppRequest = new EMMAInAppRequest(EMMACampaign.Type.BANNER);
EMMA.getInstance().getInAppMessage(inAppRequest);

 

Usando EMMA Startview 

EMMA StartView es un formato de Comunicación In-App que muestra una webview en HTML cuando se abre una app o en pantallas concretas de esta.

EMMA_14.png

Para habilitarla en tu app, necesitas ejecutar primero el método startSession.

Revisar StartView 

EMMAInAppRequest inAppRequest = new EMMAInAppRequest(EMMACampaign.Type.STARTVIEW);
EMMA.getInstance().getInAppMessage(inAppRequest);

 

Usando EMMA Adball 

EMMA AdBall te permite mostrar un pequeño gráfico circular en tu aplicación que el usuario puede desplazar libremente por la pantalla de inicio de la app y también cerrarla. Si se presiona sobre este aparece un pop-up con contenido HTML.

EMMA_15.png

Si deseas habilitar el AdBall necesita al menos implementar el primer método. Se puede configurar siguiendo estas indicaciones.

Revisar Adball 

EMMAInAppRequest inAppRequest = new EMMAInAppRequest(EMMACampaign.Type.ADBALL);
EMMA.getInstance().getInAppMessage(inAppRequest);

 

Usando EMMA Dynamic Tab

Actualmente esta funcionalidad no esta disponible para Android.

 

Usando EMMA Strip

El EMMA Strip te permite mostrar un banner de texto sobre donde se sitúa habitualmente el Status Bar con un mensaje para sus usuarios. Este puede ser desplegado en cualquier pantalla de la app.

 EMMA_17.png

Revisar Strip 

EMMAInAppRequest inAppRequest = new EMMAInAppRequest(EMMACampaign.Type.STRIP);
EMMA.getInstance().getInAppMessage(inAppRequest);

 

Usando EMMA Coupons

EMMA Coupons te permite obtener, verificar, canjear cupones que se hayan definido y configurado en la plataforma de EMMA.

EMMA_18.png

Obtener Coupons 

EMMA.getInstance().addCouponsCallback(new EMMACouponsInterface() {
@Override
public void onCouponsReceived(List<EMMACoupon> coupons) {

}

@Override
public void onCouponsFailure() {

}

@Override
public void onCouponRedemption(boolean success) {

}

@Override
public void onCouponCancelled(boolean success) {

}

@Override
public void onCouponValidRedeemsReceived(int numRedeems) {

}
});

EMMAInAppRequest inAppRequest = new EMMAInAppRequest(EMMACampaign.Type.COUPON);
EMMA.getInstance().getInAppMessage(inAppRequest);

Con esta llamada, obtendremos toda la información de los coupons disponibles para el usuario, según las condiciones que se hayan configurado en la plataforma de EMMA.

Se devolverá un listado de los cupones existentes listándose primero los cupones automáticos ordenados de más reciente a  más antiguos y después se listarán los cupones clásicos ordenados también de más reciente a más antiguo.  

Se llama a EMMACouponsInterface.onCouponsReceived(List<EMMACoupon>) en el caso de que el usuario tenga disponibles coupons para canjear, o a EMMACouponsInterface.onCouponsFailure() si el usuario no tiene coupons disponibles.

EMMACoupon contiene toda la información relativa al coupon: id (identificador interno de EMMA), código, número máximo de canjeos, número de veces canjeado, título, descripción, imagen …

Si se quiere enviar a EMMA la información de cuando se ha hecho click en el coupon o cuando este se muestra en la pantalla, hay que añadir los siguientes métodos cuando se realicen ambas acciones en la app:

EMMA.getInstance().sendInAppImpression(CommunicationTypes.COUPON, couponCampaign);
EMMA.getInstance().sendInAppClick(CommunicationTypes.COUPON, couponCampaign);

Una vez pintado el Coupon en pantalla es necesario llamar a este método

Detalles de un Coupon

EMMAInAppRequest inAppRequest = new EMMAInAppRequest(EMMACampaign.Type.COUPON);
inAppRequest.setInAppMessageId("couponId");
EMMA.getInstance().getInAppMessage(inAppRequest);

Con esta llamada, obtendremos la información relativa a un coupon concreto.

El parámetro couponId debe ser el identificador interno de EMMA de un coupon, identificador que se puede obtener de una llamada a getCoupons hecha con anterioridad.

Se llama a EMMACouponsInterface.onCouponsReceived(List<EMMACoupon>) en el caso de que el coupon indicado exista, o a EMMACouponsInterface.onCouponsFailure() en caso contrario.

EMMACoupon contiene toda la información relativa al coupon: id (identificador interno de eMMa), código, número máximo de canjeos, número de veces canjeado, título, descripción, imagen …

Revisar la validez de un Coupon 

EMMAInAppRequest inAppRequest = new EMMAInAppRequest(EMMACampaign.Type.COUPON_VALID_REDEEMS);
inAppRequest.setInAppMessageId("couponId");
EMMA.getInstance().getInAppMessage(inAppRequest);

Con esta llamada podemos comprobar si el usuario puede canjear el coupon indicado.

El parámetro couponId debe ser el identificador interno de EMMA de un coupon, identificador que se puede obtener de una llamada a getCoupons hecha con anterioridad.

Se llama a EMMACouponsInterface.onCouponsValidRedeems(int numRedeems), donde numRedeems indica el número de veces que todavía puede ser canjeado el coupon o -1 en caso de error. 

Canjear un coupon 

EMMAInAppRequest inAppRequest = new EMMAInAppRequest(EMMACampaign.Type.REDEEM_COUPON);
inAppRequest.setInAppMessageId("couponId");
EMMA.getInstance().getInAppMessage(inAppRequest);

Con esta llamada, el usuario canjea el coupon indicado.

El parámetro couponId debe ser el identificador interno de EMMA de un coupon, identificador que se puede obtener de una llamada a getCoupons hecha con anterioridad.

Se llama a EMMACouponsInterface.onCouponRedemption(boolean success), donde success indica si se ha canjeado el coupon.

Cancelar un coupon

EMMAInAppRequest inAppRequest = new EMMAInAppRequest(EMMACampaign.Type.CANCEL_COUPON);
inAppRequest.setInAppMessageId("couponId");
EMMA.getInstance().getInAppMessage(inAppRequest);

Con esta llamada se puede cancelar el canjeo de un coupon realizado con anterioridad.

El parámetro couponId debe ser el identificador interno de EMMA de un coupon identificador que se puede obtener de una llamada a getCoupons hecha con anterioridad.

Se llama a EMMACouponsInterface.onCouponCancelled(boolean success), donde success indica si se ha cancelado el coupon.

Nota

El error 511 informa de que el redeem no se ha podido completar por alguna razón. Algunas posibles causas podrían ser la interrupción de la conexión con la BBDD o múltiples redenciones afectadas por un capping.  Recomendamos, en estos casos, tratar este error y avisar al usuario final. 

 

Usando EMMA NativeAd

EMMA NativeAd te permite obtener la información de un NativeAd correspondiente a una plantilla que se haya definido y configurado en la plataforma de EMMA.

Formatos-integracion-android.png

Obtener NativeAd 

EMMANativeAdInterface nativeAdInterface = new EMMANativeAdInterface() {
@Override
public void onReceived(EMMANativeAd nativeAd) {

}

@Override
public void onShown(EMMACampaign campaign) {

}

@Override
public void onHide(EMMACampaign campaign) {

}

@Override
public void onClose(EMMACampaign campaign) {

}
};
EMMANativeAdRequest nativeAdRequest = new EMMANativeAdRequest();
nativeAdRequest.setTemplateId("myTemplateId");
EMMA.getInstance().getInAppMessage(nativeAdRequest, this);

Con esta llamada, obtendremos toda la información del NativeAd disponible para el usuario referente al templateId, según las condiciones que se hayan configurado en la plataforma de EMMA.

Se llama a EMMANativeAdInterface.onReceived(EMMANativeAd nativeAd) en el caso de que exista un NativeAd correspondiente al identificador de la plantilla correspondiente ("myTemplateId").

EMMANativeAd contiene todos los campos configurados en EMMA para esta plantilla de NativeAd, para obtenerlos se usará el siguiente método:

@Override
public void onReceived(EMMANativeAd nativeAd) {
try {
String title = nativeAd.getField("Title");
} catch (EMMAFieldNotFoundException e) {
//Esta Exception se la lanzará cuando el nativeAd no contenga ningún campo con el nombre indicado
e.printStackTrace();

Una vez obtenidos todos los campos requeridos, ya se puede crear la vista para pintar este NativeAd en pantalla en función del diseño que se le quiera aplicar. Una vez pintado el NativeAd en pantalla es necesario llamar a este método:

EMMA.getInstance().sendInAppImpression(CommunicationTypes.NATIVE_AD, nativeAd);

Abrir un NativeAd

EMMA.getInstance().openNativeAd(nativeAd);

Con esta llamada, se mostrará el contenido del link configurado en el NativeAd desde la plataforma de EMMA.

 

NativeAds Múltiples

En Android hay un nuevo callback para gestionar los nuevos Native Ad múltiples. Este callback se llama EMMABatchNativeAdInterface y extiende de EMMAInAppMessageInterface. Al igual que el callback para la devolución de un único Native Ad.

public interface EMMABatchNativeAdInterface extends EMMAInAppMessageInterface {
    void onReceived(List nativeAds);
}

Para Native Ad múltiple se utilizará una subclase de EMMAInAppRequest, EMMANativeAdRequest. 

NativeAd múltiple (devuelve todos los Native Ad disponibles de un Template) [Desde la version 4.2.6 de Android SDK en adelante 

EMMANativeAdRequest requestParams = new EMMANativeAdRequest();
requestParams.setTemplateId("<BATCH_NATIVE_AD_TEMPLATE>);
requestParams.setBatch(true);
EMMA.getInstance().getInAppMessage(requestParams, this);

NativeAd único (devuelve el Native Ad más reciente disponible de un Template)

EMMANativeAdRequest requestParams = new EMMANativeAdRequest();
requestParams.setTemplateId(NATIVE_AD_TEMPLATE2); EMMA.getInstance().getInAppMessage(requestParams, this)

La diferencia es el parámetro batch que se tendrá que cambiar a true en caso de que se quiera una recepción múltiple de NativeAd. Por defecto este valor será false.

Una vez obtenidos los NativeAd la clase EMMANativeAd tendrá un nuevo campo tag de tipo string que podrá ser null o contener el string con tag. El método se llama getTag().

 

EMMA Whitelist

Versión mínima del SDK: 2.5.6 o superior

Con esta funcionalidad podemos limitar las urls que abrirá el SDK de EMMA, de modo que en las comunicaciones In-App, sólo se mostrarán en un Webview aquel contenido que empiece por alguna de las urls que hayamos indicado en la whitelist.

Si no indicamos ninguna url en la whitelist, cualquier url está permitida.

Esta funcionalidad afectaría a los Push (Rich URL), Banners, StartViews y AdBalls.

Las comunicaciones (Banners, StartViews y AdBalls)  pueden cargar contenido externo a la app mediante un Webview y para los Banners y AdBalls podrían cargar imágenes externas que también serían controladas por la whitelist.

Para un Push con Rich URL, si ésta no cumple, no se abriría la Webview correspondiente, pero el push sí que llega a la aplicación, hay que tener en cuenta que si en vez de una url se emplea un deeplink, el scheme del deeplink debe ser añadido a la whitelist para poder abrirlo.

Cómo se usa 

Debemos llamar a este método después del startSession y antes de llamar a cualquier método relativo a las comunicaciones In-App.

EMMA.getInstance().setWhitelist(List<String> urls);

Ejemplos

Si mi whitelist es “http://mydomain.com”.

List<String> whitelist = Arrays.asList("http://mydomain.com");
EMMA.getInstance().setWhitelist(whitelist);

Ejemplo 1:

Subimos al dashboard de EMMA un Banner con Target URL https://mydomain.com

El Banner no se mostrará, deberíamos añadir a la whitelist https://mydomain.com

Ejemplo 2:

Configuramos en el dashboard de EMMA una StartView con StartView URL http://www.mydomain.com

La StartView no se mostrará, deberíamos añadir a la whitelist http://www.mydomain.com

Ejemplo 3:

Configuramos en el dashboard de EMMA un Banner con Target URL http://mydomain.com/my/url y SmartPhone Banner URL http://subdomain.mydomain.com/my/image

El Banner no se mostrará, la url de la imagen no cumple con la whitelist, deberíamos añadir a la whitelist http://subdomain.mydomain.com

Ejemplo 4:

Subimos al dashboard de EMMA un Banner con Target URL http://mydomain.com/my/url/

El Banner se mostrará porque la url introducida en el campo Target URL empieza por el mismo protocolo y dominio que la url de la whitelist

Ejemplo 5:

Configuramos en el dashboard de EMMA una StartView con StartView URL http://mydomain.com/mypage.html&param=value

La StartView se mostrará porque la url intoducida en el campo StartView URL empieza por el mismo protocolo y dominio que la url de la whitelist

 

Deshabilitar seguimiento publicitario

EMMA permite inhabilitar el trackeo o seguimiento para aquellos usuarios que manifiesten este deseo. 

Este método es la mejor forma de adaptarse a la nueva RGPD (Reglamento General de la Protección de Datos).

La comunicación del usuario para expresar esta opción de no seguimiento debe ser tratada por la app haciendo una llamada al siguiente método: 

EMMA.getInstance().disableUserTracking(boolean deleteUser);

En el caso de que se quiera volver a activar las comunicaciones del usuario, se puede utilizar este otro método:

EMMA.getInstance().enableUserTracking();

 

Depurando el código

Este paso es opcional. Si necesitas ver el log de EMMA, habilítelo antes de startSession llamando:

EMMA.getInstance().setDebuggerOutput(true);

Ten en cuenta que EMMA no trabaja estrictamente en tiempo real. Se puede tardar hasta una hora en ver sus datos.

¿Tiene más preguntas? Enviar una solicitud

0 Comentarios

Inicie sesión para dejar un comentario.