Intégration avec Android
Android est la plateforme mobile la plus utilisée dans le monde. Nous sommes ravis d'avoir une bibliothèque d'intégration officielle pour Android. Si vous recherchez React Native, veuillez consulter React Native ou si vous recherchez iOS, veuillez consulter iOS documentation. Pour d'autres intégrations mobiles, veuillez consulter intégration mobile. Si vous êtes sur Android, vous êtes au bon endroit ! Commençons !
Installation
Installation avec Gradle
Étape 1. Ajoutez le dépôt JitPack à votre fichier de construction
Ajoutez `maven { url 'https://jitpack.io' }` dans votre fichier build.gradle racine à la fin de repositories :
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
mavenCentral()
maven { url 'https://jitpack.io' }
}
}
Étape 2. Ajoutez la dépendance à vos dépendances d'application :
dependencies {
implementation 'com.github.metricalp:android:1.5'
}
Installation avec Maven
Étape 1. Ajoutez le dépôt JitPack à votre fichier de construction
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
Étape 2. Ajoutez la dépendance à vos dépendances d'application :
<dependency>
<groupId>com.github.metricalp</groupId>
<artifactId>android</artifactId>
<version>1.5</version>
</dependency>
Utilisation
Nous avons essayé de rendre l'intégration flexible et fluide pour maintenir la meilleure expérience développeur. Ici, nous partagerons un exemple complet de MainActivity.kt pour vous montrer comment vous pouvez intégrer Metricalp dans votre application Android. Nous décrirons le code étape par étape comme détaillé ci-dessous.
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 {
// Un conteneur de surface utilisant la couleur 'background' du thème
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") }
}
Nous savons que c'est une application très basique, mais cela vous aidera à comprendre les fondamentaux, croyez-nous. Tout d'abord, nous importons la bibliothèque import com.metricalp.android.Metricalp que nous utilisons pour appeler les méthodes.
La première méthode que vous devez appeler est Metricalp.init et le plus important est de l'intégrer correctement. Nous allons initialiser Metricalp pour collecter des événements. Il est important de faire cela dans le fichier d'entrée (MainActivity). Metricalp.init prend attributs (HashMap<String,String>), l'écran initial path (pour le premier screen_view autoactivé comme optionnel). Si vous fournissez l'écran initial comme null, l'événement screen_view autoactivé sera omis. Nous pouvons également passer des attributs d'événement pour cet écran initial, comme un autre argument optionnel. Sinon, passez simplement null. Expliquons :
Propriétés de l'argument Attributes de Metricalp.init()
app
Vous devez fournir le nom et la version de votre application. Il est important de fournir la version pour la suivre dans le tableau de bord. Vous pouvez le fournir au format AppName@Version. Par exemple, ExampleApp@1.0.0.
metr_user_language (optionnel)
Cette propriété est optionnelle. Si vous souhaitez la passer, vous devez fournir le langage et le code du pays pour votre application. Vous pouvez le fournir au format Language (nom complet)-Country(ISO Code), comme English-US 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.
metr_unique_identifier (requis)
Nous devons expliquer cette propriété metr_unique_identifier. Normalement dans le suivi web, bien que Metricalp n'utilise pas de cookies comme nous l'avons mentionné à plusieurs endroits, nous identifions les utilisateurs avec leurs adresses IP en hash unidirectionnel. La formule est quelque chose comme : hash(user_ip + user_agent + salt). Ici ip + user_agent est presque unique pour chaque utilisateur. Mais dans les applications mobiles, les chaînes d'agent utilisateur sont incohérentes et peu fiables. Par conséquent, nous avons 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'authentification et que vous ne suivez que les utilisateurs après qu'ils se soient connectés, vous pouvez fournir des IDs utilisateur. Ou vous pouvez utiliser de vrais identifiants uniques liés au dispositif (Android et iOS ont quelques méthodes natives pour l'obtenir). Ou, vous pouvez générer un UUID aléatoire lorsque l'utilisateur ouvre l'application pour la première fois et le stocker dans le stockage local. Ensuite, utilisez-le comme metr_unique_identifier. Maintenant, l'algorithme de hash sera comme hash(user_ip + metr_unique_identifier + salt). Dans cette approche, le metr_unique_identifier ne changera pas à moins que l'utilisateur ne supprime et réinstalle l'application. Mais c'est suffisant. Si cela ne vous suffit pas, vous pouvez fournir votre propre identifiant unique comme nous l'avons mentionné précédemment. ID utilisateur ou identifiant du dispositif ou toute autre combinaison.
Dans l'exemple ci-dessus, nous avons généré un UUID aléatoire, l'avons stocké dans SharedPreferences (stockage permanent) et l'avons utilisé comme metr_unique_identifier. Nous vous suggérons d'utiliser cette approche. Mais vous pouvez utiliser n'importe quel identifiant unique pour votre application. Mais gardez à l'esprit, il doit être unique pour chaque utilisateur et ne doit pas changer à moins que l'utilisateur ne supprime et réinstalle l'application.
metr_bypass_ip
C'est une propriété optionnelle. Les valeurs possibles sont "enable" ou "disable". Si vous voyez l'exemple final de hash avec metr_unique_identifier : hash(user_ip + metr_unique_identifier + salt), nous avons encore des informations IP dans le hash. Alors, lorsque l'utilisateur, par exemple, passe de Wifi à un réseau mobile, l'IP changera. Bien que le metr_unique_identifier soit le même, en raison du changement d'IP, il peut être compté comme un autre unique pour ce jour. Cette configuration supprime également l'IP du hash. Si vous le définissez sur "enable", alors nous n'utiliserons pas IP dans la fonction de hash (par défaut) : hash(metr_unique_identifier + salt). Mais si vous passez "disable", alors l'IP sera également utilisée dans la fonction de hash : hash(user_ip + metr_unique_identifier + salt). Nous ne suggérons pas cela car casser le comptage unique avec IP n'a pas de sens dans la plupart des scénarios mobiles. Donc, nous avons cette configuration activée par défaut. Par conséquent, dans la plupart des scénarios, ne passez tout simplement pas cette option, laissez-la par défaut (activée).
tid (requis)
Vous devez fournir votre TID (également connu sous le nom de Tracking ID) à la méthode d'initialisation. Vous pouvez l'obtenir depuis le panneau de contrôle de Metricalp. C'est obligatoire. Si vous ne le fournissez pas, vous recevrez une erreur. Vous pouvez trouver votre TID sur la page de Embed & Share Tracker.
Il y a un événement système important dans Metricalp screen_view. Nous suivons les écrans visités, les taux de rebond, etc., en nous basant sur cet événement. Par conséquent, nous vous recommandons vivement de déclencher cet événement dans votre application en plus de tout événement personnalisé. Dans votre logique de navigation, à chaque changement d'écran par l'utilisateur, vous devriez déclencher un événement screen_view. Dans l'exemple ci-dessus, nous écoutons onStart pour Android et déclenchons cet événement. Vous pouvez le déclencher ailleurs, l'emplacement n'est pas important, mais nous conseillons de déclencher cet événement quelque part pour un meilleur suivi.
...
...
public override fun onStart() {
super.onStart()
Metricalp.screenViewEvent("MainScreen", null, null);
}
...
...La méthode Metricalp.screenViewEvent fournie par la bibliothèque facilite cela. Vous devez fournir le nom de l'écran actuel (path) à cette méthode. Vous pouvez également passer des données supplémentaires (props personnalisées) à cette méthode comme deuxième argument (encore HashMap<String,String>). Le troisième argument est un autre HashMap si vous souhaitez remplacer les propriétés initiales (configurations) pour l'événement actuel, sinon, passez simplement null.
Metricalp.screenViewEvent("MainScreen", hashMapOf<String, String>("custom_prop1" to "Utilisateur non authentifié"), null);ou
Metricalp.screenViewEvent("MainScreen", hashMapOf<String, String>("theme" to "Thème Sombre"), null);Ici, le thème est un alias de props personnalisées. Vous pouvez consulter la documentation des Événements et Props Personnalisés pour obtenir des informations détaillées.
En gros, c'est tout. Vous avez maintenant intégré avec succès votre application Android avec Metricalp. Une chose de plus est que vous pouvez également créer des événements personnalisés pour obtenir des informations plus approfondies.
Une autre chose importante est de générer les événements nécessaires à la sortie de l'application. Metricalp fournit également une méthode personnalisée pour cela : Metricalp.appLeaveEvent(). Vous pouvez voir que nous déclenchons cet événement appLeave dans le gestionnaire onStop. Cela nous aide à capturer la durée des vues d'écran des utilisateurs. Vous pouvez également passer des données supplémentaires (props personnalisées) à cette méthode comme premier argument (encore HashMap<String,String>). Le deuxième argument est un autre HashMap si vous souhaitez remplacer les propriétés initiales (configurations) pour l'événement actuel, sinon, passez simplement null.
public override fun onStop() {
super.onStop()
Metricalp.appLeaveEvent(null, null);
}Événements Personnalisés
Il y a aussi un autre méthode dans la bibliothèque pour les événements personnalisés : Metricalp.customEvent. Elle prend le type d'événement comme premier argument et les attributs de données comme deuxième argument. Le troisième argument est un autre HashMap si vous souhaitez remplacer les propriétés initiales (configurations) pour l'événement actuel, sinon, passez simplement null. Vous pouvez l'appeler dans n'importe quel bouton ou clic, etc.
Metricalp.customEvent("button_click", hashMapOf<String, String>("path" to "HomepageScreen", "custom_prop1" to "top_button", "theme" to "dark"), null )Vous pouvez également passer des propriétés supplémentaires à cet événement comme nous l'avons montré précédemment.
Et c'est tout. Vous avez maintenant toutes les informations pour intégrer Metricalp dans votre application Android. Nous sommes impatients de vous voir tirer parti de la puissance de l'analyse dans votre application !