Integrazione con React Native
Sappiamo che React Native è molto famoso ultimamente. Ha un'ottima esperienza per gli sviluppatori (DX) e fornisce molta velocità ai progetti. Siamo molto felici di avere una libreria di integrazione ufficiale e di supportare pienamente React Native. Se stai cercando l'integrazione per Android consulta Android e per iOS consulta iOS. Per altre integrazioni mobili consulta integrazione mobile. Se sei su React Native, sei nel posto giusto. Iniziamo!
La nostra libreria di integrazione ufficiale su NPM si chiama @metricalp/react-native
Installazione
Puoi installarla come segue:
yarn add @metricalp/react-native
oppure
npm install @metricalp/react-native
Integrazione
Abbiamo cercato di rendere l'integrazione flessibile e fluida per mantenere l'esperienza dello sviluppatore al massimo livello. Condivideremo un file App.tsx completo (da un progetto di esempio Expo) per mostrare come puoi integrare Metricalp nella tua app React Native nel file di entrypoint (App.js, main.js, index.js...). Poi definiremo ogni dettaglio del codice sottostante.
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: '[email protected]',
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',
},
});
Prima di tutto, abbiamo importato la libreria import { Metricalp } from '@metricalp/react-native'; con cui richiamare i metodi.
Il primo metodo da chiamare è Metricalp.init, che è il più importante per una corretta integrazione. Inizializziamo Metricalp per raccogliere gli eventi. È importante farlo nel file di entrypoint (App.js, main.js, index.js...). Metricalp.init richiede un oggetto attributes e il path dello schermo iniziale (per l'auto trigger del primo evento screen_view come opzionale). Se non fornisci lo schermo iniziale, salterà l'auto trigger del primo evento screen_view. Vediamo i dettagli:
Metricalp.init() Attributi
platform (richiesto)
Devi fornire la piattaforma attuale. I valori possibili sono ios o android. Tutti devono essere in minuscolo. Puoi ottenerli con Platform.OS da react-native come nell'esempio sopra.
app
Devi fornire il nome e la versione della tua app. È importante fornire la versione per poterla tracciare nel dashboard. Puoi fornirlo nel formato NomeApp@Versione, ad esempio [email protected] come nell'esempio sopra.
language
Devi fornire la lingua attuale della tua app. Puoi farlo nel formato Lingua (nome lungo)-Paese(Codice ISO), ad esempio English-US come nell'esempio sopra o Spanish-ES o Turkish-TR ecc. Se non sei sicuro del paese, puoi fornire unknown. Ad esempio English-unknown.
os
Puoi fornire il sistema operativo attuale della tua app e la versione. Puoi farlo nel formato NomeOS VersioneOS, ad esempio iOS 14.5 come nell'esempio sopra o Android 11. Qui abbiamo convertito ios in iOS e android in Android per avere dei dati coerenti e belli nel dashboard (solo conversioni minuscolo => maiuscolo). È opzionale ma consigliato.
uuid
Dobbiamo spiegare questo prop UUID. Normalmente nel tracking web, Metricalp non utilizza cookie come abbiamo menzionato in molti posti. Identifichiamo gli utenti con i loro indirizzi IP tramite hash unidirezionali. La formula è qualcosa del tipo: hash(user_ip + user_agent + salt). Qui ip + user_agent è quasi unico per ogni utente. Ma nelle app mobile, le stringhe 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 app. Ad esempio, se si tratta di un'app di autorizzazione e stai tracciando solo dopo che gli utenti hanno effettuato l'accesso, puoi fornire gli id utente. Oppure puoi utilizzare identificatori unici relativi al dispositivo (Android e iOS hanno alcuni metodi nativi per ottenerlo). Oppure, come nell'esempio sopra, puoi generare un UUID casuale quando l'utente apre per la prima volta l'app e memorizzarlo nello storage (abbiamo usato AsyncStorage sopra). Quindi usalo come UUID. Ora, l'algoritmo di hashing sarà simile a hash(user_ip + UUID + salt). In questo approccio, l'UUID non cambierà a meno che l'utente non rimuova e reinstalli l'app. Ma è abbastanza giusto. Se non è sufficiente per te, puoi fornire il tuo identificatore unico come menzionato sopra. ID utente o identificatore del dispositivo o qualsiasi altra combinazione. Se vuoi usare solo l'IP, passa semplicemente una stringa vuota '' come UUID o omettilo completamente. Ma ti consigliamo vivamente di utilizzare un identificatore unico per un miglior tracciamento. UUID è opzionale ma consigliato.
bypassIpUniqueness
Questo è un prop opzionale. I valori possibili sono "enable" o "disable". Se osservi l'esempio di hash finale sopra con metr_unique_identifier: hash(user_ip + metr_unique_identifier + salt), abbiamo ancora l'informazione IP nell'hash. Quindi, quando l'utente ad esempio è su Wifi e poi passa alla rete mobile, l'IP cambierà. Mentre metr_unique_identifier è lo stesso, a causa del cambio IP, potrebbe essere conteggiato come un altro conteggio unico per quel giorno. Questa impostazione rimuove anche l'ip dall'hash. Se imposti questo su "enable", non useremo l'IP nella funzione di hash (come predefinito): hash(metr_unique_identifier + salt). Ma se passi disable, l'ip verrà utilizzato 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 mobile. Quindi, impostiamo questa impostazione di default come enable. Quindi, nella maggior parte degli scenari non passare questa opzione, lascia che sia predefinito (enable).
tid (richiesto)
Devi fornire il tuo TID (alias Tracking ID) al metodo init. Puoi ottenerlo dal dashboard di Metricalp. È richiesto. Se non lo fornisci, otterrai un errore. Puoi trovare il tuo tid nella pagina Embed & Share Tracker.
Ulteriori dettagli sull'integrazione
Bene, abbiamo definito tutti i possibili props. Ma ci sono alcuni dettagli nel codice sopra. Spieghiamoli tutti ora.
In primo luogo, abbiamo fatto l'inizializzazione dell'app in useEffect con una funzione async. Impostiamo uno stato per mostrare un testo di caricamento all'utente mentre stiamo inizializzando. Puoi mostrare una schermata di avvio o qualsiasi altra schermata di caricamento. Puoi inizializzare e configurare qualsiasi altra impostazione per la tua app in questa funzione, questo è un approccio comune.
All'interno della funzione init() (in useEffect), controlliamo se c'è un UUID in AsyncStorage, se non c'è, lo generiamo. AsyncStorage e le funzioni UUID sono di Expo ma puoi usare qualsiasi libreria desideri. Poi generiamo una stringa OS con versione. Successivamente chiamiamo Metricalp.init con tutti i props. Come menzionato sopra, Metricalp attiverà automaticamente il primo evento screen_view con il percorso (secondo argomento della funzione init), ma puoi saltare questo omettendo il secondo argomento.
Metricalp.init({
platform: Platform.OS,
app: '[email protected]',
language: 'English-US',
os: osWithVersion,
uuid,
bypassIpUniqueness: true,
tid: 'mam48',
}) // Qui abbiamo omesso il nome dello schermo per disabilitare l'auto fireCi sono due scenari importanti di eventi di sistema nell'integrazione Metricalp React Native: visualizzazione schermo e uscita app. Tracciamo gli schermi visitati, i tassi di rimbalzo ecc in base a questi eventi. Quindi, suggeriamo vivamente di attivare questi eventi nella tua app in aggiunta a qualsiasi evento personalizzato. Dovresti utilizzare i metodi forniti dalla libreria per attivare questi eventi. Nell'esempio sopra, stiamo ascoltando i cambiamenti di AppState da React Native e attiviamo questi eventi ogni volta che l'app è attiva o in stato inattivo/sullo sfondo. Stiamo usando i metodi screenViewEvent e appLeaveEvent dalla libreria.
...
...
subscription = AppState.addEventListener('change', (nextAppState) => {
if (nextAppState === 'background' || nextAppState === 'inactive') {
Metricalp.appLeaveEvent();
} else if (nextAppState === 'active') {
Metricalp.screenViewEvent('MainScreen');
}
});
setAppInitialized(true); // Imposta lo stato per mostrare il contenuto dell'app
}
init(); // chiama la funzione init
return () => {
subscription?.remove(); // Rimuovi la sottoscrizione allo smontaggio per prevenire memory leaks
};
...
...Il metodo Metricalp.screenViewEvent è fornito dalla libreria per semplificare le cose. Devi fornire il nome dello schermo attuale (path) a questo metodo. Puoi anche passare qualsiasi dato aggiuntivo (props personalizzati) a questi metodi come secondo argomento:
Metricalp.screenViewEvent('MainScreen', { custom_prop1: 'Unauthenticated User' });Il metodo Metricalp.appLeaveEvent è fornito nuovamente dalla libreria per semplificare le cose. Puoi passare qualsiasi dato aggiuntivo (props personalizzati) a questi metodi come primo argomento:
Metricalp.appLeaveEvent({ custom_prop1: 'Unauthenticated User' });Qui il tema è un alias per una prop personalizzata. Puoi consultare Eventi personalizzati & Props per informazioni dettagliate.
In pratica è tutto. Hai integrato con successo la tua app React Native con Metricalp. Un'altra cosa, puoi anche creare alcuni eventi personalizzati per ottenere informazioni più dettagliate.
Eventi Personalizzati
C'è anche un altro metodo della libreria per gli eventi personalizzati: Metricalp.customEvent. Richiede il tipo di evento come primo argomento e gli attributi dei dati come secondo argomento. Puoi usarlo come:
Metricalp.customEvent('click_purchase', {path: 'PricingScreen', custom_prop1: user.id, theme: 'dark'})Qui abbiamo passato le informazioni del path, abbiamo anche passato user.id come custom_prop. Abbiamo passato un altro prop personalizzato theme, ma questa volta abbiamo usato l'alias. Puoi consultare Eventi Personalizzati & Props per informazioni dettagliate. Ora, con la potenza degli eventi personalizzati e delle props, puoi tracciare e analizzare qualsiasi evento per ottenere approfondimenti dettagliati.