Firebase Analytics: Vordefinierte Events mit Event Parametern

Nachdem im ersten Teil der Firebase Analytics Serie die Einbindung von Firebase Analytics in eine App behandelt und im zweiten Teil die Erfassung automatischer Events dargestellt wurde, dreht sich der dritte Teil um die vordefinierten Events und wie zusätzliche Informationen als Event Parameter mitgesendet werden können. Hierzu nutzen wir wieder die aus bisherigen Teilen dieser Artikelserie bekannte IntroApp.

Events in Firebase Analytics – Die Theorie

Im zweiten Teil dieser Artikelserie haben wir gesehen, das Firebase bestimmte Events wie session_start oder screen_view automatisch erhebt. Im Gegensatz zu Google Analytics sind Firebase Analytics Events nicht in eine Hierachie wie Category, Action, Label aufgeteilt, sondern lediglich durch den Bezeichner identifiziert. Die Bezeichner für Events in Firebase Analytics sind dabei case-sensitive. Werden beispielsweise „Screen_view“ und „screen_view“ als Bezeichner verwendet, werden diese als zwei verschiedene Events ausgewiesen. Der Bezeichner darf keine Sonderzeichen außer dem _ enthalten und muss mit einem Buchstaben anfangen. Die Namen der automatisch erfassten Events können natürlich ebenso wenig als Bezeichner genutzt werden wie die Prefixe ga_, google_ und firebase_.

Zudem existiert ein Limit für die Anzahl der Event-Bezeichner pro angelegter App im Firebase Projekt. 500 verschiedene Event-Bezeichner können genutzt werden, inklusive der automatisch erfassten Events.

Common und Custom Events

In Firebase Analytics sind vordefinierte Events verfügbar. Dies sind Events, die nicht automatisch erfasst werden, aber häufige Anwendungsfälle in einer App abbilden, beispielsweise Käufe oder Lead- Generierung. Diese Events besitzen teilweise vordefinierte Parameter und ermöglichen es Firebase Analytics, den Kontext für ein Events in Firebase besser abzubilden. Beispielsweise kann der Umsatz bei einem Kauf direkt in Firebase dargestellt werden, anstatt die Events auszuwerten. Einige dieser Events wie first_open oder ecommerce_purchase sind bereits automatisch in Firebase Analytics als Conversion hinterlegt.

Eine Übersicht der vordefinierten Events findet sich in der Firebase Hilfe.

Für Anwendungsfälle, für die kein vordefiniertes Event existiert, kann ein Event frei definiert werden. Auch hier können die gesendeten Informationen selbst definiert werden. In Firebase Analytics wird allerdings kein Kontext zu den Daten erfasst, sondern die Events und mitgesendeten Informationen übersichtlich präsentiert.

ecommerce_purchase in die App einbauen

Erweitern wir nun die App, um die Funktion Käufe zu erfassen. In unserer IntroApp befindet sich bereits ein Button am unteren Bildschirmrand, der eine sogenannte Snackbar (Benachrichtungsfenster am unteren Bildschirmrand) öffnet. Hier bauen wir eine Kauffunktion ein. Klickt ein User auf diese Funktion, möchten wir eine Transaktion über 10 EUR erfassen. Hierfür sind mehrere Änderungen an der MainActivity nötig.

Zuerst importieren wir im Header der MainActivity.kt Datei die Klassen:

import com.google.firebase.analytics.FirebaseAnalytics.Event
import com.google.firebase.analytics.FirebaseAnalytics.Param

Mit diesen Klassen kann auf die vordefinierten Events zugegriffen werden. Nun müssen wir diese nur noch mit den passenden Werten füllen. Um die Snackbar einfach anzupassen, greifen wir auf die Design Library zurück, mit der diese Standardelemente eingebunden werden können. Hierfür fügen wir noch zwei Klassen hinzu:

import com.google.android.material.snackbar.Snackbar
import android.view.View

Die Funktionalität wird in der onCreate()-Methode in der Zeile

fab.setOnClickListener { view ->
            Snackbar.make(view, "Replace with your own action", 
            Snackbar.LENGTH_LONG)
            .setAction("Action", null).show()}

festgelegt.

Wir werfen den Code komplett weg und ersetzen diese durch

fab.setOnClickListener {
    val snack = Snackbar.make(it,"Click to Buy", Snackbar.LENGTH_LONG)
    snack.setAction("Buy", View.OnClickListener {
        val params = Bundle()
        params.putDouble(Param.VALUE, 10.00)
        params.putString(Param.CURRENCY, "EUR")
        firebaseAnalytics.logEvent(Event.ECOMMERCE_PURCHASE, params)
    })
    snack.show()
}

Neben dem Verhalten der Snackbar ist im Code bereits das Firebase ecommerce_purchase Tracking integriert. Sehen wir uns dies genauer an.

Mit Snackbar.make wird eine Snackbar erzeugt. Der übergebene Parameter „it“ definiert den Parent-View in dem die Snackbar eingehangen werden soll. Da sich dieser implizit hier ergibt, ist ein Bezeichner unnötig und es reicht „it“. (Mehr Informationen hierzu auf kotlinlang) Der zweite Parameter definiert den anzuzeigenden Text und der dritte Parameter gibt an, wie lange Snackbar eingeblendet werden soll. Der Wert LENGTH_INDEFINITE bewirkt, das die Snackbar auf unbestimmte Zeit geöffnet bleibt. Alternative Werte sind LENGTH_SHORT und LENGTH_LONG. Durch die Zuweisung an die Variable snack kann die Snackbar nun darüber angesprochen werden.

Dies wird nun genutzt, um eine Aktion in die Snackbar einzufügen, den Buy-Button. Mit snack.setAction wird im ersten Parameter der Text des Buttons definiert und im zweiten Parameter wird View.OnClickListener definiert, das prüft ob dieser Text geklickt wurde. View ist eine generische Klasse, die wir bereits mit „import android.view.View“ importiert haben und sich um die Anzeige und das Event-Handling der Komponente kümmert. View.OnClickListener enthält eine Callback-Funktion, die aufgerufen wird, wenn ein Klick erfolgt. Hier findet sich der Code für das Tracking des Kaufes. Mit dem nachfolgenden snack.show wird die Snackbar eingeblendet.

Kommen wir nun zum Punkt des ecommerce_purchase-Trackings. Die ist durch die folgenden Codezeilen integriert:

val params = Bundle()
params.putDouble(Param.VALUE, 10.00)
params.putString(Param.CURRENCY, "EUR")
firebaseAnalytics.logEvent(Event.ECOMMERCE_PURCHASE, params)

Mit val params = Bundle() wird params (val = read-only value) als Bundle() initialisiert. Bundle ist eine Klasse, die ein Mapping von Key-Value Pairs bereitstellt. In params werden die neben dem Event gesendeten Informationen gespeichert, bevor das Event selbst gesendet wird. Für vordefinierte Events sind auch vordefnierte optionale und erforderliche Event-Parameter verfügbar (siehe Übersicht in der Firebase Hilfe.

Für ecommerce_purchase werden keine erforderlichen Event Parameter vorausgesetzt, allerdings möchten wir den Transaktionswert von 10.00 EUR erfassen. Neben den Wert benötigen wir also auch die Währung.

Zuerst wird der Wert zugewiesen mit params.putDouble(Param.VALUE, 10.00). Dadurch wird in dem Bunde params ein Key-Value Pair mit dem Key Param.VALUE und der Zahl 10.00 zugewiesen. Da es sich um einen vordefiniertes Event handelt, muss auch der Wert in dem dafür vorgesehenen Key gespeichert werden. Dafür wird auf die bereits importierte Klasse com.google.firebase.analytics.FirebaseAnalytics.Param zurückgegegriffen. Das vordefinierte ecommerce_purchase Event unterstützt den vordefinierten Parameter VALUE, der in der Klasse com.google.firebase.analytics.FirebaseAnalytics.Param definiert ist. Daher wird als Key Param.VALUE verwendet.

Als nächstes wird die Währung übergeben mit params.putString(Param.CURRENCY, „EUR„). Currency wird im ISO_4217 Format (3 Buchstaben Identifier) erwartet. Daher wird nun putString genutzt. Param.CURRENCY ist der vordefinerte Parameter aus der bereits importierten Klasse. Als Wert nutzen wir „EUR“ für EURO.

Nun muss das Event mit den Parametern abgesendet werden. Ebenso wie bei den Parameter gibt es bei vordefinierten Events eine passende Klasse, die das Handling der Events übernimmt. Mit com.google.firebase.analytics.FirebaseAnalytics.Event wurde diese bereits importiert. Nun muss das Event noch abgesendet oder im Firebase Jargon geloggt werden. Dies erfolgt durch

firebaseAnalytics.logEvent(Event.ECOMMERCE_PURCHASE, params)

Event.ECOMMERCE_PURCHASE ist das vordefinierte Event aus der Klasse und in params befinden sich die Informationen zum Transaktionswert und der Währung.

Starten wir nun die App und senden die Events.

Das ecommerce_purchase Event wird erfasst und gleichzeitig als Conversion (grünes Event mit Flagge) markiert. Als Parameter ist Currency und Value verfügbar.

firebase-ecommerce-purchase-currrency-value

In den Reports wird nach einigen Stunden (bis zu 24 Stunden) der Wert auch ausgewiesen.

firebase-ecommerce-purchase-currrency-value-dashboard

Fehler-Handling bei Parametern vordefinierter Events

Das Hinzufügen und Verarbeiten der Event-Parameter bei vordefinierten Events ist ein Prozess, bei dem sich Fehler einschleichen können, zum Beispiel der falsche Variablentyp. Ändern wir nun die App zum Test kurz ab um den Value nicht als Double sondern als String zu senden. Hierfür ersetzen wir

params.putDouble(Param.VALUE, 10.00)

durch

params.putString(Param.VALUE, “10”)

in der App und führen den Code aus. Da syntaktisch alles richtig ist, wird kein Fehler in Android Studio angezeigt. Euch das Event in Firebase wird korrekt erfasst.

Allerdings enthält das Event nicht den Parameter value sondern nun die die Parameter firebase_error und error_value. error_value zeigt an, das value nicht korrekt interpretiert werden konnte. Um herauszufinden, welcher Fehler vorliegt, klicken wir auf den Link neben firebase_error und suchen dort den Error Code, den firebase_error enthält, hier 18. Der Link führt zu https://firebase.google.com/docs/analytics/errors. Error Code 18 bedeutet „Invalid value parameter type“ und zeigt an, das ein Parameter im falschen Typ gesendet wurde. Machen wir also die vorhergehende Änderung wieder Rückgängig.

Automatisch hinzugefügte User-Properties

User-Properties sind Werte, die einem User, nicht einem Event zugeordnet werden. Eine User-Property haben wir schon in den vorhergehenden Teilen kennengelernt: first_time_open. Diese gibt den Zeitpunkt an, an dem die App das erste Mal geöffnet wurde. Beim ecommece_purchase Event wird eine weitere User-Property hinzugefügt: der Livetimevalue oder ltv. Diese gibt den Umsatz des Users in der App an. Da im vorhergehenden Beispiel EUR als Währung genutzt wurde, heißt die User-Property _ltv_EUR.

Hat ein User, wie in diesem Beispiel 2 Käufe zu je 10 EUR durchgeführt, beträgt der Wert der User-Property _ltv_EUR 20000000, da Werte für den Lifetimevalue mit 1.000.000 multipliziert werde.

Senden wir nun ein neues Event für einen Umsatz von 10.00 USD an Firebase Analytics. Hierfür ändern wir EUR in USD im Quellcode. Für diesen Umsatz legt Firebase Analytics eine neue User-Property _ltv_USD und dem Wert 10000000 an. Bis zu vier unterschiedliche Währungen werden so erfasst.