La CLI Adapty vous permet de gérer votre compte Ads Manager depuis le terminal, via la commande adapty asa. Elle couvre les campagnes, les groupes d’annonces, les mots-clés, les annonces, les pages produit, les règles d’automatisation, les métriques et la recherche concurrentielle.

Utilisez-le pour les tâches que le navigateur ralentit : donner à un agent IA un accès en direct à vos performances publicitaires, ajouter plusieurs centaines de mots-clés depuis un fichier, ou appliquer la même configuration sur plusieurs campagnes. Pour tout le reste, le tableau de bord reste plus rapide.

Avant de commencer

Les commandes d’Ads Manager utilisent la même installation et la même connexion que le reste de la CLI. Si vous ne l’avez pas encore configuré, suivez les étapes 1 et 2 du guide de démarrage rapide.

Prérequis

Deux conditions supplémentaires s’appliquent à chaque commande adapty asa :

• Un compte Apple Ads connecté : Connectez-le avec adapty asa connect, ou depuis le tableau de bord comme décrit dans Premiers pas avec Adapty Ads Manager.
• Un abonnement Ads Manager actif : Sans celui-ci, chaque commande échoue avec 402 ads_manager_subscription_required.

Une seule commande fournit les deux informations :

adapty asa whoami

Différences avec le reste du CLI

• Pas de flag --app : Le périmètre correspond à la société associée à votre token. --app existe sur certaines commandes list uniquement comme filtre.
• Les écritures atteignent Apple directement : Chaque commande qui modifie votre compte affiche le corps de la requête et demande une confirmation avant l’envoi. Il n’y a pas d’étape intermédiaire.
• Les lectures sont sans risque, pas les écritures : Utilisez librement les commandes list et --dry-run. Considérez tout le reste comme irréversible.

Pour ignorer l’invite de confirmation dans un script, passez --yes. Sous --json ou dans un pipe, une commande d’écriture refuse plutôt que d’attendre une réponse qui n’arrivera jamais, donc --yes est requis dans ce cas.

Trouver les identifiants dont vous avez besoin

Chaque commande utilise des UUID, et chaque UUID provient d’une commande list. Descendez dans la hiérarchie :

adapty asa orgs list
adapty asa campaigns list --campaign-group <campaign-group-id>
adapty asa ad-groups list --campaign <campaign-id>

Affinez chaque lecture avec un filtre. Les filtres limitent la requête plutôt que la page affichée, donc une lecture filtrée est légère tandis qu’une lecture sans filtre parcourt l’intégralité du compte. adapty asa keywords list sans --ad-group est la lecture la plus large de cette rubrique.

Ces listes ne renvoient que des métadonnées. Les chiffres de performance proviennent de asa metrics.

Obtenir des recommandations de mots-clés

Pour démarrer une liste de mots-clés sans recherche préalable, obtenez un pool prêt à l’emploi pour votre application. Transmettez l’adam_id de l’application issu de adapty asa apps list et le type de pool — brand, generic ou competitor :

adapty asa keywords recommend --adam-id <adam-id> --type generic --country US

Le pool n’a pas d’enchères ni de types de correspondance. Choisissez-les vous-même, puis ajoutez les mots-clés comme décrit dans Ajouter des mots-clés en masse. Si la sortie affiche status: building, réessayez dans environ une minute. Consultez les commandes Ads Manager pour les types de pool et les limites.

Ajouter des mots-clés en lot

Ajouter des mots-clés un par un est la principale raison de quitter le tableau de bord. Placez un mot-clé par ligne dans un fichier texte :

adapty asa keywords add --ad-group <ad-group-id> --from-file keywords.txt --bid 1.20 --match-type EXACT

Les mots-clés sont appliqués par lots de 100 au maximum par appel. Répartissez les listes plus longues sur plusieurs appels.

Deux types d’échec sont possibles, et ils se comportent différemment. Un identifiant invalide fait échouer tout le lot avant qu’Apple soit appelé, donc rien n’est appliqué. Apple peut également rejeter des mots-clés individuels — les autres sont quand même ajoutés, et chaque rejet est signalé avec sa raison. Vérifiez la ligne de résumé plutôt que le seul code de sortie.

Commencez par quelques mots-clés et vérifiez le résultat avant d’envoyer un fichier complet.

Créer une campagne Max Conversions

Une campagne qui enchérit avec MAX_CONVERSIONS ne se diffuse qu’une fois qu’elle possède un groupe d’annonces automatisé ; créez-les donc ensemble :

adapty asa campaigns create --org <campaign-group-id> --name "Max Conv" --adam-id 123456 --country US --daily-budget 50 --bidding-strategy MAX_CONVERSIONS
adapty asa ad-groups create --campaign <campaign-id> --name "Automated Max Conv" --automated

Tant que ce groupe d’annonces n’existe pas, la campagne affiche serving_status: NOT_RUNNING avec AUTOMATED_KEYWORDS_REQUIRED_AD_GROUP_MISSING parmi ses serving_state_reasons, et campaigns create affiche à la fois la raison et la commande qui y remédie.

--automated est ce qui satisfait cette exigence — un groupe d’annonces classique avec --automated-keywords ne suffit pas. Apple planifie et gère lui-même le groupe d’annonces automatisé, il ne prend donc pas de --start-time, --default-bid est facultatif, et il reste activé : pour arrêter les dépenses, mettez la campagne en pause.

Sur la campagne, maintenez --target-cpa inférieur à --daily-budget.

Définir les options de facturation pour une ligne de crédit

Apple exige des options de facturation sur chaque campagne d’une organisation qui facture par ligne de crédit. adapty asa orgs list indique le payment_model de chaque organisation — LOC signifie que les cinq flags --invoice-* s’appliquent :

adapty asa campaigns create --org <campaign-group-id> --name "LOC push" --adam-id 123456 --country US --daily-budget 50 --invoice-advertiser "Acme Inc" --invoice-order-number PO-42 --invoice-contact-name "Jane Doe" --invoice-contact-email jane@acme.com --invoice-billing-email billing@acme.com

Transmettez les cinq en un seul appel — un ensemble partiel est rejeté avant que la requête n’atteigne Apple. Sans eux, la campagne est créée mais signale serving_status: NOT_RUNNING avec MISSING_BO_OR_INVOICING_FIELDS.

Ces cinq mêmes options sur adapty asa campaigns update définissent les options de facturation d’une campagne existante. Elles remplacent l’ensemble stocké dans sa totalité, donc passez les cinq même pour n’en modifier qu’une.

Créer une structure de campagne en une seule opération

campaigns bulk-create remplace un script qui boucle sur campaigns create et ad-groups create. Il soumet toute une structure de campagne — campagnes avec leurs groupes d’annonces, mots-clés, mots-clés négatifs et annonces — en une seule opération :

adapty asa campaigns bulk-create --file structure.json

L’entrée est une description JSON de la structure — consultez le format de la structure pour les champs. JSON est la voie naturelle pour un agent IA : il génère la structure et la transmet via un pipe :

cat structure.json | adapty asa campaigns bulk-create --file -

Un modèle de campagne Apple Ads en masse fonctionne également en entrée — le serveur convertit Campaign_And_Adgroup_Template.xlsx ou un fichier .csv de mots-clés en structure. --org-id prend l’org_id numérique issu de adapty asa orgs list. Pour vérifier la conversion avant toute création, ajoutez --preview :

adapty asa campaigns bulk-create --from-file Campaign_And_Adgroup_Template.xlsx --org-id 1234567 --preview

Les problèmes de conversion sont signalés avec leur feuille, ligne et colonne. Quand la structure affichée semble correcte, supprimez --preview pour soumettre.

La sortie de --preview est aussi le moyen le plus rapide d’obtenir un fichier de structure de départ : enregistrez-le, modifiez-le, puis soumettez-le avec --file — de la même façon que automations get fournit un modèle de règle.

La structure entière est validée avant toute création, et un refus liste chaque nœud invalide. Une fois acceptée, les objets sont créés sur le serveur pendant que la commande affiche la progression. Le rapport final est success, partial ou failed — un résultat partial liste chaque objet non créé, avec l’erreur Apple associée.

Pour une structure volumineuse, passez --no-wait pour récupérer immédiatement l’ID d’opération et consulter la progression plus tard :

adapty asa campaigns bulk-status <operation-id>

Interroger les métriques depuis des agents et des scripts

asa metrics génère des rapports sur n’importe quel niveau du compte sur une plage de dates. Ajoutez --json pour qu’un agent IA ou un script puisse consommer le résultat directement :

adapty asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --metric spend --metric roas --json

--metric est obligatoire et peut être répété. Il prend les noms que le gestionnaire de publicités suit. Consultez Métriques pour la liste complète. Chaque métrique que vous spécifiez est calculée sur l’ensemble du niveau d’entité avant que la page ne soit découpée, donc demandez uniquement les colonnes que vous lisez plutôt que tout le catalogue.

--app, --campaign et --ad-group permettent de délimiter le rapport, et c’est le moyen le plus économique d’accélérer un appel, car le coût dépend du nombre d’entités agrégées plutôt que de la taille de la page. Quatre métriques comptent les profils uniques par entité — subscribers, paid_subscribers, arppu et arpas — et celles-ci nécessitent un filtre campaign ou ad group, quel que soit le niveau d’entité :

adapty asa metrics --entity keyword --date-from 2026-07-01 --date-to 2026-07-31 --metric arpas --campaign <campaign-id> --json

Les métriques de cohorte fonctionnent différemment des autres. Il n’y a pas de métrique ltv, car la valeur à vie est lue à une fenêtre de renouvellement plutôt qu’à une date. Demandez la fenêtre à la place :

adapty asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --metric roas --by-days 7 --by-days 90 --order-by-day 90

Cela retourne vos campagnes classées par ROAS à 90 jours. Jusqu’à 16 fenêtres peuvent tenir dans un seul appel.

Chaque ligne correspond à une entité, déjà agrégée et triée côté serveur. Une question du type « top cinq campagnes par dépenses » est donc un seul appel, et non un parcours de toutes les pages :

adapty asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --order-by spend --page-size 5

Metrics et la liste des termes de recherche partagent un même budget d’appels d’analyse par entreprise : 5 appels par minute, et au plus 2 toutes les 10 secondes. Posez une question précise en une seule fois plutôt que de faire du polling.

Deux limites s’appliquent à un rapport. La période de reporting est plafonnée par le niveau de regroupement choisi — 28 jours avec --group-by day, 90 jours sans regroupement de période, 180 jours par semaine, 365 par mois — et chaque page est limitée à 5 000 lignes de ventilation, soit une ligne par entité × pays × période. Pour élargir un rapport, affinez --group-by plutôt que de multiplier les appels.

Vérifier les mots-clés des concurrents

Une seule commande renvoie les mots-clés sur lesquels les applications concurrentes enchérissent, pour jusqu’à cinq applications de l’App Store à la fois :

adapty asa competitors summary --app-ids 1668337467,6503873027 --json

La période et les pays sont fixés côté serveur — le dernier mois complet, dans tous les pays — donc la commande n’a pas d’autres options que les identifiants d’application. Le premier appel pour un ensemble d’applications peut prendre plusieurs dizaines de secondes.

Utilisez ceci pour extraire des données de mots-clés concurrents dans un rapport selon un planning. Pour filtrer les résultats, comparer des pays côte à côte, ou ajouter directement les mots-clés trouvés à une campagne, utilisez Market Intelligence dans le tableau de bord.

Exécuter des règles d’automatisation

Le CLI enregistre le JSON que vous lui fournissez, donc le moyen le plus rapide d’obtenir un fichier de règle d’automatisation valide est de créer une règle dans le tableau de bord, puis de la relire :

adapty asa automations get <automation-id> --json > rule.json

Modifiez ce fichier et utilisez-le comme modèle pour de nouvelles règles :

adapty asa automations create --file rule.json

Un fichier de règle contient exactement une condition et une action, ce que l’API conserve par règle. Lorsque vous passez un fichier à automations update, supprimez d’abord le champ internal_id — la mise à jour est rejetée s’il est présent.

Créer une action Ajouter comme mot-clé à partir de marqueurs

Une action fait exception à la règle du JSON écrit à la main. Add as keyword, qui promeut un terme de recherche ou copie un mot-clé dans un autre groupe d’annonces, récupère ses groupes d’annonces cibles, son enchère et son type de correspondance depuis des marqueurs :

adapty asa automations create --file rule.json --target-ad-group <ad-group-id> --match-type EXACT --cpt-bid-type search_term_current_cpt --negate ad-group

Les mêmes flags sur automations update permettent de corriger une règle déjà enregistrée avec la mauvaise forme. Le CLI lit la règle, reconstruit l’action de zéro et la réécrit, en conservant uniquement les paramètres enregistrés compatibles avec une action Add as keyword :

adapty asa automations update <automation-id> --target-ad-group <ad-group-id> --match-type EXACT --cpt-bid-type search_term_current_cpt

Tout ce qui manquait à la règle défaillante doit provenir d’un flag. Consultez les commandes Ads Manager pour la liste complète.

Testez une règle avant de la laisser modifier les enchères :

adapty asa automations run <automation-id> --dry-run

Une exécution à blanc évalue les conditions et consigne ce que la règle ferait sans toucher à Apple Ads. Les exécutions sont mises en file d’attente plutôt qu’effectuées immédiatement, donc la commande affiche un identifiant d’exécution et le résultat apparaît dans adapty asa automations runs.

Ré-exécuter les scripts en toute sécurité

Chaque écriture envoie une clé d’idempotence. Le CLI en génère une par invocation et effectue une nouvelle tentative après une erreur réseau, ce qui garantit qu’une requête ayant échoué en transit n’est jamais appliquée deux fois.

Dans un script, définissez vous-même la clé pour pouvoir relancer tout le pipeline :

adapty asa campaigns create --org <campaign-group-id> --name "Winter push" --adam-id 123456 --country US --daily-budget 50 --idempotency-key winter-push-2026 --yes

Re-exécuter la même commande dans les 24 heures renvoie le résultat stocké et affiche Already applied earlier au lieu de créer une deuxième campagne. La même clé avec un corps différent échoue avec 422, ce qui permet de détecter un script modifié qui réutilise une clé par erreur.

Et maintenant ?

• Gérer Apple Ads avec un outil de code IA — installez le plugin Apple Ads pour que Claude Code, Copilot CLI, Codex ou Gemini CLI puissent exécuter ces commandes pour vous.
• Commandes Ads Manager — toutes les commandes avec leurs arguments, options et valeurs acceptées.
• Automatisations — ce que fait chaque type de règle et les actions qu’il peut déclencher.
• Métriques — les noms de métriques acceptés par --metric et le mode de calcul de chacune.