Flutter

Flutter

SDK Flutter Eulerian — Documentation d’intégration

Cette documentation explique comment installer, initialiser et utiliser le SDK Flutter Eulerian pour tracker les événements applicatifs sur iOS, Android et Web.


Prérequis

Élément
Version / Plateforme
Flutter
>= 3.3.0
Dart SDK
>= 2.18.0 < 4.0.0
Plateformes supportées
iOS, Android, Web


Installation

Ajoutez le package à votre application avec la commande suivante :
flutter pub add eanalytics

Vous pouvez également le déclarer manuellement dans votre fichier pubspec.yaml :
dependencies:
  eanalytics: ^1.1.1

Puis importez le SDK dans votre code Dart :
import 'package:eanalytics/eanalytics.dart';



Démarrage rapide

1. Initialiser le SDK

Initialisez le SDK une seule fois, avant toute requête de tracking.
L’appel à Eulerian.init doit être effectué au niveau racine de votre application, par exemple dans le initState de votre widget principal.
await Eulerian.init('your.tracking-domain.com');

Lors de l’initialisation, le SDK tente également de rejouer les requêtes de tracking échouées précédemment et stockées localement.

Paramètres disponibles

Paramètre
Type
Défaut
Description
domain
String
—
Domaine de tracking Eulerian dédié. Il ne doit pas contenir .eulerian.com.
requestTrackingAuthorization
bool
false
iOS uniquement. Affiche la boîte de dialogue App Tracking Transparency afin de collecter l’IDFA.
enableLogger
bool
true
Active ou désactive les logs du SDK dans la console.


2. Tracker des événements

Utilisez Eulerian.track depuis n’importe quel endroit de votre application en lui passant une liste de propriétés trackables.
Eulerian.track([
  EAProducts(path: '/add/products')
    ..addProduct(Product(ref: 'p1', name: 'Product 1', group: 'test_group'))
]);

Les événements standards sont envoyés en lot via une requête POST vers le collecteur Eulerian.
En cas d’échec de la requête, les payloads sont stockés localement puis rejoués automatiquement :
  • au prochain appel à Eulerian.track ;
  • ou au prochain lancement de l’application, après Eulerian.init.


Référence de l’API

Eulerian

Eulerian est le singleton principal du SDK.
Méthode
Description
Eulerian.init(domain, {requestTrackingAuthorization, enableLogger})
Initialise le SDK et rejoue les payloads stockés localement.
Eulerian.track(List<EAProperty> properties)
Tracke une liste de propriétés. Les événements EATpView et EATpClick sont envoyés via GET ; tous les autres événements sont regroupés dans un unique POST.
Eulerian.uid()
Retourne l’identifiant de l’appareil utilisé comme euidl : Android ID sur Android, identifierForVendor sur iOS. Retourne une chaîne vide si le SDK n’est pas initialisé.


Événements trackables

EAProperty

EAProperty est la classe de base de tout événement trackable.
Elle peut également être utilisée directement pour tracker une simple vue de page.
Le constructeur requiert un path, qui correspond au chemin de la page. Si le / initial est absent, il est ajouté automatiquement.
Eulerian.track([
  EAProperty(path: '/home')
    ..setEmail('johndoe@example.com')
    ..setUID('user-42')
    ..setPageGroup('homepage')
]);


Setters disponibles

Ces setters sont hérités par tous les modèles d’événements.
Méthode
Clé du payload
Description
setPath(String path)
path
Chemin de la page de l’événement.
setLocation({latitude, longitude})
ea-lat, ea-lon
Coordonnées géographiques.
setNewCustomer(bool isNew)
newcustomer
Marque le visiteur comme nouveau client : 1 ou 0.
setStandalone()
ereplay-notag
Marque le hit comme un appel autonome, sans vue de page comptabilisée.
setEmail(String email)
email
Adresse e-mail du visiteur.
setLabel(String label)
pagelabel
Libellé de la page. Les valeurs séparées par des virgules sont autorisées.
setUID(String uid)
uid
Identifiant visiteur fourni par votre application.
setProfile(String profile)
profile
Profil du visiteur.
setPageGroup(String group)
pagegroup
Groupe de pages.
setAction(Action action)
action
Attache une action à la page.
setProperty(SiteCentric property)
property
Propriétés site-centric.
setCFlag(SiteCentric cFlag)
cflag
Indicateurs de conversion site-centric.
setCustomParam(String key, String value)
<key>
Ajoute une paire clé / valeur personnalisée.


Modèles d’événements

Tous les modèles ci-dessous étendent EAProperty.
Les setters de EAProperty sont donc disponibles sur chacun d’eux.


EAProducts — Affichage de produits

Tracke l’affichage d’un ou plusieurs produits.
Eulerian.track([
  EAProducts(path: '/product/page')
    ..addProduct(Product(ref: 'p1', name: 'Product 1', group: 'shoes'))
    ..addProduct(Product(ref: 'p2', name: 'Product 2', group: 'shoes')),
]);

Méthode
Description
addProduct(Product product)
Ajoute un produit à la liste products.


EACart — Panier d’achat

Tracke le contenu du panier du visiteur.
L’indicateur scart est positionné automatiquement.
Eulerian.track([
  EACart(path: '/cart')
    ..setCartCumul(true)
    ..addProduct(product: Product(ref: 'p1'), amount: 19.99, quantity: 2),
]);

Méthode
Description
setCartCumul(bool cumul)
Si true, le panier est cumulatif avec scartcumul.
addProduct({product, amount, quantity})
Ajoute un produit au panier. amount et quantity sont appliqués au produit s’ils ne sont pas déjà définis.


EAEstimate — Devis ou estimation

Tracke un devis avant-vente.
L’indicateur estimate est positionné automatiquement.
Eulerian.track([
  EAEstimate(path: '/estimate', ref: 'EST-001')
    ..setAmount(149.90)
    ..setCurrency('EUR')
    ..setType('quote')
    ..setPayment('card')
    ..addProduct(product: Product(ref: 'p1'), amount: 149.90, quantity: 1),
]);

Méthode
Clé du payload
Description
setAmount(double amount)
amount
Montant total.
setCurrency(String currency)
currency
Code de la devise.
setType(String type)
type
Type de devis.
setPayment(String payment)
payment
Moyen de paiement.
addProduct({product, amount, quantity})
products
Ajoute un produit au devis.


EAOrder — Achat confirmé

Tracke une commande confirmée.
EAOrder étend EAEstimate, tous les setters de EAEstimate sont donc disponibles.
Le constructeur permet de relier la commande à un devis antérieur via estimateRef.
Eulerian.track([
  EAOrder(path: '/order/confirmation', estimateRef: 'EST-001')
    ..setAmount(149.90)
    ..setCurrency('EUR')
    ..setPayment('card')
    ..addProduct(product: Product(ref: 'p1'), amount: 149.90, quantity: 1),
]);

Méthode
Clé du payload
Description
setEstimateRef(String ref)
estimateref
Référence du devis d’origine.


EASearch — Recherche interne

Tracke une requête effectuée dans le moteur de recherche interne de l’application.
Eulerian.track([
  EASearch(
    path: '/search',
    search: Search(name: 'shoes', results: 42),
  ),
]);



EAActions — Actions utilisateur

Tracke une ou plusieurs actions utilisateur, comme des clics ou interactions.
À combiner avec setStandalone() lorsque les hits ne contiennent que des actions et ne doivent pas être comptabilisés comme des vues de page.
Eulerian.track([
  EAActions(path: '')
    ..setStandalone()
    ..addAction(Action(name: 'button1', mode: 'in'))
    ..addAction(Action(name: 'newsletter', label: 'footer')
      ..setParams(Params()..addParam('input', 'test'))),
]);

Méthode
Description
addAction(Action action)
Ajoute une action à la liste actions.


Classes utilitaires

Les classes suivantes sont utilisées comme briques de base par les différents modèles d’événements.


Product

Représente un produit.
Product(
  ref: 'p1',
  name: 'Product 1',
  group: 'shoes',
  parameters: Params()..addParam('color', 'red'),
)
  ..setAmount(19.99)
  ..setQuantity(2);


Champs principaux

Champ
Description
ref
Référence produit. Ce champ est requis.
name
Nom du produit.
group
Groupe ou catégorie produit.
parameters
Paramètres personnalisés associés au produit.


Action

Représente une action utilisateur.
Action(name: 'button1', mode: 'in', label: 'lbl1,lbl2', ref: 'ref1')
  ..setParams(Params()..addParam('input', 'test'));

Champ
Description
name
Nom de l’action. Ce champ est requis.
mode
Mode de l’action. Optionnel.
label
Libellé de l’action. Optionnel.
ref
Référence associée à l’action. Optionnel.


Params

Permet d’ajouter des paramètres clé / valeur arbitraires aux produits, actions et recherches.
Params.fromEntries([
  MapEntry('foo', 'bar'),
  MapEntry('baz', [1, 2, 3]),
]);

Ou avec addParam :
Params()..addParam('foo', 'bar');



Search

Décrit une recherche interne utilisée par EASearch.
Search(
  name: 'shoes',
  results: 42,
  parameters: Params()..addParam('foo', 'bar'),
);



SiteCentric

Permet de renseigner des clés / valeurs site-centric pour setProperty et setCFlag.
Chaque valeur est une liste de chaînes.
SiteCentric()..addParam('prop', ['foo', 'baz']);



Tracking merchandising

Le SDK fournit un flux de tracking merchandising dédié pour les impressions et clics sur les vitrines produits, listes de recommandations et surfaces similaires.
Deux modèles sont disponibles :
Modèle
Usage
Envoi
EATpView
Impression merchandising
GET /tpview/
EATpClick
Clic merchandising
GET /tpclick/
Contrairement aux autres événements, envoyés en POST au collecteur standard, les événements merchandising sont envoyés via des requêtes GET sur des chemins dédiés.
Si une requête échoue, le payload est stocké localement puis rejoué avec le prochain lot POST en attente.


Format des requêtes merchandising

Impression

https://<domain>/tpview/<siteName>/<campaignName>/<placement>/<siteName>/generic/<random>
       ?evprdr0=<ref>&evprdpos0=<position>&...&url=<encoded page url>&<global context>


Clic

https://<domain>/tpclick/<siteName>/<campaignName>/<placement>/<siteName>/generic/<random>
       ?ecprdr=<ref>&ecpos=<position>&ecnbr=<total>&eurl=<encoded landing url>&<global context>



Contexte global ajouté automatiquement

Le SDK ajoute automatiquement les paramètres de contexte global à chaque requête merchandising.
Aucun code supplémentaire n’est nécessaire.
Les paramètres ajoutés sont les mêmes que ceux utilisés lors des appels au collecteur :
  • euidl
  • ea-appname
  • eos
  • ehw
  • identifiants publicitaires :
  • ea-android-adid
  • ea-ios-idfa
  • ea-ios-idfv
  • qualification de l’appareil via edev
Valeurs possibles pour edev :
  • AppNativeIOSphone
  • AppNativeIOStablet
  • AppNativeAndroidphone
  • AppNativeAndroidtablet
Ces valeurs permettent de qualifier le trafic comme provenant d’une application native.
L’identifiant visiteur uid est également ajouté lorsqu’il est défini sur l’événement via setUID().


Descripteurs communs

EATpView et EATpClick exposent les mêmes descripteurs de campagne :
Propriété
Description
siteName
Nom du site.
campaignName
Nom de la campagne.
placement
Emplacement de diffusion.
url
URL associée à l’événement.
La signification de url diffère selon le type d’événement :
Modèle
Signification de url
Paramètre envoyé
EATpView
URL de la page courante
url
EATpClick
URL de destination du produit cliqué
eurl


EATpView — Impression merchandising

final view = EATpView(path: 'homepage')
  ..siteName = 'my-site'
  ..campaignName = 'summer_sale'
  ..placement = 'banner_top'
  ..url = 'https://example.com/home'
  ..addProduct('PROD_001', position: 0)
  ..addProduct('PROD_002', position: 1);

Eulerian.track([view]);

Méthode
Description
addProduct(String ref, {int? position})
Ajoute un produit affiché, avec sa position optionnelle dans le bloc.
setProducts(List<List<dynamic>> products)
Remplace l’intégralité de la liste de produits. Les entrées peuvent être [ref] ou [ref, position].


EATpClick — Clic merchandising

final click = EATpClick(path: 'homepage')
  ..siteName = 'my-site'
  ..campaignName = 'summer_sale'
  ..placement = 'banner_top'
  ..url = 'https://example.com/home'
  ..setProduct('PROD_001', 2);

Eulerian.track([click]);

Méthode
Description
setProduct(String ref, int position, {int? totalProducts})
Définit le produit cliqué, sa position et, en option, le nombre total de produits dans le bloc.
setProductMap(Map<String, dynamic> product)
Définit le produit à partir d’une map brute avec les clés ref, position et totalProducts.


Propriétés globales

Le SDK attache automatiquement les propriétés suivantes à chaque payload, selon la plateforme.
Nom de la propriété
EAPropertyKey
iOS
Android
Web
ehw
EAPropertyKey.EHW
✔
✔
✔
eos
EAPropertyKey.EOS
✔
✔
✔
euidl
EAPropertyKey.EUIDL
✔
✔
✘
ea-appname
EAPropertyKey.APPNAME
✔
✔
✔
ea-appversion
EAPropertyKey.APP_VERSION
✔
✔
✔
url
EAPropertyKey.URL
✔
✔
✔
ea-ios-idfv
EAPropertyKey.IOS_IDFV
✔
✘
✘
ea-ios-idfa
EAPropertyKey.IOS_ADID
✔
✘
✘
ea-android-adid
EAPropertyKey.ANDROID_ADID
✘
✔
✘
ea-android-referrer
EAPropertyKey.INSTALL_REFERRER
✘
✔
✘
ereplay-time
EAPropertyKey.EPOCH
✔
✔
✔
ea-flutter-sdk-version
EAPropertyKey.SDK_VERSION
✔
✔
✔
Notes :
  • La propriété url correspond :
  • à l’identifiant de bundle sur iOS ;
  • au nom du package sur Android ;
  • au chemin de l’URL courante sur le Web.
  • La propriété ea-ios-idfa nécessite l’option requestTrackingAuthorization lors de l’initialisation du SDK sur iOS.


Configuration iOS

Si vous souhaitez utiliser l’identifiant publicitaire IDFA, vous devez mettre à jour le fichier Info.plist.
Le fichier se trouve généralement dans le répertoire suivant :
ios/Runner/Info.plist

Ajoutez la clé NSUserTrackingUsageDescription avec un message décrivant votre usage :
<key>NSUserTrackingUsageDescription</key>
<string>This identifier will be used to deliver personalized analytics.</string>

Si votre application appelle l’API App Tracking Transparency, cette chaîne est obligatoire. Elle sera affichée dans l’alerte système de permission.
Passez ensuite l’option requestTrackingAuthorization lors de l’initialisation du SDK :
@override
void initState() {
  Eulerian.init('your.tracking-domain.com', requestTrackingAuthorization: true);
  super.initState();
}



Reprise hors ligne

Les requêtes de tracking échouées sont stockées localement via shared_preferences.
Cela concerne notamment :
  • les erreurs réseau ;
  • les réponses HTTP non 2xx.
Les payloads stockés sont automatiquement rejoués :
  • au prochain appel à Eulerian.track, fusionnés avec le nouveau lot ;
  • ou au prochain lancement de l’application, une fois Eulerian.init terminé.


Application d’exemple

Une application d’exemple complète est disponible pour iOS, Android et Web dans le répertoire suivant :
example/