Integration mit Android

Android ist die weltweit am häufigsten verwendete mobile Plattform. Wir freuen uns, eine offizielle Integrationsbibliothek für Android zu haben. Wenn Sie nach React Native suchen, schauen Sie sich bitte React Native an. Für iOS-Dokumente siehe iOS . Für andere mobile Integrationen siehe mobile Integration. Wenn Sie Android verwenden, sind Sie hier genau richtig. Lassen Sie uns beginnen!

Installation

Installation mit Gradle

Schritt 1. Fügen Sie das JitPack-Repository zu Ihrer Build-Datei hinzu

Fügen Sie `maven { url 'https://jitpack.io' }` am Ende der Repositories in Ihrer root build.gradle hinzu:

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

Schritt 2. Fügen Sie die Abhängigkeit zu Ihren App-Abhängigkeiten hinzu:

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

Installation mit Maven

Schritt 1. Fügen Sie das JitPack-Repository zu Ihrer Build-Datei hinzu

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

Schritt 2. Fügen Sie die Abhängigkeit zu Ihren App-Abhängigkeiten hinzu:

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

Verwendung

Wir haben versucht, die Integration flexibel und reibungslos zu gestalten, um die Entwicklererfahrung auf höchstem Niveau zu halten. Hier zeigen wir ein vollständiges MainActivity.kt-Beispiel, um zu zeigen, wie Sie Metricalp in Ihre Android-App integrieren können. Wir werden den Code Schritt für Schritt detailliert erklären.

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") }
}

Wir wissen, dass es sich um eine sehr einfache App handelt, aber sie hilft, die Grundlagen zu verstehen, vertrauen Sie uns. Zuerst haben wir die import com.metricalp.android.Metricalp-Bibliothek importiert, über die wir Methoden aufrufen.

Die erste Methode, die aufgerufen werden muss, ist Metricalp.init, und sie ist am wichtigsten, um die Integration ordnungsgemäß vorzunehmen. Wir initialisieren Metricalp, um Ereignisse zu sammeln. Es ist wichtig, dies in der Einstiegspunktdatei (MainActivity) zu tun. Metricalp.init benötigt Attribute (HashMap<String,String>), den anfänglichen Bildschirm Pfad (für optional automatisch ausgelöste erste Bildschirmansicht). Wenn Sie den anfänglichen Bildschirm auf null setzen, wird das automatisch ausgelöste erste Bildschirmansicht-Ereignis übersprungen. Wir können auch Ereignisattributen für dieses erste Bildschirmansicht-Ereignis als optionales weiteres Argument übergeben. Andernfalls einfach null übergeben. Lassen Sie uns das erklären:

Metricalp.init() Attribut-Argumente

app

Sie sollten den Namen und die Version Ihrer App angeben. Es ist wichtig, die Version anzugeben, um sie im Dashboard zu verfolgen. Sie können es im AppName@Version-Format angeben, z.B. ExampleApp@1.0.0.

metr_user_language

Sie sollten die aktuelle Sprache Ihrer App angeben. Sie können es im Format Sprache (voller Name)-Land (ISO-Code) angeben, z.B. English-US wie im obigen Beispiel oder Spanish-ES oder Turkish-TR usw. Wenn Sie sich über das Land nicht sicher sind, können Sie unbekannt angeben. Zum Beispiel English-unknown

metr_unique_identifier (erforderlich)

Wir müssen dieses metr_unique_identifier-Attribut erklären. Normalerweise im Web-Tracking, während Metricalp keine Cookies verwendet, wie wir an vielen Stellen erwähnt haben, identifizieren wir Benutzer mit ihren IP-Adressen in Einweg-Hashes. Die Formel ist etwa so: hash(user_ip + user_agent + salt). Hier ist ip + user_agent fast einzigartig für jeden Benutzer. Aber in mobilen Apps sind Benutzeragenten-Strings inkonsistent und nicht zuverlässig. Daher benötigen wir eine eindeutige Kennung für jeden Benutzer. Diese eindeutige Kennung überlassen wir Ihnen. Sie können jede eindeutige Kennung für Ihre App verwenden. Zum Beispiel, wenn es sich um eine Autorisierungs-App handelt und Sie nur nach dem Einloggen der Benutzer verfolgen, dann können Sie Benutzer-IDs angeben. Oder Sie können gerätespezifische echte eindeutige Kennungen verwenden (Android und iOS haben einige native Methoden, um diese zu erhalten). Oder Sie können eine zufällige UUID generieren, wenn der Benutzer die App zum ersten Mal öffnet, und sie im lokalen Speicher speichern. Dann verwenden Sie es als metr_unique_identifier. Jetzt wird der Hash-Algorithmus wie hash(user_ip + metr_unique_identifier + salt) aussehen. Bei diesem Ansatz bleibt die metr_unique_identifier unverändert, es sei denn, der Benutzer entfernt und installiert die App neu. Aber das ist fair genug. Wenn das nicht genug für Sie ist, können Sie eine eigene eindeutige Kennung angeben, wie oben erwähnt. Benutzer-ID oder Gerätekennzeichner oder eine andere Kombination.

Im obigen Beispiel haben wir eine zufällige UUID generiert, sie in sharedPreferences (dauerhafter Speicher) gespeichert und als metr_unique_identifier verwendet. Wir empfehlen diesen Ansatz. Aber Sie können jede eindeutige Kennung für Ihre App verwenden. Aber beachten Sie, dass sie für jeden Benutzer einzigartig sein sollte und sich nicht ändern sollte, es sei denn, der Benutzer entfernt und installiert die App neu.

metr_bypass_ip

Dies ist eine optionale Eigenschaft. Mögliche Werte sind „enable“ oder „disable“. Wenn Sie das obige finale Hash-Beispiel mit metr_unique_identifier sehen: hash(user_ip + metr_unique_identifier + salt), haben wir immer noch IP-Informationen im Hash. Wenn der Benutzer zum Beispiel in einem WLAN ist und dann zu einem mobilen Netzwerk wechselt, wird die IP geändert. Während metr_unique_identifier gleich bleibt, kann dies aufgrund der IP-Änderung als andere eindeutige Zählung für diesen Tag gezählt werden. Diese Einstellung entfernt auch die IP aus dem Hash. Wenn Sie dies als „enable“ setzen, verwenden wir die IP nicht in der Hash-Funktion (standardmäßig): hash(metr_unique_identifier + salt). Wenn Sie jedoch „disable“ übergeben, wird die IP auch in der Hash-Funktion verwendet: hash(user_ip + metr_unique_identifier + salt). Wir empfehlen dies nicht, da es die einzigartige Zählung bei der IP in den meisten Szenarien für Mobilgeräte nicht sinnvoll ist. Daher haben wir diese Einstellung standardmäßig auf aktiv gesetzt. In den meisten Szenarien sollten Sie diese Option einfach nicht übergeben und sie auf dem Standardwert (aktiv) belassen.

tid (erforderlich)

Sie sollten Ihre TID (auch bekannt als Tracking-ID) an die Init-Methode übergeben. Sie können es im Metricalp-Dashboard erhalten. Es ist erforderlich. Wenn Sie es nicht angeben, erhalten Sie einen Fehler. Sie können Ihre TID auf der Embed & Share Tracker -Seite finden.

Es gibt ein wichtiges Systemereignis in Metricalp screen_view. Wir verfolgen besuchte Bildschirme, Absprungraten usw. basierend auf diesem Ereignis. Daher empfehlen wir dringend, dass Sie dieses Ereignis zusätzlich zu benutzerdefinierten Ereignissen in Ihrer App auslösen. In Ihrer Navigationslogik sollten Sie bei jedem Bildschirmwechsel durch den Benutzer ein screen_view-Ereignis auslösen. Im obigen Beispiel hören wir in onStart von Android und lösen dieses Ereignis aus. Sie können es an anderer Stelle auslösen, der Ort ist nicht wichtig, aber wir raten dazu, dieses Ereignis an irgendeinem Ort auszulösen, um eine bessere Verfolgung zu gewährleisten.

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

Die Methode Metricalp.screenViewEvent wird von der Bibliothek bereitgestellt, um es Ihnen zu erleichtern. Sie sollten den aktuellen Bildschirmnamen (Pfad) an diese Methode übergeben. Sie können auch zusätzliche Daten (benutzerdefinierte Eigenschaften) als zweites Argument übergeben (wieder HashMap<String,String>). Das dritte Argument ist ein weiteres HashMap, wenn Sie die ursprünglichen Eigenschaften (Einstellungen) für das aktuelle Ereignis überschreiben möchten, andernfalls einfach null übergeben.

Metricalp.screenViewEvent("MainScreen", hashMapOf<String, String>("custom_prop1" to "Unauthenticated User"), null);

oder

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

Hier ist das Thema eine benutzerdefinierte Eigenschaft. Sie können die Custom Event & Props -Dokumentation für detaillierte Informationen überprüfen.

Im Wesentlichen ist das alles. Sie haben Ihre Android-App erfolgreich mit Metricalp integriert. Eine weitere Sache ist, dass Sie auch einige benutzerdefinierte Ereignisse erstellen können, um tiefere Einblicke zu erhalten.

Es gibt noch eine wichtige Sache: das Generieren der erforderlichen Verlassen-Ereignisse beim Verlassen der Anwendung. Metricalp bietet auch eine benutzerdefinierte Methode dafür Metricalp.appLeaveEvent(). Sie sehen, dass wir dieses appLeave-Ereignis im onStop-Handler auslösen. Dies hilft uns, die Bildschirmansichten der Benutzer zu erfassen. Sie können auch zusätzliche Daten (benutzerdefinierte Eigenschaften) als erstes Argument (wieder HashMap<String,String>). Das zweite Argument ist ein weiteres HashMap, wenn Sie die ursprünglichen Eigenschaften (Einstellungen) für das aktuelle Ereignis überschreiben möchten, andernfalls einfach null übergeben.

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

Benutzerdefinierte Ereignisse

Es gibt auch eine andere Methode aus der Bibliothek für benutzerdefinierte Ereignisse: Metricalp.customEvent. Sie nimmt den Ereignistyp als erstes Argument und die Datenattribute als zweites Argument. Das dritte Argument ist ein weiteres HashMap, wenn Sie die ursprünglichen Eigenschaften (Einstellungen) für das aktuelle Ereignis überschreiben möchten, andernfalls einfach null übergeben. Sie können es wie folgt verwenden:

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

Hier haben wir Pfadinformationen übergeben, auch Informationen zu top_button als benutzerdefinierte Eigenschaft. Wir haben eine andere benutzerdefinierte Eigenschaft Thema übergeben, aber dieses Mal haben wir ein Alias verwendet. Sie können die Custom Event & Props -Dokumentation für detaillierte Informationen überprüfen. Nun können Sie mit benutzerdefinierten Ereignissen und Eigenschaften alle Ereignisse verfolgen und analysieren, um tiefere Einblicke in Ihre Android-App zu erhalten.