Skip to main content
Un Ad Group se trouve dans une campagne publicitaire et contrôle la diffusion des annonces. Il définit l’audience, le calendrier et le budget de ses annonces. Utilisez l’API Ad Groups pour créer des groupes d’annonces dans des campagnes, lister ou récupérer les paramètres de ciblage et de diffusion, mettre à jour les budgets ou le ciblage, supprimer les groupes qui doivent cesser d’être diffusés, et mettre en pause ou reprendre la diffusion.

Endpoints

Restrictions de ciblage

Les groupes d’annonces ne peuvent pas cibler les pays répertoriés dans le guide publicitaire. Les requêtes de création d’un groupe d’annonces ou de mise à jour de ses pays ciblés sont rejetées si elles incluent un pays bloqué dans regions.include.countries.

Attributs

string
requis
Identifiant unique du groupe d’annonces, préfixé par adgrp_.
object
requis
La campagne publicitaire à laquelle appartient ce groupe d’annonces.

Propriétés

string
requis
L’id de l’entité référencée.
number
requis
Valeur en USD attribuée aux événements d’ajout au panier. Additionne la valeur envoyée avec chaque événement, normalisée en USD ; les événements sans valeur comptent pour 0.
number
requis
Événements d’ajout au panier attribués par le pixel Whop, au dernier clic.
object
requis
Audiences enregistrées vers lesquelles ce groupe d’annonces diffuse ou qu’il exclut.

Propriétés

string[]
requis
ID des audiences enregistrées exclues de la diffusion, préfixés par adaud_.
string[]
requis
ID des audiences enregistrées vers lesquelles le groupe d’annonces diffuse, préfixés par adaud_.
string | null
requis
La manière dont les enchères de diffusion sont définies dans l’enchère publicitaire. Les stratégies basées sur une cible utilisent desired_cost_per_result.Options disponibles : minimum_cost, average_target, maximum_target
number | null
requis
Le budget de ce groupe d’annonces en USD, devise dans laquelle il est stocké et facturé. null lorsque le budget est défini sur la campagne à la place.
number | null
requis
Le même budget exprimé en budget_currency au taux de change du jour, pour l’affichage dans la devise de reporting publicitaire du compte. null lorsque budget_amount l’est.
string
requis
Le code ISO 4217 dans lequel est exprimé budget_amount_local : la préférence ads_reporting_currency du compte. usd sauf si le compte l’a modifiée.
string | null
requis
Indique si budget_amount est dépensé par jour (daily) ou sur toute la durée du groupe d’annonces (lifetime). Un groupe d’annonces lifetime nécessite également ends_at, au moins 24 heures après son démarrage.Options disponibles : daily, lifetime
number
requis
Clics divisés par les impressions, entre 0 et 1.
number
requis
Le nombre de clics.
number
requis
Valeur en USD attribuée aux événements d’inscription terminée. Additionne la valeur envoyée avec chaque événement, normalisée en USD ; les événements sans valeur comptent pour 0.
number
requis
Événements d’inscription terminée attribués par le pixel Whop, au dernier clic.
number
requis
Valeur en USD attribuée aux événements de contact. Additionne la valeur envoyée avec chaque événement, normalisée en USD ; les événements sans valeur comptent pour 0.
number
requis
Événements de contact attribués par le pixel Whop, au dernier clic.
string | null
requis
L’événement du pixel pour lequel l’optimisation est effectuée. Un événement standard, ou n’importe quel nom d’événement de pixel personnalisé.
number | null
requis
Dépenses divisées par les événements d’ajout au panier attribués ; null lorsqu’ils ne sont pas l’objectif et qu’aucun n’est attribué.
number
requis
Dépenses divisées par les clics ; 0 en l’absence de clics.
number | null
requis
Dépenses divisées par les événements d’inscription terminée attribués ; null lorsqu’ils ne sont pas l’objectif et qu’aucun n’est attribué.
number | null
requis
Dépenses divisées par les événements de contact attribués ; null lorsque les contacts ne sont pas l’objectif et qu’aucun n’est attribué.
number | null
requis
Dépenses divisées par les leads attribués ; null lorsque les leads ne sont pas un objectif et qu’aucun n’est attribué.
number
requis
Dépenses pour 1 000 impressions ; 0 en l’absence d’impressions.
number | null
requis
Dépenses divisées par les achats attribués ; null lorsque les achats ne sont pas un objectif et qu’aucun n’est attribué.
number | null
requis
Dépenses divisées par les résultats attribués par le pixel Whop ; null lorsque rien d’attribuable par Whop n’est optimisé.
number | null
requis
Dépenses divisées par les événements de prise de rendez-vous attribués ; null lorsque les rendez-vous ne sont pas l’objectif et qu’aucun n’est attribué.
number | null
requis
Dépenses divisées par les événements de soumission de candidature attribués ; null lorsqu’ils ne sont pas l’objectif et qu’aucun n’est attribué.
number | null
requis
Dépenses divisées par les clics uniques ; null en l’absence de clics uniques.
number | null
requis
Dépenses divisées par les événements de consultation de contenu attribués ; null lorsqu’ils ne sont pas l’objectif et qu’aucun n’est attribué.
string
requis
Date de création du groupe d’annonces, sous forme d’horodatage ISO 8601.
number
requis
Événements de conversion personnalisés (définis par le marchand) attribués par le pixel Whop, au dernier clic, tous noms d’événements personnalisés confondus.
object
requis
Conversions personnalisées attribuées par le pixel Whop, indexées par le nom de votre événement, avec leur nombre au dernier clic comme valeur. Vide lorsqu’aucun événement personnalisé nommé n’est attribué. Les événements personnalisés déclenchés sans nom sont comptés dans custom_conversions mais omis ici, de sorte que la somme de ces valeurs est au plus égale à custom_conversions.
object
requis
Valeur de conversion attribuée à chaque événement personnalisé, indexée par nom d’événement comme custom_event_counts. Additionne la valeur transmise à whop.track, normalisée en USD ; les événements déclenchés sans valeur comptent pour 0.
object | null
requis
Heures de diffusion du groupe d’annonces chaque semaine, indexées par jour. Les jours sans diffusion sont omis. null lorsqu’il diffuse à toute heure. Certaines plateformes exigent un budget_type lifetime pour un calendrier, sur le groupe d’annonces ou sur sa campagne lorsque c’est la campagne qui détient le budget.

Propriétés

object[]
Plages de diffusion du groupe d’annonces le vendredi, par ordre chronologique. Omis lorsqu’il ne diffuse pas ce jour-là.

Propriétés

string
requis
Heure de fin de la diffusion, au format 24 heures HH:00, jusqu’à 24:00 pour minuit. Postérieure à start ; une plage dépassant minuit est répartie sur deux jours.
string
requis
Heure de début de la diffusion, au format 24 heures HH:00, de 00:00 à 23:00.
object[]
Plages de diffusion du groupe d’annonces le lundi, par ordre chronologique. Omis lorsqu’il ne diffuse pas ce jour-là.

Propriétés

string
requis
Heure de fin de la diffusion, au format 24 heures HH:00, jusqu’à 24:00 pour minuit. Postérieure à start ; une plage dépassant minuit est répartie sur deux jours.
string
requis
Heure de début de la diffusion, au format 24 heures HH:00, de 00:00 à 23:00.
object[]
Plages de diffusion du groupe d’annonces le samedi, par ordre chronologique. Omis lorsqu’il ne diffuse pas ce jour-là.

Propriétés

string
requis
Heure de fin de la diffusion, au format 24 heures HH:00, jusqu’à 24:00 pour minuit. Postérieure à start ; une plage dépassant minuit est répartie sur deux jours.
string
requis
Heure de début de la diffusion, au format 24 heures HH:00, de 00:00 à 23:00.
object[]
Plages de diffusion du groupe d’annonces le dimanche, par ordre chronologique. Omis lorsqu’il ne diffuse pas ce jour-là.

Propriétés

string
requis
Heure de fin de la diffusion, au format 24 heures HH:00, jusqu’à 24:00 pour minuit. Postérieure à start ; une plage dépassant minuit est répartie sur deux jours.
string
requis
Heure de début de la diffusion, au format 24 heures HH:00, de 00:00 à 23:00.
object[]
Plages de diffusion du groupe d’annonces le jeudi, par ordre chronologique. Omis lorsqu’il ne diffuse pas ce jour-là.

Propriétés

string
requis
Heure de fin de la diffusion, au format 24 heures HH:00, jusqu’à 24:00 pour minuit. Postérieure à start ; une plage dépassant minuit est répartie sur deux jours.
string
requis
Heure de début de la diffusion, au format 24 heures HH:00, de 00:00 à 23:00.
object[]
Plages de diffusion du groupe d’annonces le mardi, par ordre chronologique. Omis lorsqu’il ne diffuse pas ce jour-là.

Propriétés

string
requis
Heure de fin de la diffusion, au format 24 heures HH:00, jusqu’à 24:00 pour minuit. Postérieure à start ; une plage dépassant minuit est répartie sur deux jours.
string
requis
Heure de début de la diffusion, au format 24 heures HH:00, de 00:00 à 23:00.
object[]
Plages de diffusion du groupe d’annonces le mercredi, par ordre chronologique. Omis lorsqu’il ne diffuse pas ce jour-là.

Propriétés

string
requis
Heure de fin de la diffusion, au format 24 heures HH:00, jusqu’à 24:00 pour minuit. Postérieure à start ; une plage dépassant minuit est répartie sur deux jours.
string
requis
Heure de début de la diffusion, au format 24 heures HH:00, de 00:00 à 23:00.
string
requis
Indique si les annonces de ce groupe d’annonces sont actuellement diffusées et, sinon, pourquoi. Lorsque plusieurs états s’appliquent simultanément, celui ayant la priorité la plus élevée est renvoyé.Options disponibles : all_ads_rejected, rejected, draft, campaign_paused, paused, in_review, processing, revise_content, issues, scheduled, completed, learning, active
object
requis
Ciblage par âge, genre et audience automatique.

Propriétés

boolean
requis
Indique si le ciblage d’audience automatique est activé. Lorsque true, la diffusion peut aller au-delà des âges et genres que vous définissez, en les traitant comme des suggestions.
string
requis
Genre ciblé.Options disponibles : all, male, female
number | null
requis
Âge maximum ciblé. null lorsqu’aucun maximum n’est défini.
number | null
requis
Âge minimum ciblé. null lorsqu’aucun minimum n’est défini.
number | null
requis
Coût par résultat à viser (average_target) ou à ne jamais dépasser (maximum_target). null pour les enchères minimum_cost.
object
requis
Plateformes d’appareils et systèmes d’exploitation ciblés.

Propriétés

object[]
requis
Systèmes d’exploitation ciblés. Une liste vide cible tous les systèmes d’exploitation.

Propriétés

string
Version minimale du système d’exploitation ciblée, par exemple 18.0. Absent lorsque toutes les versions sont éligibles.
string
requis
Système d’exploitation ciblé.Options disponibles : ios, android
string[]
requis
Types d’appareils ciblés. Une liste vide cible tous les appareils.Options disponibles : mobile, desktop
string | null
requis
Date à laquelle le groupe d’annonces cesse d’être diffusé, sous forme d’horodatage ISO 8601. null lorsqu’il est diffusé jusqu’à sa mise en pause.
number | null
requis
Impressions divisées par la couverture.
number
requis
Le nombre d’impressions.
object[]
requis
Problèmes ouverts affectant ce groupe d’annonces et ses annonces. Vide lorsqu’il n’y en a aucun.

Propriétés

string
requis
Identifiant unique du problème.
string
requis
Le type de problème : une information sur la diffusion, un avertissement ou une erreur nécessitant une action.Options disponibles : information, warning, error
string
requis
Une description du problème et de la manière de le résoudre.
string | null
requis
L’ID de la campagne, du groupe d’annonces ou de l’annonce auquel le problème est rattaché.
string
requis
Le type de ressource auquel le problème est rattaché.Options disponibles : ad_campaign, ad_group, ad
string
requis
Un titre court du problème, destiné au créateur : la règle citée par un rejet lors de la vérification du contenu, ou un libellé générique.
object[]
Termes de recherche pour lesquels les annonces de ce groupe peuvent s’afficher, et termes pour lesquels elles ne s’affichent jamais. Campagnes de recherche uniquement, où chaque groupe d’annonces en nécessite au moins un avant le lancement.

Propriétés

string
requis
Degré de correspondance requis pour une recherche : broad atteint aussi les recherches associées, phrase exige le sens de l’expression, et exact exige le même sens que le terme. Valeur par défaut : broad.Options disponibles : broad, phrase, exact
boolean
requis
Indique si ce terme empêche l’affichage des annonces au lieu de les rendre éligibles. Valeur par défaut : false.
string
requis
Le terme de recherche, jusqu’à 80 caractères et 10 mots.
string[]
requis
Langues ciblées, sous forme de codes ISO 639 comme en ou es. Une locale propre à une région sans code ISO apparaît sous forme de clé de locale numérique. Une liste vide cible toutes les langues.
number
requis
Valeur en USD attribuée aux événements de lead. Additionne la valeur envoyée avec chaque événement, normalisée en USD ; les événements sans valeur comptent pour 0.
number
requis
Leads attribués par le pixel Whop, au dernier clic.
object | null
requis
Progression vers le nombre de conversions requis par la phase d’apprentissage de ce groupe d’annonces. Null sauf s’il est en apprentissage ou en apprentissage limité et que des décomptes valides sont disponibles. L’atteinte du seuil ne détermine pas le statut de diffusion.

Propriétés

integer
requis
Les conversions requises par la phase d’apprentissage de ce groupe d’annonces. Ce nombre peut changer pendant la diffusion.
integer
requis
Conversions comptabilisées depuis la dernière modification importante pendant la phase d’apprentissage de ce groupe d’annonces.
number
requis
Conversions divisées par le seuil, sous forme de pourcentage borné entre 0 et 100. Le delivery_status du groupe d’annonces reste la référence.
Pages vues sur votre destination par les personnes ayant cliqué sur l’annonce, enregistrées par le pixel Whop. Comptabilisées de la même manière sur toutes les plateformes publicitaires.
number
requis
Valeur en USD des achats attribués par le pixel.
number
requis
Achats attribués par le pixel Whop, au dernier clic.
number
requis
Le nombre de personnes uniques ayant vu ceci.
object
requis
Lieux ciblés et exclus.

Propriétés

object
requis
Lieux exclus du ciblage. Les groupes de pays ne peuvent pas être exclus.

Propriétés

object[]
requis
Villes, indexées selon la taxonomie des lieux.

Propriétés

string
requis
La clé de la ville dans la taxonomie des lieux.
string
Nom de la ville, par exemple Austin. Absent lorsque la taxonomie des lieux n’en contient pas.
string[]
requis
Pays, sous forme de codes ISO 3166-1 alpha-2 comme US.
string[]
requis
Groupes multi-pays comme worldwide ou europe.
object[]
requis
Zones circulaires, chacune définie par des coordonnées et un rayon.

Propriétés

string
Pays ISO 3166-1 alpha-2 dans lequel se trouve le point. Envoyez-le dans le cadre d’une catégorie publicitaire spéciale, où la campagne doit déclarer les pays atteints par ses ensembles de publicités.
string
requis
Unité de radius.Options disponibles : mile, kilometer
number
requis
Latitude du point central.
number
requis
Longitude du point central.
string
Libellé du lieu, par exemple une ville ou une adresse. Absent lorsque le lieu n’a pas de libellé.
number
requis
Rayon autour du point central, en distance_unit.
string[]
requis
États américains et DC, sous forme de codes ISO 3166-2 comme US-CA. Les territoires américains (PR, GU, VI, AS, MP) et tous les lieux hors des États-Unis sont ciblés via countries.
string[]
requis
Codes ZIP et codes postaux, indexés sous la forme COUNTRY:CODE, par exemple US:78756.
object
requis
Lieux ciblés par le groupe d’annonces.

Propriétés

object[]
requis
Villes, indexées selon la taxonomie des lieux.

Propriétés

string
requis
La clé de la ville dans la taxonomie des lieux.
string
Nom de la ville, par exemple Austin. Absent lorsque la taxonomie des lieux n’en contient pas.
string[]
requis
Pays, sous forme de codes ISO 3166-1 alpha-2 comme US.
string[]
requis
Groupes multi-pays comme worldwide ou europe.
object[]
requis
Zones circulaires, chacune définie par des coordonnées et un rayon.

Propriétés

string
Pays ISO 3166-1 alpha-2 dans lequel se trouve le point. Envoyez-le dans le cadre d’une catégorie publicitaire spéciale, où la campagne doit déclarer les pays atteints par ses ensembles de publicités.
string
requis
Unité de radius.Options disponibles : mile, kilometer
number
requis
Latitude du point central.
number
requis
Longitude du point central.
string
Libellé du lieu, par exemple une ville ou une adresse. Absent lorsque le lieu n’a pas de libellé.
number
requis
Rayon autour du point central, en distance_unit.
string[]
requis
États américains et DC, sous forme de codes ISO 3166-2 comme US-CA. Les territoires américains (PR, GU, VI, AS, MP) et tous les lieux hors des États-Unis sont ciblés via countries.
string[]
requis
Codes ZIP et codes postaux, indexés sous la forme COUNTRY:CODE, par exemple US:78756.
string | null
requis
L’événement de conversion du pixel Whop dont le nombre attribué représente les résultats : l’objectif d’optimisation, ou l’événement attribué au volume le plus élevé pour les campagnes budgétées par groupe d’annonces. Null lorsque l’objectif n’est pas un événement attribué par Whop.Options disponibles : purchase, lead, schedule, submit_application, contact, complete_registration, view_content, add_to_cart, custom, messaging_conversation
string | null
requis
Le nom d’événement défini par le marchand lorsque result_event vaut custom ; null pour les événements standard.
number | null
requis
Le nombre attribué par le pixel Whop derrière result_event. Lorsque les groupes d’annonces d’une campagne optimisent des objectifs différents, il n’y a pas de result_event unique (il vaut null), et cette valeur correspond alors à la somme des résultats attribués propres à chaque groupe d’annonces. Null lorsque rien d’attribuable par Whop n’est optimisé.
number
requis
Valeur des achats divisée par les dépenses, toutes deux en USD (un ratio indépendant de la devise) ; 0 en l’absence de dépenses.
number
requis
Valeur en USD attribuée aux événements de prise de rendez-vous. Additionne la valeur envoyée avec chaque événement, normalisée en USD ; les événements sans valeur comptent pour 0.
number
requis
Événements de prise de rendez-vous attribués par le pixel Whop, au dernier clic.
number
requis
Le montant facturé, en spend_currency.
string | null
requis
Le code de devise ISO 4217 de toutes les métriques monétaires.
string | null
requis
Date à laquelle le groupe d’annonces commence à être diffusé, sous forme d’horodatage ISO 8601. null lorsqu’il démarre dès qu’il est actif.
string
requis
Indique si le groupe d’annonces est activé. active et paused sont définis par vous ; rejected signifie qu’il a échoué à la vérification publicitaire ; duplicating est une copie encore en cours de remplissage.Options disponibles : active, paused, rejected, duplicating
number
requis
Valeur en USD attribuée aux événements de soumission de candidature. Additionne la valeur envoyée avec chaque événement, normalisée en USD ; les événements sans valeur comptent pour 0.
number
requis
Événements de soumission de candidature attribués par le pixel Whop, au dernier clic.
string | null
requis
Nom d’affichage du groupe d’annonces.
number | null
requis
Clics uniques divisés par les impressions, entre 0 et 1.
number
requis
Personnes ayant cliqué, signalées par le pixel Whop, comptées une seule fois par personne.
string
requis
Date de dernière mise à jour du groupe d’annonces, sous forme d’horodatage ISO 8601.
number
requis
Valeur en USD attribuée aux événements de consultation de contenu. Additionne la valeur envoyée avec chaque événement, normalisée en USD ; les événements sans valeur comptent pour 0.
number
requis
Événements de consultation de contenu attribués par le pixel Whop, au dernier clic.
AdGroup