Commandes pour les placements et les segments
Ces commandes CLI Adapty gèrent les placements, les audiences qui leur sont associées, et les segments ciblés par ces audiences.
Placements
Les placements sont les endroits où vos flows, paywalls et onboardings atteignent les utilisateurs. Le type de contenu d’un placement est fixé à la création ; faire passer une app des paywalls aux flows implique donc de créer de nouveaux placements plutôt que de modifier les existants — le skill migrate-placements pilote ces commandes pour le faire en masse.
Liste des placements Adapty
Liste tous les placements d’une application.
adapty placements list --app <app-id>
| Flag | Requis | Description |
|---|---|---|
--app | Oui | ID de l’application (UUID) |
--type | Non | Liste uniquement les placements de ce type : paywall, flow ou onboarding |
Accepte les options de pagination.
Chaque élément contient id, developer_id, title, is_active et type. is_active vaut true pour un placement actif et false pour un placement inactif. type désigne le type de contenu du placement : paywall, flow ou onboarding. En mode --json, un placement sans type a type: null. Le flag --type et le champ type nécessitent la version 0.15.0 ou supérieure de la CLI.
adapty placements get
Obtenez les détails d’un placement spécifique.
adapty placements get --app <app-id> <placement-id>
| Argument | Description |
|---|---|
placement-id | ID du placement (UUID) |
| Flag | Requis | Description |
|---|---|---|
--app | Oui | ID de l’application (UUID) |
La réponse contient id, developer_id, title, is_active, type, ainsi qu’un tableau audiences. is_active vaut true pour un placement actif et false pour un placement inactif. Chaque entrée d’audience comporte content_type, segment_ids, priority et l’identifiant de son contenu : paywall_id pour paywall, flow_id pour flow, ou ab_test_id et ab_test_title pour une audience qui exécute un test A/B. L’audience par défaut a segment_ids: [] et la valeur de priorité la plus élevée (évaluée en dernier). Voir Structure des audiences.
adapty placements create
Crée un nouveau placement.
adapty placements create --app <app-id> --title "Main" --developer-id "main" --audiences '[{"content_type":"paywall","segment_ids":[],"paywall_id":"<paywall-id>","priority":0}]'
| Flag | Obligatoire | Description |
|---|---|---|
--app | Oui | ID de l’app (UUID) |
--title | Oui | Titre du placement |
--developer-id | Oui | Identifiant string utilisé dans le code de l’app pour demander ce placement |
--audiences | L’un des deux | Tableau JSON d’entrées d’audience, chacune avec un content_type explicite. Voir Forme des audiences |
--paywall-id | L’un des deux | Obsolète. ID du paywall (UUID). Encapsulé côté client dans une seule audience par défaut |
Passez exactement l’un de --audiences ou --paywall-id. Passer les deux ou aucun génère une erreur.
--paywall-id est déprécié et sera supprimé. Lorsqu’il est fourni, la CLI affiche un avertissement sur stderr et convertit la valeur en audience par défaut. Utilisez --audiences pour les nouvelles automatisations.
adapty placements update
Remplace tous les champs d’un placement existant.
adapty placements update --app <app-id> <placement-id> --title "Main" --developer-id "main" --audiences '[{"content_type":"paywall","segment_ids":[],"paywall_id":"<paywall-id>","priority":0}]'
Cette commande remplace tous les champs du placement, y compris la liste complète des audiences.
| Argument | Description |
|---|---|
placement-id | ID du placement (UUID) |
| Flag | Requis | Description |
|---|---|---|
--app | Oui | ID de l’application (UUID) |
--title | Oui | Titre du placement |
--developer-id | Oui | Identifiant utilisé dans le code de l’application pour demander ce placement |
--audiences | L’un des deux | Tableau JSON d’entrées d’audience, chacune avec un content_type explicite. Voir Format des audiences |
--paywall-id | L’un des deux | Déprécié. ID du paywall (UUID). Remplace toutes les audiences par une seule audience par défaut |
Passer --paywall-id réécrit toutes les audiences du placement. Les audiences spécifiques aux segments sont supprimées. Pour les conserver, utilisez --audiences et incluez toutes les entrées que vous souhaitez garder.
Structure des audiences
Le flag --audiences prend un tableau JSON. Chaque entrée contient :
| Champ | Type | Description |
|---|---|---|
content_type | string | Requis pour chaque entrée. "paywall", "flow", "ab_test" (test A/B de paywall), "flow_ab_test" (test A/B de flow), "cross_ab_test" ou "flow_cross_ab_test" (test A/B inter-placement). Utilisez paywall, ab_test et cross_ab_test dans un placement de paywall, et flow, flow_ab_test et flow_cross_ab_test dans un placement de flow |
segment_ids | string[] | IDs de segment ciblés par cette audience. Longueur 0 ou 1. Un tableau vide indique l’audience par défaut — le fallback pour les utilisateurs qui ne correspondent à aucun autre segment |
paywall_id | string | ID (UUID) du paywall affiché aux utilisateurs de cette audience. Requis lorsque content_type vaut "paywall" |
flow_id | string | ID (UUID) du flow affiché aux utilisateurs de cette audience. Requis lorsque content_type vaut "flow" |
ab_test_id | string | ID du test A/B exécuté pour les utilisateurs de cette audience. Requis pour les quatre types de contenu test A/B |
ab_test_title | string | Titre du test A/B. Lecture seule : l’API l’ignore lors d’une écriture |
priority | number | Base 0, unique au sein du placement. Les audiences sont évaluées du plus petit au plus grand ; l’audience par défaut doit avoir la valeur la plus élevée |
Un placement doit avoir exactement une audience par défaut.
placements update remplace la liste complète des audiences, y compris celles qui font tourner un test A/B. Pour conserver un test en cours, copiez son entrée depuis placements get dans --audiences sans la modifier, avec les mêmes ab_test_id et segment_ids. Une écriture qui supprime ou remplace cette entrée arrête le test sans désigner de gagnant. Une écriture qui déplace l’entrée vers d’autres segments relance le test, et un ab_test_id sur une autre audience démarre le test là. Une écriture qui ne modifie que les priorités laisse le test tourner. La CLI ne vous avertit pas dans ces cas.
Les entrées de test A/B croisé (cross_ab_test, flow_cross_ab_test) sont en lecture seule. L’API les ignore lors d’une écriture et conserve celles qui sont stockées.
Le type de contenu d’un placement est fixé à sa création, donc placements update ne peut pas faire passer un placement de paywall à un flow, ni l’inverse. Servez le flow depuis un placement qui lui est propre — voir Créer un nouveau placement pour votre flow.
Le CLI vérifie chaque entrée avant d’envoyer la requête. Une entrée avec un content_type manquant ou inconnu, ou sans l’ID requis par son content_type, provoque une sortie avec le code 2 et rien n’est envoyé. Pour un content_type qu’il ne reconnaît pas, le CLI affiche this CLI does not know this audience kind; update the CLI. Si l’entrée provient de placements get, mettez à jour le CLI plutôt que de supprimer l’entrée : celle-ci peut correspondre à un test A/B en cours.
Un flow ne peut être associé qu’après avoir été publié. Un flow en état draft, ou dont la première publication est encore en cours, est rejeté par le serveur ; le CLI reconnaît ce rejet et quitte avec le code 2, en affichant la commande flows publish correspondant à ce flow. Pour publier un flow, utilisez flows publish ou le Flow & Paywall Builder, puis attendez que son statut passe à published.
Exemple avec une audience ciblée et une audience par défaut :
adapty placements update <placement-id> --app <app-id> --title "Main" --developer-id "main" \
--audiences '[{"content_type":"paywall","segment_ids":["<vip-segment-id>"],"paywall_id":"<vip-paywall-id>","priority":0},{"content_type":"paywall","segment_ids":[],"paywall_id":"<default-paywall-id>","priority":1}]'
Exemple de placement qui sert un flow publié à tous les utilisateurs :
adapty placements create --app <app-id> --title "Onboarding" --developer-id "onboarding" \
--audiences '[{"content_type":"flow","segment_ids":[],"flow_id":"<flow-id>","priority":0}]'
Pour remplacer un paywall dans plusieurs placements sans perdre le routage par segment :
-
Trouvez les placements concernés :
adapty paywalls placements --app <app-id> <old-paywall-id> -
Pour chacun, lisez le tableau
audiencescomplet :adapty placements get --app <app-id> <placement-id> --json -
Remplacez les valeurs
paywall_idcorrespondantes côté client. Laissez toutes les autres entrées inchangées, y compris les entrées de test A/B. -
Réécrivez le payload modifié :
adapty placements update --app <app-id> <placement-id> --title "<title>" --developer-id "<developer-id>" --audiences '<modified-payload>'
liste des métriques de placements adapty
Affiche les métriques cumulées de plusieurs placements de flow ou de paywall, une ligne par placement. Ce sont les données du tableau des placements dans le tableau de bord.
adapty placements metrics list --app <app-id> --type flow --ids <placement-id>,<placement-id>
| Flag | Requis | Description |
|---|---|---|
--app | Oui | ID de l’application (UUID) |
--type | Oui | Type de placement, tel qu’affiché par placements list : flow ou paywall |
--ids | Oui | IDs des placements (UUIDs). Séparez-les par des virgules ou répétez le flag |
--csv | Non | Affiche un CSV : une ligne par placement, avec l’ID du placement et les métriques numériques. Ne peut pas être utilisé avec --json |
Les commandes placements metrics lisent les chiffres de la page métriques de placement. Elles nécessitent la version 0.15.0 ou ultérieure de la CLI pour les placements de flow et la version 0.16.0 ou ultérieure pour les placements de paywall. --type doit correspondre au type du placement : Adapty refuse un placement d’un autre type et ne dispose d’aucune métrique pour les placements d’onboarding.
Chaque ligne affiche l’identifiant du placement avec ses vues, achats, essais et revenus. Pour un placement de flow, --json et --csv contiennent l’ensemble des 27 métriques.
Une ligne d’accès à vie d’un placement de paywall n’a pas de vues, donc sa colonne de vues affiche —. Elle comporte 15 métriques, telles que purchases, revenue et refunds. Pour lire les visiteurs d’un placement de paywall, utilisez placements metrics get avec une période.
adapty placements metrics values
Répertorie les clés et valeurs de filtre d’un placement de flow ou d’un placement de paywall : ce que placements metrics get --filter accepte.
adapty placements metrics values --app <app-id> <placement-id> --type flow
| Argument | Description |
|---|---|
placement-id | ID du placement (UUID) |
| Flag | Requis | Description |
|---|---|---|
--app | Oui | ID de l’app (UUID) |
--type | Oui | Type de placement : flow ou paywall |
La sortie a la même forme que flows metrics values : la valeur en tête de chaque groupe est la clé de filtre, et les valeurs les plus imbriquées correspondent à ce que la clé accepte. Un placement sans clé de filtre affiche No filter values.
adapty placements metrics get
Affiche les métriques d’un placement de flow ou d’un placement de paywall sous forme d’arborescence, comme sur la page des métriques de placement. Un placement de flow couvre toute sa durée de vie ou une période donnée. Un placement de paywall couvre une période donnée.
adapty placements metrics get --app <app-id> <placement-id> --type flow --based-on flow
| Argument | Description |
|---|---|
placement-id | Identifiant du placement (UUID) |
| Flag | Requis | Description |
|---|---|---|
--app | Oui | ID de l’application (UUID) |
--type | Oui | Type de placement : flow ou paywall |
--based-on | Oui | Ce sur quoi se divise le premier niveau de l’arbre. Pour un placement de type flow : audience, flow ou placement. Pour un placement de type paywall : audience ou paywall |
--group-by | Non | Pour un placement de type flow, diviser chaque audience par country ou store. Pour un placement de type paywall, regrouper les produits par product, store ou country |
--date-from | Non | Premier jour de la période, inclus (YYYY-MM-DD). À utiliser avec --date-to et --date-type |
--date-to | Non | Dernier jour de la période, inclus (YYYY-MM-DD). À utiliser avec --date-from et --date-type |
--date-type | Non | La date à laquelle s’applique la période : purchase_date ou profile_install_date. À utiliser avec --date-from et --date-to |
--granularity | Non | Découper la période en points : day, week, month, quarter ou year |
--filter | Non | Ne conserver que les données correspondant à ces valeurs de filtre. Répétable. Voir Filtrer les métriques |
--timezone | Non | Fuseau horaire IANA des points de la période, par exemple Europe/Berlin. Sans ce paramètre, Adapty utilise le fuseau horaire de l’application |
--depth | Non | Nombre de niveaux de l’arbre à afficher sous Total. Par défaut : 1 |
--csv | Non | Afficher en CSV : une ligne par nœud de l’arbre complet. Incompatible avec --json |
Pour un placement de type flow, la commande renvoie les métriques sur toute la durée de vie sans --date-from, --date-to ni --date-type. Pour une période, passez les trois : une période sans --date-type sort avec le code 4. Un placement de type paywall nécessite toujours les trois, et sort avec le code 4 sans eux.
Pour un placement de type flow, la sortie, --depth, --json, --csv et --filter fonctionnent comme dans flows metrics get. Pour un placement de type paywall, ils fonctionnent comme dans paywalls metrics get. Par exemple, pour comparer les audiences d’un placement par store :
adapty placements metrics get --app <app-id> <placement-id> --type flow --based-on audience --group-by store \
--date-from 2026-09-01 --date-to 2026-10-21 --date-type purchase_date --depth 2
Pour lire chaque branche d’un test A/B sur un placement de paywall, divisez l’arbre par paywall. Sous chaque paywall, la ligne du test A/B affiche les chiffres de cette branche :
adapty placements metrics get --app <app-id> <placement-id> --type paywall --based-on paywall \
--date-from 2026-09-01 --date-to 2026-10-21 --date-type purchase_date --depth 3
Le total de l’ensemble du test A/B apparaît sur sa propre ligne dans l’arborescence --based-on audience. Ce total compte chaque utilisateur une seule fois, il peut donc être inférieur à la somme des variantes : un utilisateur ayant vu les deux variantes est comptabilisé dans chacune d’elles.
Segments
Les segments regroupent les utilisateurs selon leurs attributs de profil. Utilisez ces commandes pour créer des segments et retrouver leurs identifiants lors de la composition des audiences de placement. Pour créer un segment à partir de campagnes, groupes d’annonces ou mots-clés Apple Ads, utilisez plutôt adapty asa segments create : cette commande recherche automatiquement les identifiants Apple et nomme le segment comme le fait Ads Manager.
adapty segments list
Listez tous les segments d’une application.
adapty segments list --app <app-id>
| Flag | Required | Description |
|---|---|---|
--app | Yes | App ID (UUID) |
Accepte les options de pagination.
adapty segments get
Obtenez les détails d’un segment spécifique.
adapty segments get --app <app-id> <segment-id>
| Argument | Description |
|---|---|
segment-id | ID du segment (UUID) |
| Flag | Requis | Description |
|---|---|---|
--app | Oui | ID de l’application (UUID) |
La réponse contient id, title, description, filters, profile_count, refresh_in_progress, created_at et updated_at. La commande list retourne uniquement id, title et description.
adapty segments create
Créez un segment à partir d’un ou plusieurs filtres.
adapty segments create --app <app-id> --title "US installs" --filter ip_country:IN:US --filter install_date:>=:2026-01-01
| Flag | Requis | Description |
|---|---|---|
--app | Oui | ID de l’application (UUID) |
--title | Oui | Titre du segment |
--filter | Oui | Règle de filtre. Répétable. Voir Syntaxe des filtres |
--description | Non | Description du segment |
Un utilisateur correspond au segment uniquement s’il correspond à chaque filtre. La réponse contient les mêmes champs que segments get. profile_count commence à 0, et Adapty le recalcule après la création du segment.
adapty segments update
Remplacez le titre, la description et les filtres d’un segment existant.
adapty segments update --app <app-id> <segment-id> --title "US installs" --filter ip_country:IN:US,CA
| Argument | Description |
|---|---|
segment-id | ID du segment (UUID) |
| Flag | Requis | Description |
|---|---|---|
--app | Oui | ID de l’app (UUID) |
--title | Oui | Titre du segment |
--filter | Oui | Règle de filtre. Répétable. Voir Syntaxe des filtres |
--description | Non | Description du segment |
segments update remplace l’intégralité du segment. Transmettez tous les filtres que vous souhaitez conserver, pas seulement celui que vous modifiez. Pour lire les filtres actuels, exécutez adapty segments get --app <app-id> <segment-id> --json.
Syntaxe des filtres
Écrivez chaque --filter sous la forme field:OPERATOR:value. Pour correspondre à plusieurs valeurs, séparez-les par des virgules : ip_country:IN:US,CA.
| Opérateur | Valeurs | Exemple |
|---|---|---|
IN, NOT IN | Une ou plusieurs | ip_country:NOT IN:US,CA |
>, >=, <, <= | Une | age:>:18 |
BETWEEN | Deux | total_revenue_usd:BETWEEN:10,100 |
IS NULL, IS NOT NULL | Aucune | age:IS NULL |
Passez les nombres comme valeurs brutes, par exemple age:>:18. Adapty les convertit pour les champs numériques comme age, total_revenue_usd et les attributs personnalisés de type float.
Pour une valeur que cette forme courte ne peut pas exprimer, passez le filtre sous forme d’objet JSON :
adapty segments create --app <app-id> --title "Adults" --filter '{"field_name":"age","operator":">","value_list":[18]}'
Adapty valide les noms de champs, les opérateurs et les types de valeurs, et signale une erreur pour chaque filtre invalide. Pour voir les noms de champs et les formats de valeurs des filtres existants, exécutez adapty segments get --app <app-id> <segment-id> --json sur un segment créé dans le tableau de bord.
Et ensuite
- Référence des commandes — tous les sujets CLI, les options globales et les options de pagination.