CDCStream/skills

Différence hebdomadaire de la bibliothèque publicitaire

Récupérez les annonces actuellement visibles de chaque concurrent depuis les bibliothèques publiques, comparez-les avec l'instantané de la semaine dernière et rédigez un court rapport de ce qui est nouveau, ce qui a cessé, et ce que disent les nouvelles annonces.

Ce que les bibliothèques publiques peuvent et ne peuvent pas vous dire

Déclarez ces limites dans chaque rapport. Ne laissez pas le lecteur en déduire davantage.

• Les bibliothèques publiques n'affichent pas les dépenses, impressions ou conversions pour les annonces commerciales ordinaires. Google publie des fourchettes de dépenses et d'impressions uniquement pour les annonces électorales ; Meta montre des détails de portée uniquement pour certaines annonces diffusées dans l'UE et politiques ; LinkedIn affiche les impressions et le ciblage sur un sous-ensemble d'annonces. N'estimez jamais le budget ou la performance à partir du nombre d'annonces.
• « Absent de la bibliothèque » ne signifie pas « pas de publicité » : les bibliothèques sont limitées à un pays et peuvent accuser un retard d'un jour ou plus.
• La bibliothèque publicitaire de TikTok ne couvre que les annonces diffusées dans l'UE/EEE, le Royaume-Uni et la Suisse. En dehors de ces pays, indiquez « TikTok : non couvert » — ne signalez pas zéro annonce.
• Les dates de première/dernière diffusion d'une annonce sont des jours calendaires, pas des heures exactes.

Entrées à collecter d'abord

1. Concurrents : nom de la marque, et si connu, l'URL de leur page Meta, le nom de l'annonceur Google et le nom de l'entreprise LinkedIn.
2. Pays (codes à deux lettres). Par défaut : US. Ajoutez un pays de l'UE/Royaume-Uni tel que GB ou DE si TikTok est pertinent.
3. Chemin du fichier d'instantané. Par défaut : ad-library-snapshot.json dans le répertoire de travail.
4. Indiquez s'il faut extraire les détails et le texte des annonces pour les nouvelles annonces (plus de crédits, meilleur rapport).

Estimation des crédits — à afficher avant l'exécution

Par concurrent, par pays :

Étape	Endpoint	Crédits
Trouver la page Meta	/v1/ad-library/facebook/search-companies	2
Annonces Meta	/v1/ad-library/facebook/company-ads	2
Trouver l'annonceur Google	/v1/ad-library/google/advertiser-search	1
Annonces Google	/v1/ad-library/google/company-ads	2
Annonces LinkedIn	/v1/ad-library/linkedin/search-ads	2
Annonces TikTok (UE/EEE/Royaume-Uni/CH uniquement)	/v1/ad-library/tiktok/search	2 (jusqu'à 5 sur son chemin de repli)

Cela représente environ 11 crédits par concurrent et par pays (9 là où TikTok n'est pas couvert). Les étapes de recherche peuvent être ignorées lors des exécutions ultérieures en sauvegardant l'ID de la page et l'ID de l'annonceur dans l'instantané.

En option, uniquement pour chaque nouvelle annonce : détails (.../ad-details, 2 chacun) et texte de l'annonce Meta (/v1/ad-library/facebook/ad-transcript, 2 chacun). Limitez ces options — par exemple à 5 nouvelles annonces par concurrent — et mentionnez-les dans l'estimation.

Affichez l'estimation (concurrents × pays × 11, plus le plafond des détails) et vérifiez le solde avec GET /v1/account/balance (gratuit). Demandez à l'utilisateur de confirmer avant de dépenser.

Comment appeler Captapi

Les deux chemins fonctionnent ; utilisez celui que l'environnement propose.

• MCP : outils nommés d'après l'endpoint, par exemple facebook_ad_library_company_ads, google_ad_library_company_ads, linkedin_ad_library_search_ads, tiktok_ad_library_search.
• REST : GET https://api.captapi.com<path>?<params> avec l'en-tête Authorization: Bearer $CAPTAPI_API_KEY.

Les appels échoués coûtent 0 crédit. Une erreur avec retryable: true peut être retentée une fois après une courte attente ; retryable: false est une réponse définitive — enregistrez-la, ne bouclez pas.

Étapes

1. Chargez l'instantané s'il existe. Il associe concurrent → pays → bibliothèque → {ids: [...], meta: {...}} ainsi que les IDs de recherche sauvegardés.
2. Résolvez les IDs seulement là où l'instantané n'en a pas :
   • Meta : facebook/search-companies?q=<marque>&country=<cc> → choisissez la page correspondant au nom ; conservez son pageId. Si plusieurs semblent corrects, demandez.
   • Google : google/advertiser-search?q=<marque>&country=<cc> → conservez l'ID de l'annonceur du résultat correspondant.
3. Récupérez les annonces actuelles pour chaque concurrent et pays :
   • facebook/company-ads?url=<pageId ou URL de la page>&country=<cc>&status=active
   • google/company-ads?advertiser=<ID ou nom de l'annonceur>&country=<cc>
   • linkedin/search-ads?company=<nom>&country=<cc>
   • tiktok/search?q=<marque>&country=<cc> — uniquement pour UE/EEE/Royaume-Uni/CH.
4. Différenciez par ID d'annonce par rapport à l'instantané : nouvelle (présente maintenant, pas avant), arrêtée (avant, pas maintenant), continue.
5. Enrichissez les nouvelles annonces jusqu'au plafond convenu : .../ad-details pour les dates et les médias, facebook/ad-transcript pour le titre/le corps/CTA/l'URL de destination Meta.
6. Rédigez le rapport (format ci-dessous) et sauvegardez le nouvel instantané — uniquement après la rédaction du rapport, de sorte qu'un échec n'écrase jamais les données de la semaine dernière.

Format du rapport

Pour chaque concurrent :

• Une ligne par bibliothèque : N nouvelles · N arrêtées · N en cours, ou la raison de son absence (non couvert dans ce pays, recherche échouée, 0 annonce trouvée).
• Nouvelles annonces : titre ou première ligne du texte, format (image/vidéo/carrousel), date de première diffusion, domaine de destination, et l'endpoint d'où elles proviennent, par ex. (source : /v1/ad-library/facebook/company-ads).
• Thèmes : 2 à 4 points sur les angles que partagent les nouvelles annonces (offre, audience, produit). Marquez chacun comme [nécessite une révision humaine] — c'est une interprétation.
• Annonces arrêtées : nombre, plus celle qui a duré le plus longtemps parmi celles qui se sont arrêtées.

Terminez par la section des limites ci-dessus, un total de crédits sur une ligne pour l'exécution, et le chemin de l'instantané.

Où une révision humaine est nécessaire

• Quelle page ou quel annonceur est « le » concurrent lorsque la recherche renvoie plusieurs résultats.
• Chaque affirmation de thème ou de stratégie — les bibliothèques montrent les créations, pas l'intention.
• Toute conclusion sur le budget ou la performance : il n'y a pas de données pour cela ; le rapport doit le dire plutôt que de deviner.