Integrazione con Android

Android è la piattaforma mobile più utilizzata al mondo. Siamo molto felici di avere una libreria di integrazione ufficiale per Android. Se stai cercando React Native, per favore consulta React Native per iOS, per favore consulta iOS docs. Per altre integrazioni mobili, per favore consulta integrazione mobile. Se stai usando Android, sei nel posto giusto. Iniziamo!

Installazione

Installazione con Gradle

Passo 1. Aggiungi il repository di JitPack al tuo file di build

Aggiungi `maven { url 'https://jitpack.io' }` alla fine del tuo build.gradle nei repository:

gradle

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

Passo 2. Aggiungi la dipendenza alle dipendenze della tua applicazione:

gradle

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

Installazione con Maven

Passo 1. Aggiungi il repository di JitPack al tuo file di build

gradle

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

Passo 2. Aggiungi la dipendenza alle dipendenze della tua applicazione:

gradle

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

Utilizzo

Abbiamo cercato di rendere l'integrazione flessibile e fluida per mantenere l'esperienza dello sviluppatore al massimo livello. Qui condivideremo un esempio completo di MainActivity.kt per mostrare come puoi integrare Metricalp nella tua applicazione Android. Descriveremo il codice passo dopo passo come dettagliato di seguito.

kotlin
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 {
                // A surface container using the 'background' color from the theme
                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") }
}

Sappiamo che è un'applicazione molto brutta, ma aiuterà a comprendere le basi, fidati di noi. Per prima cosa, importiamo import com.metricalp.android.Metricalp la libreria attraverso la quale chiamiamo i metodi.

Il primo metodo da chiamare è Metricalp.init ed è il più importante da integrare correttamente. Inizializzeremo Metricalp per raccogliere eventi. È importante fare questo nel file di ingresso (MainActivity). Metricalp.init accetta attributi (HashMap<String,String>), la schermata iniziale path (per auto scatenare la prima screen_view come opzionale). Se fornisci la schermata iniziale come null, allora verrà ignorato l'evento auto scatenato della prima screen_view. Altrimenti, passa solo null. Spiegheremo:

Attributi del Metodo Metricalp.init()

app

Devi fornire il nome e la versione della tua applicazione. È importante fornire la versione per tracciarla nel pannello di controllo. Puoi fornire come AppName@Version come ExampleApp@1.0.0. Questo aiuta a tracciare il numero di utenti di ciascuna versione.

metr_user_language (opzionale)

La lingua che l'utente sta utilizzando nella tua applicazione. Puoi fornirla come Language (Nome completo)-Paese (Codice ISO) English-US come nel esempio sopra o Italian-IT o Turkish-TR ecc. Se non sei sicuro del paese, puoi fornire sconosciuto. Ad esempio English-unknown

metr_unique_identifier (obbligatorio)

Dobbiamo spiegare questo prop metr_unique_identifier. Normalmente nel tracciamento web, anche se Metricalp non utilizza cookie come abbiamo menzionato in molti posti, identifichiamo gli utenti con i loro indirizzi IP in hash unidirezionali. La formula è qualcosa del tipo: hash(user_ip + user_agent + salt). Qui ip + user_agent è quasi unico per ogni utente. Ma nelle applicazioni mobili, le stringhe di user agent sono incoerenti e non affidabili. Quindi abbiamo bisogno di un identificatore unico per ogni utente. Lasciamo questo identificatore unico a te. Puoi usare qualsiasi identificatore unico per la tua applicazione. Ad esempio, se è un'applicazione di autorizzazione e stai tracciando solo dopo che gli utenti hanno effettuato l'accesso, allora puoi fornire identificatori utente. Oppure puoi usare identificatori univoci reali relativi al dispositivo (Android e iOS hanno alcuni metodi nativi per ottenerlo). O puoi generare un UUID casuale quando l'utente apre l'applicazione per la prima volta e memorizzarlo nello storage locale. Poi usalo come metr_unique_identifier. Ora, l'algoritmo di hash sarà come hash(user_ip + metr_unique_identifier + salt). In questo approccio, il metr_unique_identifier non cambierà a meno che l'utente non elimini e reinstalla l'applicazione. Ma è giusto. Se non ti basta, puoi fornire il tuo identificatore unico come abbiamo menzionato in precedenza. ID utente o identificatore del dispositivo o qualsiasi altra combinazione.

Nell'esempio sopra, abbiamo generato un UUID casuale, lo abbiamo messo in sharedPreferences (memoria permanente) e lo abbiamo usato come metr_unique_identifier. Suggeriamo di usare questo approccio. Ma puoi usare qualsiasi identificatore unico per la tua applicazione. Ma ricorda, deve essere unico per ogni utente e non deve cambiare a meno che l'utente non elimini e reinstalla l'applicazione.

metr_bypass_ip

Questo è un prop opzionale. I valori possibili sono "enable" o "disable". Se vedi l'esempio finale di hash con metr_unique_identifier: hash(user_ip + metr_unique_identifier + salt), abbiamo ancora informazioni sull'IP nell'hash. Quindi, quando l'utente, ad esempio, è su WiFi e poi passa a una rete mobile, l'IP cambierà. Mentre il metr_unique_identifier è lo stesso, a causa del cambio di IP, può essere contato come un altro conteggio unico per quel giorno. Questa impostazione elimina anche l'IP dall'hash. Se lo imposti su "enable", allora non useremo l'IP nella funzione di hash (come predefinito): hash(metr_unique_identifier + salt). Ma se passi disable, allora anche l'IP sarà usato nella funzione di hash: hash(user_ip + metr_unique_identifier + salt). Non lo suggeriamo perché rompere il conteggio unico con l'IP è senza senso nella maggior parte degli scenari per i mobili. Quindi, impostiamo la configurazione predefinita su enable. Quindi, nella maggior parte degli scenari, non passare questa opzione, lasciala come predefinita (enable).

tid (obbligatorio)

Devi fornire il tuo TID (noto anche come ID di tracciamento) al metodo init. Puoi ottenerlo dal pannello di controllo di Metricalp. È obbligatorio. Se non lo fornisci, riceverai un errore. Puoi trovare il tuo tid nella pagina Embed & Share Tracker .

C'è un evento di sistema importante in Metricalp screen_view. Stiamo tracciando le schermate visitate, i tassi di rimbalzo, ecc., basati su questo evento. Pertanto, ti consigliamo vivamente di scatenare questo evento nella tua applicazione oltre a qualsiasi evento personalizzato. Nella tua logica di navigazione, ad ogni cambiamento di schermata da parte dell'utente, devi scatenare un evento di screen_view. Nell'esempio sopra, stiamo ascoltando onStart per Android e scatenando questo evento. Puoi scatenarlo in un altro posto, il posto non è importante, ma ti consigliamo di scatenare questo evento in qualche luogo per un miglior tracciamento.

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

Il metodo Metricalp.screenViewEvent fornito dalla libreria facilita le cose per te. Devi fornire il nome della schermata attuale (percorso) a questo metodo. Puoi anche passare eventuali dati aggiuntivi (props personalizzati) a questo metodo come secondo argomento (di nuovo HashMap<String,String>). Il terzo argomento è un altro HashMap se desideri annullare i props iniziali (configurazioni) per l'evento attuale, altrimenti passa solo null.

kotlin
Metricalp.screenViewEvent("MainScreen", hashMapOf<String, String>("custom_prop1" to "Utente non autenticato"), null);

o

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

Qui il tema è un alias di prop personalizzato. Puoi consultare Evento Personalizzato & Props docs per maggiori dettagli.

Fondamentalmente, questo è tutto. Ora hai integrato con successo la tua applicazione Android con Metricalp. Un'altra cosa è che puoi anche creare alcuni eventi personalizzati per ottenere ulteriori dettagli.

C'è un'altra cosa importante: generare gli eventi di uscita necessari quando l'app si chiude. Metricalp fornisce anche un metodo personalizzato per questo Metricalp.appLeaveEvent(). Puoi vedere che stiamo scatenando questo evento appLeave nel gestore onStop. Questo ci aiuta a catturare la durata della vista della schermata degli utenti. Puoi anche passare eventuali dati aggiuntivi (props personalizzati) a questo metodo come primo argomento (di nuovo HashMap<String,String>). Il secondo argomento è un altro HashMap se desideri annullare i props iniziali (configurazioni) per l'evento attuale, altrimenti passa solo null.

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

Eventi Personalizzati

C'è anche un altro metodo della libreria per eventi personalizzati: Metricalp.customEvent. Prende il tipo di evento come primo argomento e gli attributi dei dati come secondo argomento. Il terzo argomento è un altro HashMap se desideri annullare i props iniziali (configurazioni) per l'evento attuale, altrimenti passa solo null. Puoi usarlo così:

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

Qui abbiamo creato un evento personalizzato e l'abbiamo scatenato quando l'utente clicca sul pulsante. Puoi aggiungere qualsiasi evento che desideri e raccogliere i dati per il tuo tracciamento.