Meta Ads Fetcher

Récupère les publicités d'un compte Meta via la Marketing API : nomenclature sur les trois niveaux, performances, copy, et surtout les URLs média — MP4 téléchargeables et images pleine résolution.

---

Pourquoi cet actor existe

Le connecteur MCP Meta fonctionne bien, mais il a deux limites que rien ne permet de contourner de son côté :

Il n'est pas ouvert sur tous les comptes. Meta déploie l'accès progressivement, compte par compte. Un compte parfaitement actif peut ne pas l'avoir. Un compte désactivé ne l'aura jamais.

Il ampute un champ décisif. Sur ads_get_ad_videos, le champ source est explicitement rejeté — c'est pourtant lui qui donne l'URL MP4 téléchargeable. Résultat : avec le MCP seul, on ne peut pas analyser une vidéo.

La Marketing API n'a aucune de ces limites. Le verrou is_ads_mcp_enabled ne concerne que le serveur MCP : l'API classique fonctionne sur n'importe quel compte auquel tu as accès.

---

Ce que tu récupères

Donnée	Détail
Nomenclature	Nom de l'ad, de l'ad set et de la campagne — les trois niveaux, pour parser ta convention de nommage
Copy	Titre, body, call-to-action
Vidéos	URL MP4 téléchargeable, miniature, durée
Statics	Image pleine résolution, dimensions, hash
Dynamic creative	Assets extraits de asset_feed_spec — le cas que la plupart des scripts oublient
Performances	Spend, impressions, reach, fréquence, clics, CTR, CPC, CPM, achats, CPA, métriques vidéo
Aperçu	Rendu HTML de l'annonce (optionnel, ralentit sur gros volume)

---

Installation — une seule fois

1. L'app Meta

Sur developers.facebook.com → Mes apps → Créer une app → type Business.

Dans l'app : Ajouter un produit → Marketing API.

Si tu as déjà une app Business, inutile d'en créer une autre — ajoute-lui simplement le produit Marketing API.

2. Le system user et son token

Dans ton Business Manager → Paramètres de l'entreprise → Utilisateurs → Utilisateurs système → Ajouter.

• Nom : au choix
• Rôle : Employé suffit

Puis, sur ce system user :

1. Ajouter des ressources → tes comptes publicitaires → accès Afficher les performances (lecture seule suffit)
2. Générer un nouveau token → choisis ton app → permission ads_read (ajoute business_management si tu gères des comptes clients)
3. Copie le token immédiatement — il ne sera plus affiché

💡 Ce token n'expire pas, contrairement à un token utilisateur qui dure environ 60 jours. C'est toute la raison de passer par un system user.

3. Pour un compte client

Le client partage son compte publicitaire avec ton Business Manager en partenaire, puis tu assignes ce compte à ton system user.

Un accès lecture seule en Standard Access suffit. Les limites de débit sont juste plus basses — sans conséquence sur un usage normal.

4. L'actor

Sur console.apify.com → Actors → Development → Create new → template Node.js — Empty project.

Copie les fichiers de ce dossier :

.actor/actor.json
.actor/input_schema.json
src/main.js
package.json
Dockerfile

⚠️ Trois pièges du template par défaut :

• Il crée souvent un INPUT_SCHEMA.json à la racine → supprime-le, garde celui dans .actor/
• Écrase src/main.js entièrement
• Vérifie que package.json contient bien "type": "module"

Puis Build, et Publication pour l'appeler depuis le MCP Apify.

---

Utilisation

{
  "accessToken": "<ton token system user>",
  "adAccountId": "664188280758656",
  "datePreset": "last_30d",
  "includeInsights": true,
  "includeMedia": true
}

⚠️ L'identifiant du compte va sans le préfixe act_.

Depuis Claude :

call-actor("<username>/meta-ads-fetcher", {
  accessToken: "<token>",
  adAccountId: "<id>",
  datePreset: "last_30d"
})

Pour une période précise :

{ "timeRange": { "since": "2026-01-01", "until": "2026-03-31" } }

---

Deux pièges documentés par Meta

thumbnail_url est en basse résolution par défaut. L'actor l'expose sous le nom thumbnail_low_res pour éviter qu'on l'utilise par erreur — l'image pleine résolution est dans media.url, récupérée via le hash.

source peut revenir vide sur certaines vidéos, typiquement celles issues d'un post de page sur lequel le token n'a pas les droits. L'actor bascule alors automatiquement sur advideos. Si ça échoue aussi, le champ note explique pourquoi — plutôt qu'un null silencieux.

---

Structure des résultats

Une ligne par ad :

{
  "ad_id": "120247580389050526",
  "ad_name": "Batch 08/04/26 - Static 7",
  "adset_name": "...",
  "campaign_name": "...",
  "effective_status": "ACTIVE",
  "created_time": "2026-04-08T10:23:00+0000",
  "title": "...",
  "body": "...",
  "media": {
    "type": "video",
    "video_id": "4350315591909408",
    "source": "https://video.xx.fbcdn.net/....mp4",
    "thumbnail": "https://scontent...jpg",
    "length_seconds": 40.7
  },
  "is_dynamic_creative": false,
  "spend": 5625.42,
  "purchases": 312,
  "cost_per_purchase": 18.03,
  "ctr": 1.24,
  "cpm": 8.91
}

Un objet SUMMARY est aussi écrit dans le key-value store : nombre d'ads, répartition statics/vidéos, vidéos sans source, dynamic creatives.

---

Messages d'erreur

Message	Cause
Token invalide ou expire	Régénère le token du system user
Permissions insuffisantes sur le compte	Le system user n'est pas assigné à ce compte, ou pas avec ads_read
Quota API atteint	Attends quelques minutes, ou réduis la période
Aucune ad trouvee	Vérifie l'identifiant du compte, ou élargis effectiveStatus

---

Coût

Quelques centimes par exécution — c'est du temps de calcul Apify, pas d'appel payant.

L'API Meta est gratuite dans les limites de débit standard. Sur un très gros historique, découper la période en plusieurs exécutions plutôt que de tout demander d'un coup.