Integración con Android

Android es la plataforma móvil más utilizada en el mundo. Estamos muy contentos de tener una biblioteca de integración oficial para Android. Si buscas React Native, por favor revisa React Native o si buscas iOS, por favor revisa iOS documentación. Para otras integraciones móviles, por favor revisa integración móvil. Si estás con Android, ¡estás en el lugar correcto! ¡Vamos a empezar!

Instalación

Instalación con Gradle

Paso 1. Agrega el repositorio de JitPack a tu archivo de construcción

Agrega `maven { url 'https://jitpack.io' }` en tu archivo build.gradle raíz al final de repositories:

        dependencyResolutionManagement {
          repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
          repositories {
            mavenCentral()
            maven { url 'https://jitpack.io' }
          }
        }
        

Paso 2. Agrega la dependencia a tus dependencias de aplicación:

        dependencies {
	        implementation 'com.github.metricalp:android:1.5'
	}
        

Instalación con Maven

Paso 1. Agrega el repositorio de JitPack a tu archivo de construcción

      <repositories>
        <repository>
            <id>jitpack.io</id>
            <url>https://jitpack.io</url>
        </repository>
      </repositories>
        

Paso 2. Agrega la dependencia a tus dependencias de aplicación:

    <dependency>
        <groupId>com.github.metricalp</groupId>
        <artifactId>android</artifactId>
        <version>1.5</version>
    </dependency>
        

Uso

Hemos intentado hacer la integración flexible y fluida para mantener la mejor experiencia del desarrollador. Aquí compartiremos un ejemplo completo de MainActivity.kt para mostrarte cómo puedes integrar Metricalp en tu aplicación Android. Describiremos el código paso a paso como se detalla a continuación.

package com.myapp.test

import android.content.Context
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.material3.Button
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import com.metricalp.android.Metricalp
import com.myapp.test.ui.theme.TestappTheme
import java.util.UUID

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val sharedPref = getSharedPreferences("app_data", Context.MODE_PRIVATE)
        var uuid = sharedPref.getString("user_uuid", null);
        if (uuid == null) {
            uuid = UUID.randomUUID().toString()
            with (sharedPref.edit()) {
                putString("user_uuid", uuid)
                apply()
            }
        }
        Metricalp.init(hashMapOf<String, String?>("tid" to "mam48", "metr_unique_identifier" to uuid,  "app" to "ExampleApp@1.0.0", "metr_user_language" to "English-US"), null, null)
        setContent {
            TestappTheme {
                // Un contenedor de superficie usando el color 'background' del tema
                Surface(
                    modifier = Modifier.fillMaxSize(),
                    color = MaterialTheme.colorScheme.background
                ) {
                    RenderButton()
                }
            }
        }
    }

    public override fun onStart() {
        super.onStart()
        Metricalp.screenViewEvent("MainScreen", null, null);
    }

    public override fun onStop() {
        super.onStop()
        Metricalp.appLeaveEvent(null, null);
    }
}

@Composable
fun RenderButton() {
    Button(onClick = { Metricalp.customEvent("button_click", hashMapOf<String, String>("path" to "HomepageScreen", "custom_prop1" to "top_button", "theme" to "dark"), null ) }) { Text("Button") }
}

Sabemos que es una aplicación muy básica, pero te ayudará a entender lo fundamental, confía en nosotros. En primer lugar, importamos la biblioteca import com.metricalp.android.Metricalp que utilizamos para llamar a los métodos.

El primer método que debes llamar es Metricalp.init y el más importante es integrarlo correctamente. Inicializaremos Metricalp para recopilar eventos. Es importante hacer esto en el archivo de entrada (MainActivity). Metricalp.init toma atributos (HashMap<String,String>), la pantalla inicial path (para el primer screen_view autoactivado como opcional). Si proporcionas la pantalla inicial como null, se omitirá el evento de screen_view autoactivado. También podemos pasar atributos de evento para ese primer screen_view, como otro argumento opcional. De lo contrario, simplemente pasa null. Vamos a explicar:

Propiedades del Argumento Attributes de Metricalp.init()

app

Debes proporcionar el nombre y la versión de tu aplicación. Es importante proporcionar la versión para rastrearla en el panel de control. Puedes proporcionarlo en el formato AppName@Version, como ExampleApp@1.0.0 en el ejemplo anterior.

metr_user_language

Debes proporcionar el idioma actual de tu aplicación. Puedes proporcionarlo en el formato Language (nombre completo)-Country(ISO Code), como English-US en el ejemplo anterior o Spanish-ES o Turkish-TR, etc. Si no estás seguro acerca del país, puedes proporcionar unknown. Por ejemplo, English-unknown.

metr_unique_identifier (requerido)

Necesitamos explicar esta propiedad metr_unique_identifier. Normalmente en el seguimiento web, aunque Metricalp no usa cookies como mencionamos en muchos lugares, identificamos a los usuarios con sus direcciones IP en hashes unidireccionales. La fórmula es algo así: hash(user_ip + user_agent + salt). Aquí ip + user_agent es casi único para cada usuario. Pero en aplicaciones móviles, las cadenas de agente de usuario son inconsistentes y no confiables. Por lo tanto, necesitamos tener un identificador único para cada usuario. Dejamos este identificador único para ti. Puedes usar cualquier identificador único para tu aplicación. Por ejemplo, si es una aplicación de autorización y solo estás rastreando después de que los usuarios inicien sesión, entonces puedes proporcionar IDs de usuario. O puedes usar identificadores únicos reales relacionados con el dispositivo (Android e iOS tienen algunos métodos nativos para obtenerlo). O, puedes generar un UUID aleatorio cuando el usuario abre la aplicación por primera vez y almacenarlo en el almacenamiento local. Luego, úsalo como metr_unique_identifier. Ahora, el algoritmo de hash será como hash(user_ip + metr_unique_identifier + salt). En este enfoque, el metr_unique_identifier no cambiará a menos que el usuario elimine y reinstale la aplicación. Pero eso es suficiente. Si esto no es suficiente para ti, puedes proporcionar tu propio identificador único como mencionamos anteriormente. ID de usuario o identificador del dispositivo o cualquier otra combinación.

En el ejemplo anterior, generamos un UUID aleatorio, lo guardamos en SharedPreferences (almacenamiento permanente) y lo usamos como metr_unique_identifier. Sugerimos usar este enfoque. Pero puedes usar cualquier identificador único para tu aplicación. Pero ten en cuenta, debe ser único para cada usuario y no debe cambiar a menos que el usuario elimine y reinstale la aplicación.

metr_bypass_ip

Esta es una propiedad opcional. Los valores posibles son "enable" o "disable". Si ves el ejemplo final de hash con metr_unique_identifier: hash(user_ip + metr_unique_identifier + salt), aún tenemos información de IP en el hash. Entonces, cuando el usuario, por ejemplo, cambia de Wifi a red móvil, la IP cambiará. Mientras que el metr_unique_identifier es el mismo, debido al cambio de IP, puede contar como otro único para ese día. Esta configuración también elimina la IP del hash. Si lo estableces como "enable", entonces no utilizaremos IP en la función de hash (por defecto): hash(metr_unique_identifier + salt). Pero si pasas disable, entonces la IP también se usará en la función de hash: hash(user_ip + metr_unique_identifier + salt). No sugerimos esto porque romper el conteo único con IP no tiene sentido en la mayoría de los escenarios para móviles. Entonces, establecemos esta configuración como habilitada por defecto. Por lo tanto, en la mayoría de los escenarios, simplemente no pases esta opción, déjala como predeterminada (habilitada).

tid (requerido)

Debes proporcionar tu TID (también conocido como Tracking ID) al método de inicialización. Puedes obtenerlo desde el panel de control de Metricalp. Es obligatorio. Si no lo proporcionas, recibirás un error. Puedes encontrar tu TID en la página de Embed & Share Tracker.

Hay un evento del sistema importante en Metricalp screen_view. Estamos rastreando pantallas visitadas, tasas de rebote, etc., basándonos en este evento. Por lo tanto, te recomendamos encarecidamente que dispares este evento en tu aplicación además de cualquier evento personalizado. En tu lógica de navegación, en cada cambio de pantalla por parte del usuario, deberías disparar un evento screen_view. En el ejemplo anterior, estamos escuchando onStart por Android y disparando este evento. Puedes dispararlo en otro lugar, el lugar no es importante, pero aconsejamos que dispares este evento en algún lugar para un mejor seguimiento.

      ...
      ...
      public override fun onStart() {
          super.onStart()
          Metricalp.screenViewEvent("MainScreen", null, null);
      }
  
      ...
      ...

El método Metricalp.screenViewEvent proporcionado por la biblioteca facilita esto. Debes proporcionar el nombre de la pantalla actual (path) a este método. También puedes pasar cualquier dato adicional (props personalizados) a este método como segundo argumento (de nuevo HashMap<String,String>). El tercer argumento es otro HashMap si deseas anular las propiedades iniciales (configuraciones) para el evento actual, de lo contrario, simplemente pasa null.

Metricalp.screenViewEvent("MainScreen", hashMapOf<String, String>("custom_prop1" to "Usuario no autenticado"), null);

o

Metricalp.screenViewEvent("MainScreen", hashMapOf<String, String>("theme" to "Tema Oscuro"), null);

Aquí el tema es un alias de props personalizados. Puedes consultar la documentación de Eventos y Props Personalizados para obtener información detallada.

Básicamente eso es todo. Ahora has integrado con éxito tu aplicación Android con Metricalp. Una cosa más es que también puedes crear algunos eventos personalizados para obtener una visión más profunda.

Otra cosa importante es generar los eventos necesarios de salida al abandonar la aplicación. Metricalp también proporciona un método personalizado para esto: Metricalp.appLeaveEvent(). Puedes ver que estamos disparando este evento appLeave en el manejador onStop. Esto nos ayuda a capturar la duración de las vistas de pantalla de los usuarios. También puedes pasar cualquier dato adicional (props personalizados) a este método como primer argumento (de nuevo HashMap<String,String>). El segundo argumento es otro HashMap si deseas anular las propiedades iniciales (configuraciones) para el evento actual, de lo contrario, simplemente pasa null.

 public override fun onStop() {
        super.onStop()
        Metricalp.appLeaveEvent(null, null);
    }

Eventos Personalizados

También hay otro método en la biblioteca para eventos personalizados: Metricalp.customEvent. Toma el tipo de evento como primer argumento y los atributos de datos como segundo argumento. El tercer argumento es otro HashMap si deseas anular las propiedades iniciales (configuraciones) para el evento actual, de lo contrario, simplemente pasa null. Puedes usarlo así:

Metricalp.customEvent("button_click", hashMapOf<String, String>("path" to "HomepageScreen", "custom_prop1" to "top_button", "theme" to "dark"), null )

Aquí pasamos información del path, también pasamos info top_button como prop personalizada. Pasamos otra prop personalizada theme pero usamos un alias esta vez. Puedes consultar la documentación de Eventos y Props Personalizados para obtener información detallada. Ahora, con el poder de los eventos y props personalizados, puedes rastrear y analizar cualquier evento para obtener una visión profunda de tu aplicación Android fácilmente.