Généré le 14/10/2026 22:43

⚡ SKILL : Analytics Natif — Meta Graph API + Shopify ShopifyQL

Date de création : 2026-06-06
Auteur : Claude Code (Analyse architecturale sur demande de Raphaël)
Statut : VALIDÉ — Remplace la méthode CDP+Vision pour les extractions analytiques


🎯 Objectif

Extraire les données d'analyse Meta Ads ET Shopify Analytics en mode 100% backend (aucun navigateur, aucune capture d'écran) via des APIs natives. Vitesse : 5-10 secondes au lieu de 2-3 minutes.


⚠️ Contexte : Pourquoi changer ?

Ancienne Méthode Nouvelle Méthode
CDP Port 9222 + DOM scraping Meta Meta Marketing API (Graph v20)
CDP Port 9222 + Screenshot + Vision IA Shopify ShopifyQL via GraphQL Admin
2-3 minutes, fragile aux updates UI 5-10 secondes, stable
Chrome obligatoirement ouvert Aucun navigateur requis

La méthode CDP+Vision reste valide comme FALLBACK si les tokens API ne sont pas configurés.


🔑 PRÉ-REQUIS (Configuration une fois)

Token Meta (longue durée)

  1. Aller sur https://developers.facebook.com/tools/explorer
  2. Générer un token avec scopes : ads_read, ads_management
  3. Échanger contre un token 60 jours :
GET https://graph.facebook.com/oauth/access_token
  ?grant_type=fb_exchange_token
  &client_id={APP_ID}
  &client_secret={APP_SECRET}
  &fb_exchange_token={SHORT_TOKEN}
  1. Stocker dans une variable d'environnement META_ACCESS_TOKEN

Token Shopify Admin (scope read_analytics)

  1. Shopify Admin → Apps → Développer des apps → Créer une app privée
  2. Activer le scope read_analytics (critique — absent par défaut)
  3. Générer le token Admin API
  4. Stocker dans SHOPIFY_ADMIN_TOKEN

📡 MODULE 1 : Meta Marketing API

Endpoint — Récupérer les campagnes

GET https://graph.facebook.com/v20.0/act_{AD_ACCOUNT_ID}/campaigns
  ?fields=id,name,start_time,stop_time,status,daily_budget
  &effective_status=["ACTIVE","PAUSED"]
  &access_token={META_ACCESS_TOKEN}

Données retournées : id, name, start_time (date de lancement = critique pour règle test jours 1-3), status

Endpoint — Insights d'une campagne

GET https://graph.facebook.com/v20.0/{CAMPAIGN_ID}/insights
  ?fields=spend,ctr,cpc,cpm,impressions,clicks,actions,cost_per_action_type
  &level=campaign
  &time_range={"since":"YYYY-MM-DD","until":"YYYY-MM-DD"}
  &access_token={META_ACCESS_TOKEN}

Extraction des achats : dans actions[], filtrer action_type == "purchase" → value = nombre d'achats
CPA réel : dans cost_per_action_type[], filtrer action_type == "purchase" → value = CPA en €

Endpoint — Deep Dive niveau Publicités

GET https://graph.facebook.com/v20.0/{CAMPAIGN_ID}/insights
  ?fields=ad_id,ad_name,spend,ctr,cpc,impressions,actions
  &level=ad
  &time_range={"since":"YYYY-MM-DD","until":"YYYY-MM-DD"}
  &access_token={META_ACCESS_TOKEN}

Usage : Identifier les créatives Sangsues (CPC > 2€, CTR < 1%) vs Gagnantes.


🛍️ MODULE 2 : Shopify ShopifyQL API

Endpoint

POST https://{STORE}.myshopify.com/admin/api/2024-01/graphql.json
Header: X-Shopify-Access-Token: {SHOPIFY_ADMIN_TOKEN}
Header: Content-Type: application/json

Mutation GraphQL

mutation shopifyqlQuery($query: String!) {
  shopifyqlQuery(query: $query) {
    tableData {
      unformattedData
      columnMeta { name dataType }
    }
    parseErrors { code message }
  }
}

Query ShopifyQL (variables)

FROM sessions 
SHOW sessions, added_to_carts, orders_placed, conversion_rate 
SINCE {SINCE_DATE} 
UNTIL {UNTIL_DATE}

Métriques disponibles : sessions, added_to_carts, orders_placed, conversion_rate, returning_customer_rate

Format dates : YYYY-MM-DD — utiliser start_time[:10] de la campagne Meta comme SINCE_DATE


🧠 MODULE 3 : Matrice de Décision (rappel)

Signal Décision
Spend > CPA_seuil × 1.5 ET 0 achat KILL campagne
Spend > CPA_seuil × 0.5 ET 0 ATC KILL campagne
CPC > 2€ ET CTR < 0.8% KILL créative
CPA < seuil ET ≥ 3 achats ET ≥ 3 jours SCALE +20% budget
Jours 1-3 : CPC > 2€ sur certaines pubs OPTIMIZE : Kill les Sangsues uniquement
Bon CTR mais peu de sessions Shopify TROUBLESHOOT : tracking / vitesse site

🚀 SCRIPT DE RÉFÉRENCE

Fichier : C:\ASSISTANT_IA\meta_shopify_analytics.py

Lancement :

python "meta_shopify_analytics.py"
# Ou avec filtre par nom de campagne :
python "meta_shopify_analytics.py" "Robe"

Ce script implémente : les 3 modules ci-dessus + la matrice de décision complète en un seul fichier autonome.


🔄 PROTOCOLE D'EXÉCUTION POUR LES AGENTS

Séquence recommandée

  1. Vérifier que META_ACCESS_TOKEN et SHOPIFY_ADMIN_TOKEN sont disponibles
  2. Appeler get_meta_campaigns() → récupérer campagnes actives + dates
  3. Pour chaque campagne → get_meta_campaign_insights(campaign_id, since, until)
  4. Calculer days_running depuis start_time → détermine règle Test vs Croisière
  5. Appeler get_shopify_analytics(since_date, until_date) avec les mêmes dates
  6. Appeler apply_decision_matrix(meta_data, shopify_data, days_running)
  7. Produire le rapport final + envoyer via Telegram si mode autonome

FALLBACK si tokens absents

Si SHOPIFY_ADMIN_TOKEN non configuré → basculer sur l'ancienne méthode :
- Lancer capture_shopify_vision.py via CDP port 9222
- Lire la capture d'écran avec la vision multimodale
- Référence : Section R de SKILL_Global_Advanced_Automation.md


🔗 Fichiers liés