Comandos de placements y segmentos
Estos comandos de la CLI de Adapty gestionan los placements, las audiencias de los mismos y los segmentos a los que apuntan esas audiencias.
Placements
Los placements son los puntos donde tus flows, paywalls y onboardings llegan a los usuarios. El tipo de contenido de un placement se fija en el momento de su creación, por lo que migrar una app de paywalls a flows implica crear nuevos placements en lugar de actualizar los existentes — el skill migrate-placements ejecuta estos comandos en bloque.
Lista de placements de Adapty
Lista todos los placements de una aplicación.
adapty placements list --app <app-id>
| Flag | Requerido | Descripción |
|---|---|---|
--app | Sí | ID de la app (UUID) |
--type | No | Lista solo los placements de este tipo: paywall, flow u onboarding |
Acepta flags de paginación.
Cada elemento contiene id, developer_id, title, is_active y type. is_active es true para un placement activo y false para uno inactivo. type es el tipo de contenido del placement: paywall, flow u onboarding. En --json, un placement sin tipo tiene type: null. El flag --type y el campo type requieren la versión 0.15.0 o posterior de la CLI.
adapty placements get
Obtén los detalles de un placement específico.
adapty placements get --app <app-id> <placement-id>
| Argumento | Descripción |
|---|---|
placement-id | ID del placement (UUID) |
| Flag | Obligatorio | Descripción |
|---|---|---|
--app | Sí | ID de la app (UUID) |
La respuesta contiene id, developer_id, title, is_active, type y un array audiences. is_active es true para un placement activo y false para uno inactivo. Cada entrada de audiencia incluye content_type, segment_ids, priority y el ID de su contenido: paywall_id para paywall, flow_id para flow, o ab_test_id y ab_test_title para una audiencia que ejecuta una prueba A/B. La audiencia predeterminada tiene segment_ids: [] y el valor de prioridad más alto (la última en evaluarse). Consulta Formato de audiencias.
adapty placements create
Crea un nuevo placement.
adapty placements create --app <app-id> --title "Main" --developer-id "main" --audiences '[{"content_type":"paywall","segment_ids":[],"paywall_id":"<paywall-id>","priority":0}]'
| Indicador | Obligatorio | Descripción |
|---|---|---|
--app | Sí | ID de la app (UUID) |
--title | Sí | Título del placement |
--developer-id | Sí | Identificador de cadena usado en el código de la app para solicitar este placement |
--audiences | Uno de los dos | Array JSON de entradas de audiencia, cada una con un content_type explícito. Ver Formato de audiencias |
--paywall-id | Uno de los dos | Obsoleto. ID del paywall (UUID). Se envuelve en el lado del cliente en una única audiencia predeterminada |
Pasa exactamente uno de --audiences o --paywall-id. Pasar ambos o ninguno devuelve un error.
--paywall-id está en desuso y será eliminado. Al utilizarlo, la CLI muestra una advertencia en stderr y convierte el valor en una audiencia predeterminada. Usa --audiences para nueva automatización.
adapty placements update
Reemplaza todos los campos de un placement existente.
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}]'
Este comando reemplaza todos los campos del placement, incluida la lista completa de audiencias.
| Argumento | Descripción |
|---|---|
placement-id | ID del placement (UUID) |
| Flag | Obligatorio | Descripción |
|---|---|---|
--app | Sí | ID de la app (UUID) |
--title | Sí | Título del placement |
--developer-id | Sí | Identificador de cadena utilizado en el código de la app para solicitar este placement |
--audiences | Uno de los dos | Array JSON de entradas de audiencia, cada una con un content_type explícito. Ver Forma de audiencias |
--paywall-id | Uno de los dos | Obsoleto. ID del paywall (UUID). Reemplaza todas las audiencias con una única audiencia predeterminada |
Pasar --paywall-id reescribe todas las audiencias del placement. Las audiencias específicas de segmento se eliminan. Para conservarlas, usa --audiences e incluye todas las entradas que quieras mantener.
Estructura de audiences
El flag --audiences acepta un array JSON. Cada entrada tiene:
| Campo | Tipo | Descripción |
|---|---|---|
content_type | string | Obligatorio en cada entrada. "paywall", "flow", "ab_test" (prueba A/B de paywall), "flow_ab_test" (prueba A/B de flow), "cross_ab_test" o "flow_cross_ab_test" (prueba A/B de placement cruzado). Usa paywall, ab_test y cross_ab_test en un placement de paywall, y flow, flow_ab_test y flow_cross_ab_test en un placement de flow |
segment_ids | string[] | IDs de segmento a los que se dirige esta audiencia. Longitud 0 o 1. Un array vacío indica la audiencia predeterminada — el fallback para usuarios que no coinciden con ningún otro segmento |
paywall_id | string | ID (UUID) del paywall que se muestra a los usuarios de esta audiencia. Obligatorio cuando content_type es "paywall" |
flow_id | string | ID (UUID) del flow que se muestra a los usuarios de esta audiencia. Obligatorio cuando content_type es "flow" |
ab_test_id | string | ID de la prueba A/B que se ejecuta para los usuarios de esta audiencia. Obligatorio en los cuatro tipos de contenido de prueba A/B |
ab_test_title | string | Título de la prueba A/B. Solo lectura: la API lo ignora al escribir |
priority | number | Basado en 0, único dentro del placement. Las audiencias se evalúan de menor a mayor; la audiencia predeterminada debe tener el valor más alto |
Un placement debe tener exactamente una audiencia predeterminada.
placements update reemplaza la lista completa de audiencias, incluidas las que tienen una prueba A/B en curso. Para mantener una prueba activa, copia su entrada desde placements get a --audiences sin modificarla, con el mismo ab_test_id y los mismos segment_ids. Una escritura que elimine o reemplace esa entrada detiene la prueba sin ganador. Una escritura que mueva la entrada a otros segmentos reinicia la prueba, y un ab_test_id en otra audiencia la inicia allí. Una escritura que solo cambie las prioridades mantiene la prueba en curso. La CLI no avisa sobre ninguno de estos casos.
Las entradas de prueba A/B entre placements (cross_ab_test, flow_cross_ab_test) son de solo lectura. La API las ignora al escribir y conserva las almacenadas.
El tipo de contenido de un placement se fija al crearlo, por lo que placements update no puede cambiar un placement de paywall a un flow ni viceversa. Sirve el flow desde un placement propio; consulta Crear un nuevo placement para tu flow.
El CLI verifica cada entrada antes de enviar la solicitud. Una entrada con un content_type faltante o desconocido, o sin el ID que su content_type requiere, termina con código 2 y no se envía nada. Para un content_type que no reconoce, el CLI imprime this CLI does not know this audience kind; update the CLI. Si la entrada proviene de placements get, actualiza el CLI en lugar de eliminar la entrada: puede ser una prueba A/B en ejecución.
Un flow solo puede vincularse después de haber sido publicado. El servidor rechaza un flow en estado draft o cuya primera publicación aún está en curso; el CLI reconoce ese rechazo y sale con el código 2, imprimiendo el comando flows publish para ese flow. Para publicar un flow, usa flows publish o el Flow & Paywall Builder y espera a que su estado sea published.
Ejemplo con una audiencia específica y una predeterminada:
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}]'
Ejemplo de un placement que sirve un flow publicado a todos los usuarios:
adapty placements create --app <app-id> --title "Onboarding" --developer-id "onboarding" \
--audiences '[{"content_type":"flow","segment_ids":[],"flow_id":"<flow-id>","priority":0}]'
Para intercambiar un paywall en varios placements sin perder el enrutamiento específico por segmento:
-
Encuentra los placements afectados:
adapty paywalls placements --app <app-id> <old-paywall-id> -
Para cada uno, lee el array completo de
audiences:adapty placements get --app <app-id> <placement-id> --json -
Reemplaza los valores
paywall_idcoincidentes en el cliente. Deja todas las demás entradas sin cambios, incluidas las entradas de pruebas A/B. -
Escribe el payload modificado de nuevo:
adapty placements update --app <app-id> <placement-id> --title "<title>" --developer-id "<developer-id>" --audiences '<modified-payload>'
Lista de métricas de placements de Adapty
Muestra las métricas de vida útil de varios placements de flow o varios placements de paywall, una línea por cada placement. Estos son los datos de la tabla de placements en el dashboard.
adapty placements metrics list --app <app-id> --type flow --ids <placement-id>,<placement-id>
| Flag | Obligatorio | Descripción |
|---|---|---|
--app | Sí | ID de la app (UUID) |
--type | Sí | Tipo de placement, tal como lo muestra placements list: flow o paywall |
--ids | Sí | IDs de placement (UUIDs). Sepáralos con comas o repite el flag |
--csv | No | Muestra CSV: una fila por placement, con el ID del placement y las métricas numéricas. No se puede usar con --json |
Los comandos placements metrics leen los números de la página de métricas de placement. Requieren la versión 0.15.0 o posterior de la CLI para placements de flow y la 0.16.0 o posterior para placements de paywall. --type debe coincidir con el tipo de placement: Adapty rechaza un placement de otro tipo y no tiene métricas para placements de onboarding.
Cada línea muestra el ID del placement con sus vistas, compras, trials y revenue. Para un placement de flow, --json y --csv incluyen las 27 métricas.
Una fila de por vida de un placement de paywall no tiene vistas, por lo que su columna de vistas muestra —. Incluye 15 métricas, como purchases, revenue y refunds. Para consultar los visitantes de un placement de paywall, usa placements metrics get con un período.
adapty placements metrics values
Lista las claves y valores de filtro de un placement de flow o de paywall: lo que acepta placements metrics get --filter.
adapty placements metrics values --app <app-id> <placement-id> --type flow
| Argumento | Descripción |
|---|---|
placement-id | ID del placement (UUID) |
| Flag | Obligatorio | Descripción |
|---|---|---|
--app | Sí | ID de la app (UUID) |
--type | Sí | Tipo de placement: flow o paywall |
El resultado tiene el mismo formato que flows metrics values: el valor superior de cada grupo es la clave de filtro, y los valores más internos son los que toma dicha clave. Un placement sin claves de filtro muestra No filter values.
adapty placements metrics get
Muestra las métricas de un placement de flow o de paywall como el árbol de la página de métricas de placement. Un placement de flow abarca toda su vida útil o un período. Un placement de paywall abarca un período.
adapty placements metrics get --app <app-id> <placement-id> --type flow --based-on flow
| Argument | Description |
|---|---|
placement-id | Placement ID (UUID) |
| Flag | Obligatorio | Descripción |
|---|---|---|
--app | Sí | ID de la app (UUID) |
--type | Sí | Tipo de placement: flow o paywall |
--based-on | Sí | Por qué se divide el primer nivel del árbol. Para un placement de tipo flow: audience, flow o placement. Para un placement de tipo paywall: audience o paywall |
--group-by | No | Para un placement de tipo flow, divide cada audiencia por country o store. Para un placement de tipo paywall, agrupa los productos por product, store o country |
--date-from | No | Primer día del período, inclusive (YYYY-MM-DD). Úsalo junto con --date-to y --date-type |
--date-to | No | Último día del período, inclusive (YYYY-MM-DD). Úsalo junto con --date-from y --date-type |
--date-type | No | A qué fecha se aplica el período: purchase_date o profile_install_date. Úsalo junto con --date-from y --date-to |
--granularity | No | Divide el período en puntos: day, week, month, quarter o year |
--filter | No | Conserva solo los datos con estos valores de una clave de filtro. Repetible. Consulta Filtrar las métricas |
--timezone | No | Zona horaria IANA de los puntos del período, por ejemplo Europe/Berlin. Sin este parámetro, Adapty utiliza la zona horaria de la app |
--depth | No | Cuántos niveles del árbol se muestran bajo Total. Valor por defecto: 1 |
--csv | No | Imprime CSV: una fila por cada nodo del árbol completo. No se puede usar con --json |
Para un placement de tipo flow, el comando devuelve las métricas de por vida sin --date-from, --date-to ni --date-type. Para un período, pasa los tres: un período sin --date-type sale con código 4. Un placement de tipo paywall siempre necesita los tres, y sale con código 4 sin ellos.
Para un placement de tipo flow, la salida, --depth, --json, --csv y --filter funcionan como en flows metrics get. Para un placement de tipo paywall, funcionan como en paywalls metrics get. Por ejemplo, para comparar las audiencias de un placement por 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
Para leer cada rama de una prueba A/B en un placement de paywall, divide el árbol por paywall. Bajo cada paywall, la línea de la prueba A/B muestra los números de esa rama:
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
El total del conjunto de la prueba A/B aparece en su propia línea en el árbol --based-on audience. Ese total cuenta a cada usuario una sola vez, por lo que puede ser inferior a la suma de las variantes: un usuario que vio ambas variantes se contabiliza en cada una de ellas.
Segmentos
Los segmentos agrupan usuarios según los atributos de su perfil. Usa estos comandos para crear segmentos y buscar IDs de segmento al componer audiencias de placement. Para crear un segmento a partir de campañas, grupos de anuncios o palabras clave de Apple Ads, usa adapty asa segments create en su lugar: busca automáticamente los IDs de Apple y asigna al segmento el nombre que usa Ads Manager.
Lista de segmentos de Adapty
Lista todos los segmentos de una app.
adapty segments list --app <app-id>
| Flag | Obligatorio | Descripción |
|---|---|---|
--app | Sí | ID de la app (UUID) |
Acepta flags de paginación.
adapty segments get
Obtén los detalles de un segmento específico.
adapty segments get --app <app-id> <segment-id>
| Argumento | Descripción |
|---|---|
segment-id | ID del segmento (UUID) |
| Flag | Obligatorio | Descripción |
|---|---|---|
--app | Sí | ID de la app (UUID) |
La respuesta contiene id, title, description, filters, profile_count, refresh_in_progress, created_at y updated_at. list devuelve únicamente id, title y description.
adapty segments create
Crea un segmento a partir de uno o más filtros.
adapty segments create --app <app-id> --title "US installs" --filter ip_country:IN:US --filter install_date:>=:2026-01-01
| Flag | Obligatorio | Descripción |
|---|---|---|
--app | Sí | ID de la app (UUID) |
--title | Sí | Título del segmento |
--filter | Sí | Regla de filtro. Repetible. Ver Sintaxis de filtros |
--description | No | Descripción del segmento |
Un usuario pertenece al segmento solo cuando cumple todos los filtros. La respuesta tiene los mismos campos que segments get. profile_count empieza en 0, y Adapty lo recalcula después de que se crea el segmento.
adapty segments update
Reemplaza el título, la descripción y los filtros de un segmento existente.
adapty segments update --app <app-id> <segment-id> --title "US installs" --filter ip_country:IN:US,CA
| Argumento | Descripción |
|---|---|
segment-id | ID del segmento (UUID) |
| Flag | Obligatorio | Descripción |
|---|---|---|
--app | Sí | ID de la app (UUID) |
--title | Sí | Título del segmento |
--filter | Sí | Regla de filtro. Repetible. Ver Sintaxis de filtros |
--description | No | Descripción del segmento |
segments update reemplaza el segmento completo. Pasa todos los filtros que quieras conservar, no solo el que modificas. Para leer los filtros actuales, ejecuta adapty segments get --app <app-id> <segment-id> --json.
Sintaxis de filtros
Escribe cada --filter como field:OPERATOR:value. Para coincidir con varios valores, sepáralos con comas: ip_country:IN:US,CA.
| Operador | Valores | Ejemplo |
|---|---|---|
IN, NOT IN | Uno o más | ip_country:NOT IN:US,CA |
>, >=, <, <= | Uno | age:>:18 |
BETWEEN | Dos | total_revenue_usd:BETWEEN:10,100 |
IS NULL, IS NOT NULL | Ninguno | age:IS NULL |
Pasa los números como valores simples, por ejemplo age:>:18. Adapty los convierte para campos numéricos como age, total_revenue_usd y atributos personalizados de tipo float.
Para un valor que esta forma abreviada no pueda expresar, pasa el filtro como un objeto JSON:
adapty segments create --app <app-id> --title "Adults" --filter '{"field_name":"age","operator":">","value_list":[18]}'
Adapty valida los nombres de campo, los operadores y los tipos de valor, y reporta un error por cada filtro inválido. Para ver los nombres de campo y los formatos de valor de los filtros existentes, ejecuta adapty segments get --app <app-id> <segment-id> --json en un segmento creado en el dashboard.
¿Qué sigue?
- Referencia de comandos — todos los temas de la CLI, los flags globales y los flags de paginación.