iSonic Analytics Enrichment for Salesforce

Plugin WordPress qui enrichit automatiquement les soumissions Gravity Forms avec les données Matomo avant envoi à Salesforce.

🎯 Objectif

Capturer le contexte web complet de chaque Lead pour :

• Améliorer le scoring (leads "chauds" = parcours long, pages stratégiques)
• Personnaliser l'approche commerciale (connaître l'intérêt réel)
• Mesurer le ROI des campagnes web

📊 Données Capturées (13 champs)

Parcours Web

• Temps passé : Durée totale de la session
• Page d'entrée : Première page visitée
• Parcours complet : Liste des pages consultées

Source & Campagne

• Source web : Google, Facebook, Direct, etc.
• Medium : cpc, email, social, etc.
• Mot-clé : Mot-clé de recherche

Formulaire

• Page formulaire : URL exacte du formulaire
• Type formulaire : Demo, Support, Formation, etc.
• Nom formulaire : Nom Gravity Forms

Engagement

• Nombre de visites : Visites avant soumission
• Première visite : Date de découverte du site
• Pages consultées : Nombre total de pages vues

🚀 Installation

Installation complète détaillée : Voir INSTALLATION.md

Installation rapide :

1. Uploader le plugin dans /wp-content/plugins/
2. Activer via WordPress Admin
3. Créer Connected App Salesforce (voir guide)
4. Configurer dans Réglages → iSonic Analytics
5. Tester : /wp-content/plugins/isonic-analytics-plugin/test-plugin.php

⚙️ Configuration

Un menu dédié iSonic Analytics apparaît désormais dans la barre d’admin WordPress :

• iSonic Analytics → Configuration : paramètres Matomo + Salesforce.
• iSonic Analytics → Logs : visionneuse des dernières entrées [iSonic Analytics ...] issues du fichier WP_DEBUG_LOG (par défaut wp-content/debug.log).
• Section Test de connexion : boutons pour vérifier l’auth Salesforce et créer un Lead de test (avec campagne auto) en un clic.

Matomo

🎉 Si vous utilisez le plugin Matomo WordPress :

• ✅ Détection automatique - Aucune configuration requise !
• Juste renseigner le Site ID (généralement 1)

Si vous utilisez un Matomo externe :

• URL : https://matomo.isonic.fr
• Site ID : 1
• Auth Token : [Générer dans Matomo → Personal → Security]

Salesforce (single org)

• Une seule org Salesforce configurée.
• Connected App Consumer Key & Secret (obligatoires).
• Mode d’authentification : Client Credentials, Authorization Code (bouton « Connecter Salesforce »), ou Username + Password + Security Token.

📋 Campaigns Salesforce

Formulaire	Campaign Salesforce	ID
Inscription Isonic	Contenu pédagogique	701Jv00000oEgv7IAC
Autres formulaires	Site web isonic.fr	701Jv00000oEi1EIAS

🏗 Architecture et flux

Deux flux envoient les données vers Salesforce (endpoint unique POST /services/apexrest/MatomoInbound) :

1. Soumission (immédiat) : à chaque gform_after_submission, envoi de lead, campaignId, session, visits (données Matomo exhaustives), meta (mode=submission). Si Matomo indisponible : envoi quand même avec visits=[] et meta.matomoStatus=unavailable.
2. Sync périodique (toutes les 5 min) : cron WordPress envoie les nouvelles visites depuis le dernier watermark ; payload visits + meta (mode=periodic_5min), sans lead.

Documentation détaillée : docs/ARCHITECTURE_2_FLUX.md (schéma payload, idempotence, retry, variables de config).

• Visitor ID : Récupéré côté serveur via le cookie Matomo _pk_id.{site_id}. Aucun JavaScript front requis pour le tracking.
• Matomo : Si le plugin Matomo WordPress est détecté, l’API PHP native est utilisée ; sinon fallback sur l’API HTTP (URL + Auth Token).
• Retry : Backoff progressif sur erreurs transitoires (timeout, 429, 5xx). Aucun secret loggé.

🔧 Développement

Structure

isonic-analytics-plugin/
├── isonic-analytics.php (Main plugin)
├── includes/
│   ├── class-logger.php
│   ├── class-matomo-api.php
│   ├── class-matomo-payload-builder.php
│   ├── class-matomo-sync-cron.php
│   ├── class-salesforce-api.php
│   ├── class-campaign-mapper.php
│   └── class-form-enricher.php
├── admin/
│   └── settings-page.php
├── tests/
│   ├── bootstrap.php
│   ├── Test_Matomo_Payload_Builder.php
│   └── README.md
└── docs/
    ├── ARCHITECTURE_2_FLUX.md
    └── (Documentation technique)

Hooks

Le plugin utilise gform_after_submission pour intercepter les soumissions Gravity Forms.

Logs

Activez WP_DEBUG et WP_DEBUG_LOG dans wp-config.php :

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );

Logs dans : fichier défini par WP_DEBUG_LOG (par défaut wp-content/debug.log)

📝 TODO

v1.0 (Fait ✅)

• [x] OAuth2 complet pour Salesforce (Username-Password flow)
• [x] Page settings admin complète
• [x] Boutons "Test Connection" Matomo + Salesforce
• [x] Script de test et validation

v1.1 (À venir)

• [ ] Queue système (fallback si SF down)
• [ ] Dashboard WordPress avec métriques
• [ ] Tests unitaires

🔗 Documentation

Voir dossier docs/ pour documentation complète :

• ARCHITECTURE_2_FLUX.md : Deux flux (soumission + cron 5 min), schéma payload, erreurs/fallback, config
• SPEC_TECHNIQUE.md : Spécifications techniques
• SPEC_CHAMPS_ANALYTICS.md : Détail des 13 champs
• SPEC_MAPPING_CAMPAGNE.md : Mapping formulaires → campaigns

Tests : ./vendor/bin/phpunit (voir tests/README.md).

⚠️ Prérequis

• WordPress 6.0+
• PHP 8.0+
• Gravity Forms 2.5+
• Matomo installé et configuré
• Salesforce avec champs custom déployés

📄 Licence

GPL-2.0+

👤 Auteur

iSonic - https://isonic.fr