Integration mit React Native

Wir wissen, dass React Native in letzter Zeit sehr beliebt ist. Es bietet eine großartige Entwicklererfahrung (DX) und beschleunigt Projekte erheblich. Wir freuen uns sehr, eine offizielle Integrationsbibliothek zu haben und React Native vollständig zu unterstützen. Wenn Sie nach Android suchen, schauen Sie bitte unter Android und für iOS schauen Sie bitte unter iOS. Für andere mobile Integrationen schauen Sie bitte unter mobile Integration. Wenn Sie React Native verwenden, sind Sie hier genau richtig. Los geht's!

Unsere offizielle Integrationsbibliothek auf NPM heißt @metricalp/react-native

Installation

Sie können sie wie folgt installieren:

yarn add @metricalp/react-native

oder

npm install @metricalp/react-native

Integration

Wir haben versucht, die Integration flexibel und reibungslos zu gestalten, um die Entwicklererfahrung auf höchstem Niveau zu halten. Hier teilen wir eine vollständige App.tsx (aus einem Beispiel-Expo-Projekt), um zu zeigen, wie Sie Metricalp in Ihre React Native App in Ihrer Einstiegsdatei (App.js, main.js, index.js...) integrieren können. Dann definieren wir alle Details des Codes unten.

        import { StatusBar } from 'expo-status-bar';
        import { AppState, NativeEventSubscription, Platform, StyleSheet, Text, View } from 'react-native';
        import { Metricalp } from '@metricalp/react-native';
        import * as Crypto from 'expo-crypto';
        import AsyncStorage from '@react-native-async-storage/async-storage';
        import { useEffect, useState } from 'react';
        
        export default function App() {
          const [appInitialized, setAppInitialized] = useState(false);
        
          useEffect(() => {
            let subscription: NativeEventSubscription;
        
            async function init() {
              let uuid = await AsyncStorage.getItem('uuid');
              if (!uuid) {
                uuid = Crypto.randomUUID();
                await AsyncStorage.setItem('uuid', uuid);
              }
              const osWithVersion = (Platform.OS === 'ios' ? 'iOS' : 'Android') + ' ' + Platform.Version;
        
              Metricalp.init({
                platform: Platform.OS,
                app: 'ExampleApp@1.0.0',
                language: 'English-US',
                os: osWithVersion,
                uuid,
                tid: 'mam48',
              }, 'MainScreen');
        
              subscription = AppState.addEventListener('change', (nextAppState) => {
                if (nextAppState === 'background' || nextAppState === 'inactive') {
                  Metricalp.appLeaveEvent();
                } else if (nextAppState === 'active') {
                  Metricalp.screenViewEvent('MainScreen');
                }
              });
        
              setAppInitialized(true);
            }
        
            init();
        
            return () => {
              subscription?.remove();
            };
          }, []);
        
          return (
            <View style={styles.container}>
              {appInitialized ? (
                <View>
                  <Text>Open up App.tsx to start working on your app!</Text>
                  <StatusBar style="auto" />
                </View>
              ) : (
                <Text>Loading...</Text>
              )}
            </View>
          );
        }
        
        const styles = StyleSheet.create({
          container: {
            flex: 1,
            backgroundColor: '#fff',
            alignItems: 'center',
            justifyContent: 'center',
          },
        });
        

Zuerst haben wir die Bibliothek import { Metricalp } from '@metricalp/react-native'; importiert, mit der wir die Methoden aufrufen.

Die erste Methode, die aufgerufen wird, ist Metricalp.init und die wichtigste, um eine ordnungsgemäße Integration sicherzustellen. Wir initialisieren Metricalp, um Ereignisse zu sammeln. Es ist wichtig, dies in der Einstiegsdatei (App.js, main.js, index.js...) zu tun. Metricalp.init benötigt ein attributes Objekt und den initialen Bildschirm path (für das automatisch ausgelöste erste screen_view Ereignis als optional). Wenn Sie den initialen Bildschirm nicht angeben, wird das erste screen_view Ereignis übersprungen.

Metricalp.init() Attributsargumente

platform (erforderlich)

Sie müssen die aktuelle Plattform angeben. Mögliche Werte sind ios oder android. Alle müssen kleingeschrieben sein. Sie können es mit Platform.OS von react-native erhalten, wie im obigen Beispiel gezeigt.

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 Format AppName@Version angeben, z. B. ExampleApp@1.0.0 wie im obigen Beispiel.

language

Sie sollten die aktuelle Sprache Ihrer App angeben. Sie können es im Format Sprache (Langname)-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 unknown angeben, z. B. English-unknown.

os

Sie können Ihr aktuelles Betriebssystem und die Version angeben. Sie können es im Format BetriebssystemName BetriebssystemVersion angeben, z. B. iOS 14.5 wie im obigen Beispiel oder Android 11. Hier haben wir ios in iOS und android in Android umgewandelt, um im Dashboard schöne und konsistente Daten zu haben (nur Kleinbuchstaben => Großbuchstaben Umwandlungen). Es ist optional, aber empfohlen.

uuid

Wir müssen dieses UUID-Attribut erklären. Normalerweise verwendet Metricalp beim Web-Tracking keine Cookies, wie wir an vielen Stellen erwähnt haben. Wir identifizieren Benutzer mit ihren IP-Adressen in Einweg-Hashes. Die Formel sieht ungefähr so aus: hash(user_ip + user_agent + salt). Hier sind ip + user_agent für jeden Benutzer fast einzigartig. In mobilen Apps sind die User-Agent-Strings jedoch inkonsistent und nicht zuverlässig. Daher benötigen wir für jeden Benutzer einen eindeutigen Bezeichner. Wir überlassen Ihnen diesen eindeutigen Bezeichner. Sie können jeden eindeutigen Bezeichner für Ihre App verwenden. Wenn es sich beispielsweise um eine Autorisierungs-App handelt und Sie nur nach dem Login der Benutzer verfolgen, können Sie Benutzer-IDs angeben. Sie können auch gerätebezogene, echte eindeutige Bezeichner verwenden (Android und iOS haben einige native Methoden, um diese zu erhalten). Oder wie im obigen Beispiel können Sie eine zufällige UUID generieren, wenn der Benutzer die App zum ersten Mal öffnet und diese im Speicher speichern (wir haben oben AsyncStorage verwendet). Verwenden Sie dann diese UUID. Jetzt sieht der Hash-Algorithmus so aus: hash(user_ip + UUID + salt). In diesem Ansatz bleibt die UUID unverändert, es sei denn, der Benutzer entfernt und installiert die App neu. Aber das ist fair genug. Wenn das für Sie nicht ausreicht, können Sie Ihren eigenen eindeutigen Bezeichner wie oben erwähnt angeben. Benutzer-ID oder Gerätebezeichner oder jede andere Kombination. Wenn Sie nur die IP verwenden möchten, geben Sie einfach einen leeren String '' als UUID an oder lassen Sie ihn ganz weg. Aber wir empfehlen dringend, einen eindeutigen Bezeichner für ein besseres Tracking zu verwenden. UUID ist optional, aber empfohlen.

bypassIpUniqueness

Dies ist ein optionales Attribut. Mögliche Werte sind "enable" oder "disable". Wenn Sie sich das obige Hash-Beispiel mit metr_unique_identifier ansehen: hash(user_ip + metr_unique_identifier + salt), haben wir immer noch die IP-Informationen im Hash. Dann, wenn der Benutzer z. B. im WLAN ist und dann zum Mobilfunknetz wechselt, ändert sich die IP. Während metr_unique_identifier gleich bleibt, kann aufgrund der IP-Änderung eine zusätzliche einzigartige Zählung für diesen Tag vorgenommen werden. Diese Einstellung entfernt auch die IP aus dem Hash. Wenn Sie dies auf "enable" setzen, wird die IP nicht in der Hash-Funktion verwendet (als Standard): hash(metr_unique_identifier + salt). Wenn Sie jedochdisable übergeben, wird die IP auch in der Hash-Funktion verwendet: hash(user_ip + metr_unique_identifier + salt). Wir empfehlen dies nicht, da das Aufbrechen der einzigartigen Zählung mit IP in den meisten Szenarien für Mobilgeräte keinen Sinn ergibt. Daher setzen wir diese Einstellungen standardmäßig auf enable. In den meisten Szenarien geben Sie diese Option also nicht an, lassen Sie es als Standard (enable).

tid (erforderlich)

Sie sollten Ihre TID (alias Tracking ID) an die Init-Methode übergeben. Sie können es aus dem Metricalp-Dashboard abrufen. Es ist erforderlich. Wenn Sie es nicht angeben, erhalten Sie einen Fehler. Sie können Ihre tid auf der Seite Embed & Share Trackerfinden.

Weitere Details zur Integration

Nun, wir haben alle möglichen Attribute definiert. Aber es gibt ein paar Details im obigen Code. Lassen Sie uns diese nun erklären.

Erstens haben wir die App-Initialisierung in useEffect mit einer asynchronen Funktion durchgeführt. Wir haben einen Zustand festgelegt, um dem Benutzer einen Lade-Text anzuzeigen, während wir die Initialisierung durchführen. Sie können einen Splash-Screen oder jeden anderen Ladebildschirm anzeigen. Sie können in dieser Funktion alle anderen Einstellungen für Ihre App initialisieren und konfigurieren, dies ist ein gängiger Ansatz.

Innerhalb der init()-Funktion (in useEffect) prüfen wir auf eine UUID in AsyncStorage, wenn keine vorhanden ist, generieren wir sie. AsyncStorage und UUID-Funktionen stammen von Expo, aber Sie können jede gewünschte Bibliothek verwenden. Dann generieren wir einen OS mit Versionsstring. Dann rufen wir Metricalp.init mit allen Attributen auf. Wie oben erwähnt, wird Metricalp das erste screen_view-Ereignis automatisch mit dem Pfad (zweites Argument der init-Funktion) auslösen, aber Sie können dies überspringen, indem Sie das zweite Argument weglassen.

   Metricalp.init({
          platform: Platform.OS,
          app: 'ExampleApp@1.0.0',
          language: 'English-US',
          os: osWithVersion,
          uuid,
          bypassIpUniqueness: true,
          tid: 'mam48',
    }) // Hier haben wir den Bildschirmnamen weggelassen, um das automatische Auslösen zu deaktivieren.

Es gibt zwei wichtige Systemereignis-Szenarien in der Metricalp React Native-Integration: Bildschirmansicht und App verlassen. Wir verfolgen besuchte Bildschirme, Absprungraten usw. basierend auf diesen Ereignissen. Daher empfehlen wir dringend, diese Ereignisse zusätzlich zu allen benutzerdefinierten Ereignissen in Ihrer App auszulösen. Sie sollten die von der Bibliothek bereitgestellten Methoden verwenden, um diese Ereignisse auszulösen. Im obigen Beispiel hören wir auf Änderungen im AppState durch React Native und lösen diese Ereignisse aus, wenn die App aktiv oder inaktiv/im Hintergrund ist. Wir verwenden die Methoden screenViewEvent und appLeaveEvent aus der Bibliothek.

        ...
        ...
        subscription = AppState.addEventListener('change', (nextAppState) => {
          if (nextAppState === 'background' || nextAppState === 'inactive') {
            Metricalp.appLeaveEvent();
          } else if (nextAppState === 'active') {
            Metricalp.screenViewEvent('MainScreen');
          }
        });
  
        setAppInitialized(true); // Status setzen, um App-Inhalt anzuzeigen
      }
  
      init(); // init-Funktion aufrufen
  
      return () => {
        subscription?.remove(); // Abonnement beim Unmount entfernen, um Speicherlecks zu verhindern
      };
      ...
      ...

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 alle zusätzlichen Daten (benutzerdefinierte Attribute) an diese Methoden als zweites Argument übergeben:

Metricalp.screenViewEvent('MainScreen', { custom_prop1: 'Unauthenticated User' });

Die Methode Metricalp.appLeaveEvent wird von der Bibliothek ebenfalls bereitgestellt, um es Ihnen zu erleichtern. Sie können alle zusätzlichen Daten (benutzerdefinierte Attribute) an diese Methoden als erstes Argument übergeben:

Metricalp.appLeaveEvent({ custom_prop1: 'Unauthenticated User' });

Hier ist das Thema ein benutzerdefiniertes Attribut-Alias. Weitere Informationen finden Sie unter Benutzerdefinierte Ereignisse & Attribute.

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

Benutzerdefinierte Ereignisse

Es gibt auch eine andere Methode der Bibliothek für benutzerdefinierte Ereignisse: Metricalp.customEvent. Es benötigt den Ereignistyp als erstes Argument und die Datenattribute als zweites Argument. Sie können es verwenden wie:

Metricalp.customEvent('click_purchase', {path: 'PricingScreen', custom_prop1: user.id, theme: 'dark'})

Hier haben wir die Pfadinformationen übergeben, auch haben wir user.id als benutzerdefiniertes Attribut übergeben. Ein weiteres benutzerdefiniertes Attribut wurde übergeben: theme, aber dieses Mal haben wir das Alias verwendet. Weitere Informationen finden Sie unter Benutzerdefinierte Ereignisse & Attribute. Jetzt können Sie mit der Leistung benutzerdefinierter Ereignisse und Attribute jedes Ereignis verfolgen und analysieren, um tiefere Einblicke zu gewinnen.