---
title: "版位与市场细分命令"
description: "用于创建和更新版位及其目标受众，以及创建目标受众所针对的市场细分的 Adapty CLI 命令。"
---

> **AI agents**: to search Adapty docs faster and with fewer tokens, install the Adapty skills: `npx adapty skills install --yes`

这些 Adapty CLI 命令用于管理[版位](placements)、版位上的目标受众，以及目标受众所针对的[市场细分](segments)。

## 版位 \{#placements\}

[版位](placements)是您的流程、付费墙和用户引导触达用户的入口。版位的内容类型在创建时固定，因此将应用从付费墙迁移到流程意味着需要创建新版位，而非更新现有版位——[migrate-placements 技能](migrate-placements-skill)正是通过这些命令批量完成该操作的。

### adapty placements list

列出应用的所有[版位](placements)。

```bash
adapty placements list --app <app-id>
```

| 标志 | 是否必填 | 描述 |
|---|---|---|
| `--app` | 是 | 应用 ID（UUID） |

支持[分页标志](developer-cli-reference#global-flags)。

每条记录包含 `id`、`developer_id`、`title` 和 `is_active`。`is_active` 为 `true` 表示版位处于上线状态，为 `false` 表示版位处于未激活状态。

### adapty placements get

获取特定[版位](placements)的详细信息。

```bash
adapty placements get --app <app-id> <placement-id>
```

| 参数 | 描述 |
|---|---|
| `placement-id` | 版位 ID（UUID） |

| 标志 | 必填 | 描述 |
|---|---|---|
| `--app` | 是 | 应用 ID（UUID） |

响应包含 `id`、`developer_id`、`title`、`is_active` 以及一个 `audiences` 数组。`is_active` 为 `true` 表示版位处于上线状态，为 `false` 表示版位未激活。每个目标受众条目包含 `content_type`、`segment_ids`、`priority`，以及其内容的 ID：付费墙对应 `paywall_id`，流程对应 `flow_id`，运行 [A/B 测试](ab-tests) 的目标受众对应 `ab_test_id` 和 `ab_test_title`。默认目标受众的 `segment_ids: []`，且优先级值最高（最后被评估）。详见 [Audiences shape](#audiences-shape)。

### adapty placements create

创建新[版位](placements)。

```bash
adapty placements create --app <app-id> --title "Main" --developer-id "main" --audiences '[{"content_type":"paywall","segment_ids":[],"paywall_id":"<paywall-id>","priority":0}]'
```

| 参数 | 是否必填 | 说明 |
|---|---|---|
| `--app` | 是 | 应用 ID（UUID） |
| `--title` | 是 | 版位标题 |
| `--developer-id` | 是 | 在应用代码中用于请求此[版位](placements)的字符串标识符 |
| `--audiences` | 二选一 | 受众条目的 JSON 数组，每个条目需显式指定 `content_type`。详见[目标受众格式](#audiences-shape) |
| `--paywall-id` | 二选一 | **已废弃。**[付费墙](paywalls) ID（UUID）。客户端会将其包装为单个默认目标受众 |

`--audiences` 和 `--paywall-id` 必须且只能传其中一个，同时传入或都不传均会报错。

:::warning
`--paywall-id` 已弃用，将在后续版本中移除。传入该参数时，CLI 会在 stderr 输出警告，并将该值转换为默认目标受众。新的自动化流程请使用 `--audiences`。
:::

### adapty placements update

替换现有[版位](placements)的所有字段。

```bash
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}]'
```

此命令会替换版位的所有字段，包括完整的目标受众列表。

| 参数 | 描述 |
|---|---|
| `placement-id` | 版位 ID（UUID） |

| 参数 | 是否必填 | 描述 |
|---|---|---|
| `--app` | 是 | 应用 ID（UUID） |
| `--title` | 是 | 版位标题 |
| `--developer-id` | 是 | 在应用代码中用于请求该[版位](placements)的字符串标识符 |
| `--audiences` | 二选一 | 目标受众条目的 JSON 数组，每个条目需包含明确的 `content_type`。详见[目标受众结构](#audiences-shape) |
| `--paywall-id` | 二选一 | **已弃用。**[付费墙](paywalls) ID（UUID）。将所有目标受众替换为单个默认目标受众 |

:::warning
传入 `--paywall-id` 会覆盖版位上的所有目标受众，特定市场细分的目标受众将被移除。若要保留它们，请使用 `--audiences` 并将所有需要保留的条目一并传入。
:::

#### 目标受众结构 \{#audiences-shape\}

`--audiences` 参数接受一个 JSON 数组，每个条目包含：

| 字段 | 类型 | 描述 |
|---|---|---|
| `content_type` | `string` | 每个条目必填。`"paywall"`、`"flow"`、`"ab_test"`（付费墙 A/B 测试）、`"flow_ab_test"`（流程 A/B 测试）、`"cross_ab_test"` 或 `"flow_cross_ab_test"`（跨版位 A/B 测试）。在付费墙版位中使用 `paywall`、`ab_test` 和 `cross_ab_test`，在流程版位中使用 `flow`、`flow_ab_test` 和 `flow_cross_ab_test` |
| `segment_ids` | `string[]` | 此目标受众所针对的[市场细分](segments) ID。长度为 0 或 1。空数组表示**默认目标受众**——即未匹配任何其他市场细分的用户的兜底受众 |
| `paywall_id` | `string` | 向此目标受众用户展示的[付费墙](paywalls) ID（UUID）。当 `content_type` 为 `"paywall"` 时必填 |
| `flow_id` | `string` | 向此目标受众用户展示的[流程](adapty-flow-builder) ID（UUID）。当 `content_type` 为 `"flow"` 时必填 |
| `ab_test_id` | `string` | 针对此目标受众用户运行的 [A/B 测试](ab-tests) ID。四种 A/B 测试内容类型均必填 |
| `ab_test_title` | `string` | A/B 测试标题。只读：写入时 API 会忽略此字段 |
| `priority` | `number` | 从 0 开始，在版位内唯一。目标受众按从低到高的顺序依次评估；默认目标受众必须具有最高优先级值 |

每个版位必须有且只有一个默认目标受众。

:::warning
`placements update` 会替换完整的目标受众列表，包括正在运行 A/B 测试的目标受众。如需保留正在运行的测试，请从 `placements get` 中复制对应条目到 `--audiences`，保持 `ab_test_id` 和 `segment_ids` 不变。若写入时移除或替换了该条目，测试将在没有胜出者的情况下终止。若将该条目移至其他市场细分，测试将重新开始；若在另一个目标受众上设置了 `ab_test_id`，测试将在该目标受众处启动。若仅更改优先级，测试将继续运行。CLI 不会就上述情况发出任何警告。
:::

跨版位 A/B 测试条目（`cross_ab_test`、`flow_cross_ab_test`）为只读。API 在写入时会忽略这些条目，并保留已存储的值。

版位的内容类型在创建时即已固定，因此 `placements update` 无法将付费墙版位切换为流程版位，反之亦然。请为流程单独创建一个版位——详见[为你的流程创建新版位](migrate-to-flows#create-a-new-placement-for-your-flow)。

CLI 在发送请求前会对每条条目进行检查。若条目缺少或包含未知的 `content_type`，或者缺少 `content_type` 所要求的 ID，则退出码为 2，且不发送任何内容。对于未知的 `content_type`，CLI 会打印 `this CLI does not know this audience kind; update the CLI`。如果该条目来自 `placements get`，请更新 CLI 而非删除该条目：该条目可能对应一个正在运行的 A/B 测试。

一个流程只有在发布后才能被关联。处于 `draft` 状态的流程，或者首次发布仍在进行中的流程，将被服务器拒绝；CLI 会识别该拒绝并以退出码 2 退出，同时打印该流程的 `flows publish` 命令。要发布流程，请使用 [`flows publish`](developer-cli-flows#adapty-flows-publish) 或 [Flow & Paywall Builder](builder-save-publish)，然后等待其状态变为 `published`。

示例，包含一个定向目标受众和一个默认受众：

```bash
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}]'
```

向所有用户提供已发布流程的版位示例：

```bash
adapty placements create --app <app-id> --title "Onboarding" --developer-id "onboarding" \
  --audiences '[{"content_type":"flow","segment_ids":[],"flow_id":"<flow-id>","priority":0}]'
```

要在多个版位之间替换付费墙，同时保留细分受众的路由规则：

1. 找到受影响的版位：

   ```bash
   adapty paywalls placements --app <app-id> <old-paywall-id>
   ```

2. 对每个版位，读取完整的 `audiences` 数组：

   ```bash
   adapty placements get --app <app-id> <placement-id> --json
   ```

3. 在客户端替换匹配的 `paywall_id` 值。保持其他所有条目不变，包括 A/B 测试条目。

4. 将修改后的数据写回：

   ```bash
   adapty placements update --app <app-id> <placement-id> --title "<title>" --developer-id "<developer-id>" --audiences '<modified-payload>'
   ```

## 市场细分 \{#segments\}

[市场细分](segments)通过用户画像属性对用户进行分组。使用以下命令创建市场细分，或在编写[版位目标受众](#audiences-shape)时查找细分 ID。如需基于 Apple Ads 广告系列、广告组或关键词创建市场细分，请改用 [`adapty asa segments create`](developer-cli-ads-manager-reference#segments)：它会自动为您查找 Apple ID，并按 Ads Manager 的命名方式为细分命名。

### adapty segments list

列出应用的所有[市场细分](segments)。

```bash
adapty segments list --app <app-id>
```

| 参数 | 必填 | 描述 |
|---|---|---|
| `--app` | 是 | 应用 ID（UUID） |

支持[分页参数](developer-cli-reference#global-flags)。

### adapty segments get

获取特定[市场细分](segments)的详细信息。

```bash
adapty segments get --app <app-id> <segment-id>
```

| 参数 | 描述 |
|---|---|
| `segment-id` | 市场细分 ID（UUID） |

| 标志 | 是否必填 | 描述 |
|---|---|---|
| `--app` | 是 | 应用 ID（UUID） |

响应包含 `id`、`title`、`description`、`filters`、`profile_count`、`refresh_in_progress`、`created_at` 和 `updated_at`。`list` 仅返回 `id`、`title` 和 `description`。

### adapty segments create

从一个或多个过滤器创建[市场细分](segments)。

```bash
adapty segments create --app <app-id> --title "US installs" --filter ip_country:IN:US --filter install_date:>=:2026-01-01
```

| 参数 | 是否必填 | 描述 |
|---|---|---|
| `--app` | 是 | 应用 ID（UUID） |
| `--title` | 是 | 市场细分名称 |
| `--filter` | 是 | 过滤规则，可重复使用。详见[过滤器语法](#filter-syntax) |
| `--description` | 否 | 市场细分描述 |

只有当用户匹配所有筛选条件时，才会被纳入该市场细分。响应字段与 `segments get` 相同。`profile_count` 初始值为 `0`，Adapty 会在市场细分创建后重新计算该值。

### adapty segments update

替换现有[市场细分](segments)的标题、描述和过滤条件。

```bash
adapty segments update --app <app-id> <segment-id> --title "US installs" --filter ip_country:IN:US,CA
```

| 参数 | 描述 |
|---|---|
| `segment-id` | 市场细分 ID（UUID） |

| 标志 | 是否必填 | 描述 |
|---|---|---|
| `--app` | 是 | App ID（UUID） |
| `--title` | 是 | 市场细分标题 |
| `--filter` | 是 | 过滤规则，可重复使用。参见[过滤语法](#filter-syntax) |
| `--description` | 否 | 市场细分描述 |

:::warning
`segments update` 会替换整个市场细分。请传入所有要保留的筛选条件，而不仅仅是要修改的那个。如需查看当前筛选条件，请运行 `adapty segments get --app <app-id> <segment-id> --json`。
:::

#### 筛选语法 \{#filter-syntax\}

每个 `--filter` 的格式为 `field:OPERATOR:value`。若要匹配多个值，用逗号分隔：`ip_country:IN:US,CA`。

| 运算符 | 取值数量 | 示例 |
|---|---|---|
| `IN`, `NOT IN` | 一个或多个 | `ip_country:NOT IN:US,CA` |
| `>`, `>=`, `<`, `<=` | 一个 | `age:>:18` |
| `BETWEEN` | 两个 | `total_revenue_usd:BETWEEN:10,100` |
| `IS NULL`, `IS NOT NULL` | 无 | `age:IS NULL` |

数字请直接以纯数值传入，例如 `age:>:18`。Adapty 会自动将其转换为数值类型，适用于 `age`、`total_revenue_usd` 以及 float 类型的自定义属性。

如果某个筛选条件无法用上述简写形式表达，请将其以 JSON 对象的形式传入：

```bash
adapty segments create --app <app-id> --title "Adults" --filter '{"field_name":"age","operator":">","value_list":[18]}'
```

Adapty 会校验字段名、运算符和值类型，并对每个无效过滤条件单独报错。要查看现有过滤条件的字段名和值格式，可对看板中已创建的市场细分运行 `adapty segments get --app <app-id> <segment-id> --json`。

## 下一步 \{#whats-next\}

- [命令参考](developer-cli-reference) — 所有 CLI 主题、全局标志和分页标志。