Intégration avec React Native
Nous savons que React Native est très populaire récemment. Il offre une excellente expérience de développement (DX) et apporte beaucoup de rapidité aux projets. Nous sommes très heureux d'avoir une bibliothèque d'intégration officielle et de soutenir pleinement React Native. Si vous cherchez Android, veuillez consulter Android et pour iOS, veuillez consulter iOS. Pour d'autres intégrations mobiles, consultez intégration mobile. Si vous utilisez React Native, vous êtes au bon endroit. Commençons!
Notre bibliothèque d'intégration officielle sur NPM s'appelle @metricalp/react-native
Installation
Vous pouvez l'installer comme suit :
yarn add @metricalp/react-native
ou
npm install @metricalp/react-native
Intégration
Nous avons essayé de rendre l'intégration flexible et fluide pour maintenir la meilleure expérience de développement. Ici, nous partagerons un App.tsx complet (d'un projet Expo exemple) pour montrer comment intégrer Metricalp dans votre app React Native dans votre fichier d'entrée (App.js, main.js, index.js...). Ensuite, nous définirons tous les détails du code ci-dessous.
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',
},
});
Tout d'abord, nous avons importé la bibliothèque import { Metricalp } from '@metricalp/react-native'; avec laquelle nous appelons les méthodes.
La première méthode appelée est Metricalp.init et c'est la plus importante pour garantir une intégration correcte. Nous allons initialiser Metricalp pour collecter les événements. Il est important de faire cela dans le fichier d'entrée (App.js, main.js, index.js...). Metricalp.init prend un objet de attributes et le chemin de la première vue path (pour l'événement screen_view auto-déclenché en option). Si vous ne fournissez pas l'écran initial, l'événement screen_view sera omis.
Attributs de l'Argument Metricalp.init()
platform (obligatoire)
Vous devez fournir la plateforme actuelle. Les valeurs possibles sont ios ou android. Tout en minuscule. Vous pouvez l'obtenir avec Platform.OS de react-native comme dans l'exemple ci-dessus.
app
Vous devez fournir le nom et la version de votre application. Il est important de fournir la version pour la suivre sur le tableau de bord. Vous pouvez le fournir au format AppName@Version, comme ExampleApp@1.0.0 comme dans l'exemple ci-dessus.
language
Vous devez fournir la langue actuelle de votre application. Vous pouvez le fournir au format Langue (nom long)-Pays (Code ISO), comme English-US comme dans l'exemple ci-dessus ou Spanish-ES ou Turkish-TR, etc. Si vous n'êtes pas sûr du pays, vous pouvez fournir unknown. Par exemple, English-unknown.
os
Vous pouvez fournir le système d'exploitation actuel de votre application et la version. Vous pouvez le faire au format NomOS VersionOS, comme iOS 14.5 comme dans l'exemple ci-dessus ou Android 11. Ici, nous avons converti ios en iOS et android en Android pour avoir des données belles et cohérentes dans le tableau de bord (seulement des conversions minuscules => majuscules). C'est optionnel mais recommandé.
uuid
Nous devons expliquer cet attribut UUID. Normalement, dans le suivi Web, Metricalp n'utilise pas de cookies comme nous l'avons mentionné à plusieurs reprises. Nous identifions les utilisateurs avec leurs adresses IP dans des hachages à sens unique. La formule ressemble à ceci : hash(user_ip + user_agent + salt). Ici, ip + user_agent est presque unique pour chaque utilisateur. Mais dans les applications mobiles, les chaînes user-agent sont incohérentes et non fiables. Nous avons donc besoin d'un identifiant unique pour chaque utilisateur. Nous vous laissons cet identifiant unique. Vous pouvez utiliser n'importe quel identifiant unique pour votre application. Par exemple, si c'est une application d'autorisation et que vous ne suivez que les utilisateurs après leur connexion, vous pouvez fournir des IDs d'utilisateur. Vous pouvez également utiliser des identifiants uniques liés à l'appareil (Android et iOS ont des méthodes natives pour les obtenir). Ou, comme dans l'exemple ci-dessus, vous pouvez générer un UUID aléatoire lorsque l'utilisateur ouvre l'application pour la première fois et le stocker (nous avons utilisé AsyncStorage ci-dessus). Ensuite, utilisez cet UUID. Maintenant, l'algorithme de hachage ressemblera à ceci : hash(user_ip + UUID + salt). Dans cette approche, l'UUID restera inchangé sauf si l'utilisateur supprime et réinstalle l'application. Mais c'est suffisant. Si cela ne suffit pas, vous pouvez fournir votre propre identifiant unique comme mentionné ci-dessus. ID utilisateur ou identifiant d'appareil ou toute autre combinaison. Si vous souhaitez uniquement utiliser l'IP, passez simplement une chaîne vide'' comme UUID ou omettez-le complètement. Mais nous vous recommandons vivement d'utiliser un identifiant unique pour un meilleur suivi. UUID est optionnel mais recommandé.
bypassIpUniqueness
C'est un attribut optionnel. Les valeurs possibles sont "enable" ou "disable". Si vous voyez l'exemple de hachage ci-dessus avec metr_unique_identifier : hash(user_ip + metr_unique_identifier + salt), nous avons encore les informations IP dans le hachage. Ensuite, lorsque l'utilisateur, par exemple, est en Wifi puis passe au réseau mobile, alors l'IP changera. Alors que metr_unique_identifier est le même, en raison du changement d'IP, il peut être compté comme un autre décompte unique pour ce jour. Cette configuration supprime également l'IP du hachage. Si vous définissez cela sur "enable", nous n'utiliserons pas l'IP dans la fonction de hachage (comme par défaut) : hash(metr_unique_identifier + salt). Mais si vous passez disable, alors l'IP sera également utilisée dans la fonction de hachage : hash(user_ip + metr_unique_identifier + salt). Nous ne recommandons pas cela car casser le décompte unique avec IP n'a pas de sens dans la plupart des scénarios mobiles. Par conséquent, nous avons configuré ce paramètre par défaut sur enable. Dans la plupart des scénarios, ne passez pas cette option, laissez-la par défaut (enable).
tid (obligatoire)
Vous devez fournir votre TID (alias ID de suivi) à la méthode init. Vous pouvez l'obtenir depuis le tableau de bord de Metricalp. C'est obligatoire. Si vous ne le fournissez pas, vous recevrez une erreur. Vous pouvez trouver votre tid sur la page Embed & Share Tracker.
Plus de détails sur l'intégration
Eh bien, nous avons défini tous les attributs possibles. Mais il y a quelques détails dans le code ci-dessus. Expliquons-les maintenant.
Tout d'abord, nous avons effectué l'initialisation de l'application dans useEffect avec une fonction asynchrone. Nous avons défini un état pour montrer un texte de chargement à l'utilisateur pendant que nous effectuons l'initialisation. Vous pouvez afficher un écran de démarrage ou tout autre écran de chargement. Vous pouvez initialiser et configurer toute autre configuration pour votre application dans cette fonction, c'est une approche courante.
Dans la fonction init() (dans useEffect), nous vérifions si un UUID est présent dans AsyncStorage, s'il n'y en a pas, nous le générons. Les fonctions AsyncStorage et UUID proviennent d'Expo, mais vous pouvez utiliser n'importe quelle bibliothèque que vous souhaitez. Ensuite, nous générons un OS avec une chaîne de version. Ensuite, nous appelons Metricalp.init avec tous les attributs. Comme mentionné ci-dessus, Metricalp déclenchera automatiquement le premier événement screen_view avec le chemin (deuxième argument de la fonction init), mais vous pouvez le sauter en omettant le deuxième argument.
Metricalp.init({
platform: Platform.OS,
app: 'ExampleApp@1.0.0',
language: 'English-US',
os: osWithVersion,
uuid,
bypassIpUniqueness: true,
tid: 'mam48',
}) // Ici, nous avons omis le nom de l'écran pour désactiver le déclenchement automatique.Il existe deux scénarios d'événements système importants dans l'intégration de Metricalp React Native : vue de l'écran et quitter l'application. Nous suivons les écrans visités, les taux de rebond, etc. basés sur ces événements. Nous vous recommandons donc fortement de déclencher ces événements dans votre application en plus de tout événement personnalisé. Vous devez utiliser les méthodes fournies par la bibliothèque pour déclencher ces événements. Dans l'exemple ci-dessus, nous écoutons les changements d'état de l'application par React Native et déclenchons ces événements lorsque l'application est active ou en état inactif/arrière-plan. Nous utilisons les méthodes screenViewEvent et appLeaveEvent de la bibliothèque.
...
...
subscription = AppState.addEventListener('change', (nextAppState) => {
if (nextAppState === 'background' || nextAppState === 'inactive') {
Metricalp.appLeaveEvent();
} else if (nextAppState === 'active') {
Metricalp.screenViewEvent('MainScreen');
}
});
setAppInitialized(true); // Définir l'état pour afficher le contenu de l'app
}
init(); // Appeler la fonction init
return () => {
subscription?.remove(); // Supprimer l'abonnement au démontage pour éviter les fuites de mémoire
};
...
...La méthode Metricalp.screenViewEvent est fournie par la bibliothèque pour vous faciliter la tâche. Vous devez fournir le nom de l'écran actuel (chemin) à cette méthode. Vous pouvez également passer des données supplémentaires (attributs personnalisés) à ces méthodes en tant que deuxième argument :
Metricalp.screenViewEvent('MainScreen', { custom_prop1: 'Utilisateur non authentifié' });La méthode Metricalp.appLeaveEvent est également fournie par la bibliothèque pour vous faciliter la tâche. Vous pouvez passer des données supplémentaires (attributs personnalisés) à ces méthodes en tant que premier argument :
Metricalp.appLeaveEvent({ custom_prop1: 'Utilisateur non authentifié' });Ici, le thème est un alias pour un attribut personnalisé. Vous pouvez consulter Événements personnalisés & Attributs pour plus d'informations.
En gros, c'est tout. Vous avez intégré avec succès votre application React Native avec Metricalp. Une chose de plus, vous pouvez également créer des événements personnalisés pour obtenir des informations plus détaillées.
Événements Personnalisés
Il existe également une autre méthode de la bibliothèque pour les événements personnalisés : Metricalp.customEvent. Elle prend le type d'événement en premier argument et les attributs de données en second argument. Vous pouvez l'utiliser ainsi :
Metricalp.customEvent('click_purchase', {path: 'PricingScreen', custom_prop1: user.id, theme: 'dark'})Ici, nous avons passé les informations du chemin, nous avons également passé user.id comme attribut personnalisé. Nous avons passé un autre attribut personnalisé theme, mais cette fois nous avons utilisé l'alias. Vous pouvez consulter Événements personnalisés & Attributs pour plus d'informations. Maintenant, avec la puissance des événements personnalisés et des attributs, vous pouvez suivre et analyser tout événement pour obtenir des informations détaillées.