Trackily Docs

Réconciliation Meta Ads (Insights API)

Synchronise ce que Meta rapporte (dépense, impressions, clics, conversions) avec ce que Trackily traque (clics atterris, leads, conversions, revenu), par campagne — pour obtenir le profit et le ROI réels : Dépense Meta × Revenu Trackily.

Modal de réconciliation Meta Ads

⚠️ Les conversions Meta ≠ les conversions Trackily. Meta applique une fenêtre d'attribution (7 j clic / 1 j vue par défaut) et modélise statistiquement une partie des conversions depuis iOS 14/ATT. L'axe fiable de réconciliation est donc Dépense Meta (ce que tu paies) × Revenu Trackily (ce que tu encaisses). Les colonnes de conversions sont informatives, pas un rapprochement au conversion près.

1. Prérequis : un token longue durée (System User)

L'API Insights de Meta exige un token avec la permission ads_read. Un token utilisateur classique expire (~60 jours) → la synchro casserait silencieusement. Utilise un System User token (n'expire pas) :

  1. Ouvre Meta Business Settings → https://business.facebook.com/settings
  2. Utilisateurs → Utilisateurs système → Ajouter → crée un system user (rôle Admin ou Employé).
  3. Attribuer des actifs → sélectionne ton compte publicitaire → active au minimum Voir les performances (lecture).
  4. Générer un token → choisis l'app → coche la permission ads_read (et business_management si demandé) → Générer.
  5. Copie le token (il ne sera plus affiché ensuite) et garde-le secret.

Tu auras aussi besoin de l'ID de compte publicitaire, de la forme act_1234567890 (Business Settings → Comptes publicitaires, ou en haut du Gestionnaire de publicités).

2. Configurer la source Meta dans Trackily

Dans Sources de trafic :

  1. Crée (ou édite) une source dont le nom ou le slug contient meta ou facebook (c'est ce qui active le mode Insights).
  2. api_key = ton System User token.
  3. Dans les macros (JSON), ajoute : {"ad_account_id": "act_1234567890"}.

Le token n'est jamais affiché en clair côté visiteur et n'est utilisé que pour les appels serveur → Meta.

3. Mapper les campagnes (obligatoire pour croiser le revenu)

Le rapprochement se fait via le champ external_id de la campagne Trackily, qui doit valoir l'ID de la campagne Meta.

  • Trouver l'ID de campagne Meta : dans le Gestionnaire de publicités, ajoute la colonne Identifiant de campagne, ou lis-le dans l'URL en sélectionnant la campagne (...selected_campaign_ids=23851...).
  • Renseigner dans Trackily : édite la campagne → champ External ID → colle l'ID Meta.

Une campagne Meta non mappée apparaît quand même dans le tableau (avec un ⚠️) mais sans le revenu Trackily croisé — donc sans profit/ROI fiable.

4. Synchroniser et lire la réconciliation

Sources de trafic → bouton « 📊 Réconciliation Meta » :

  1. Choisis la source Meta et la période (Du / Au).
  2. Clique ⟳ Synchroniser → Trackily appelle l'API Insights au niveau campagne (un point par campagne et par jour) et stocke la dépense.
  3. Clique Afficher (ou re-synchronise) pour voir le tableau.

Colonnes du tableau :

Colonne Source Sens
Campagne mapping nom Trackily (ou nom Meta + ⚠️ si non mappée)
Dépense Meta Meta ce que tu as payé
Clics Meta Meta link clicks rapportés par Meta
Clics Trackily Trackily clics réellement atterris et trackés
Conv Meta Meta conversions rapportées (informatif)
Conv Trackily Trackily conversions trackées (source de vérité)
Revenu Trackily Trackily revenu USD (statuts non exclus)
Profit calcul Revenu Trackily − Dépense Meta
ROI calcul Profit ÷ Dépense Meta

Les KPIs en haut agrègent toute la période : Dépense · Revenu · Profit · ROI.

5. Synchro automatique quotidienne

Active « Sync auto quotidien » dans le modal pour que Trackily re-synchronise cette source chaque jour. Le cron re-tire les 7 derniers jours à chaque passage, car Meta révise l'attribution après coup (une conversion peut être rattachée à un jour antérieur plusieurs jours plus tard).

La ligne d'état affiche la dernière synchro et, le cas échéant, la dernière erreur (ex. token expiré) — utile pour repérer un token à renouveler.

6. Pourquoi un écart Meta ↔ Trackily est normal

  • Attribution : Meta s'auto-attribue les conversions selon sa fenêtre ; Trackily compte ce qui a réellement traversé le tracker.
  • Modélisation : Meta estime une part des conversions (post-ATT).
  • Clics : « link clicks » Meta ≠ clics atterris (pré-chargements, abandons, bots filtrés côté Trackily).

➡️ Ne cherche pas l'égalité au conversion près. Pilote sur Profit / ROI (dépense réelle vs revenu réel).

7. Dépannage

Symptôme Cause probable Solution
« Token Meta ou ad_account_id manquant » api_key vide ou macros.ad_account_id absent renseigne les deux (§2)
Erreur « Meta API: … (190) » dans l'état token expiré/révoqué régénère un System User token (§1)
Dépense présente mais revenu = 0 campagne non mappée (⚠️) renseigne external_id (§3)
Tableau vide aucune synchro sur la période clique Synchroniser puis Afficher
Chiffres qui « bougent » après coup restatement d'attribution Meta normal — le sync auto re-tire 7 j

Notes techniques

  • Les données sont stockées dans ad_spend_daily (snapshot quotidien par campagne, upsert idempotent) — totalement isolé des calculs de revenu/ profit existants (Solution B). La synchro ne modifie jamais tes clics ni tes conversions.
  • Les alias de conversions Meta (lead vs offsite_conversion.fb_pixel_lead…) sont dédupliqués (max par famille, somme entre familles) pour éviter le double comptage.
  • Endpoints : POST /admin/api/sources/:id/sync-insights, GET /admin/api/sources/:id/reconciliation, POST /admin/api/sources/:id/ads-auto-sync.