---
title: "Lệnh Ads Manager trong Adapty Developer CLI"
description: "Tài liệu tham khảo cho mọi lệnh adapty asa — chiến dịch, nhóm quảng cáo, từ khóa, quảng cáo, tự động hóa và chỉ số."
---

Bài viết này liệt kê mọi lệnh [Ads Manager](adapty-ads-manager) trong Adapty CLI, cùng các đối số, cờ và giá trị được chấp nhận. Các lệnh Ads Manager nằm trong chủ đề `adapty asa`.

:::link
Để biết điều kiện tiên quyết, các biện pháp ghi an toàn và ví dụ theo tác vụ, hãy xem [Quản lý Ads Manager từ CLI](developer-cli-ads-manager).
:::

Các lệnh này yêu cầu tài khoản Apple Ads đã được kết nối và gói đăng ký Ads Manager đang hoạt động. Chạy [`adapty asa whoami`](#adapty-asa-whoami) để kiểm tra cả hai. Để xem toàn bộ CLI, hãy xem [tài liệu tham khảo lệnh](developer-cli-reference).

## Cờ toàn cục \{#global-flags\}

Các cờ này khả dụng trên tất cả các lệnh Ads Manager.

| Cờ | Mô tả |
|---|---|
| `--json` | Xuất dưới dạng JSON thay vì văn bản định dạng |
| `--help` | Hiển thị trợ giúp lệnh |

Tất cả các lệnh `list` cũng chấp nhận cờ phân trang:

| Cờ | Mặc định | Mô tả |
|---|---|---|
| `--page` | `1` | Số trang |
| `--page-size` | `100` | Số mục mỗi trang (tối đa: 1000) |

Các trang Ads Manager có kích thước lớn hơn so với phần còn lại của CLI. Nên dùng một trang lớn thay vì lặp qua nhiều trang nhỏ.

Tất cả các lệnh thay đổi tài khoản của bạn đều chấp nhận các cờ sau:

| Cờ | Mô tả |
|---|---|
| `--yes`, `-y` | Áp dụng mà không cần xác nhận. Bắt buộc khi đầu ra được pipe hoặc dùng `--json` |
| `--idempotency-key` | Khóa cố định cho lần ghi này. Nếu lặp lại với cùng khóa và body trong vòng 24 giờ, sẽ trả về kết quả đã lưu thay vì áp dụng thay đổi lần nữa |

Các lệnh Ads Manager không nhận cờ `--app`. Phạm vi là công ty mà token của bạn thuộc về. `--app` chỉ tồn tại trên một số lệnh `list` với vai trò lọc dữ liệu.

## Bộ lọc danh sách \{#list-filters\}

Bộ lọc thu hẹp phạm vi truy vấn, không phải trang hiển thị. Nếu không áp dụng bộ lọc, `keywords list` sẽ phân trang qua toàn bộ từ khóa trong tài khoản, vì vậy hãy giới hạn mỗi lần đọc ở cấp độ bạn cần.

| Filter | Accepted by |
|---|---|
| `--campaign-group` | `campaigns`, `ad-groups`, `keywords`, `negative-keywords`, `search-terms`, `ads`, `creatives`, `product-pages` |
| `--app` | `campaigns`, `ad-groups`, `keywords`, `negative-keywords`, `search-terms`, `creatives`, `product-pages` |
| `--campaign` | `ad-groups`, `keywords`, `negative-keywords`, `search-terms`, `ads` |
| `--ad-group` | `keywords`, `negative-keywords`, `search-terms`, `ads` |
| `--status` | `campaigns`, `ad-groups`, `ads` (`ENABLED` hoặc `PAUSED`), `keywords` (`ACTIVE` hoặc `PAUSED`) |
| `--search` | `campaigns`, `ad-groups`, `keywords`, `negative-keywords`, `search-terms`, `ads`. Tìm kiếm chuỗi con theo tên, không phân biệt chữ hoa/thường |

`adapty asa apps list`, `orgs list`, `automations list`, và `automations runs` không nhận bộ lọc nào. Chúng chỉ chấp nhận các cờ phân trang.

`--campaign-group`, `--app`, `--campaign`, và `--ad-group` nhận các UUID được in ra bởi lệnh `list` tương ứng, và mỗi cờ có thể lặp lại nhiều lần:

```bash
adapty asa keywords list --ad-group <ad-group-id> --ad-group <other-ad-group-id>
```

Một ID thuộc về công ty khác sẽ không khớp với bất kỳ kết quả nào, vì vậy trang trả về rỗng thay vì báo lỗi.

## Tài khoản \{#account\}

### adapty asa whoami

Hiển thị công ty, cách cấp quyền truy cập Ads Manager và trạng thái kết nối với Apple Ads.

```bash
adapty asa whoami
```

Chạy lệnh này trước tiên. Lệnh sẽ báo cáo xem hai điều kiện tiên quyết cho mọi lệnh khác có được đáp ứng hay không.

### adapty asa connect

Liên kết tài khoản Apple Ads với Adapty.

```bash
adapty asa connect
```

Lệnh này in ra một đường dẫn ủy quyền Apple và chờ cho đến khi Apple báo cáo tài khoản đã được kết nối.

| Flag | Mặc định | Mô tả |
|---|---|---|
| `--wait` / `--no-wait` | `--wait` | Chờ cho đến khi Apple Ads báo cáo đã kết nối. `--no-wait` trả về ngay lập tức |
| `--timeout` | `300` | Số giây chờ cho bước trình duyệt |

### adapty asa orgs list

Liệt kê các nhóm chiến dịch (tổ chức Apple Ads) có sẵn cho công ty của bạn.

```bash
adapty asa orgs list
```

Mỗi hàng chứa hai định danh, và chúng không thể thay thế cho nhau:

| Field | Used as |
|---|---|
| `internal_id` | UUID mà `--org` nhận trên [`campaigns create`](#adapty-asa-campaigns-create), và `--campaign-group` nhận làm [bộ lọc danh sách](#list-filters) |
| `org_id` | ID tổ chức dạng số của Apple. Cả hai flag đều không chấp nhận giá trị này |

`--org` chỉ tồn tại trên `campaigns create`. Không có lệnh list nào chấp nhận nó.

Chấp nhận [pagination flags](#global-flags).

### adapty asa apps list

Liệt kê các ứng dụng được quảng bá trên Apple Ads.

```bash
adapty asa apps list
```

Mỗi hàng chứa hai định danh, và chúng không thể thay thế cho nhau:

| Trường | Dùng làm |
|---|---|
| `internal_id` | UUID mà `--app` nhận làm [bộ lọc danh sách](#list-filters) |
| `adam_id` | ID App Store dạng số của Apple, được `--adam-id` nhận vào lệnh [`campaigns create`](#adapty-asa-campaigns-create) và [`product-pages sync`](#adapty-asa-product-pages-sync) |

Chấp nhận [cờ phân trang](#global-flags).

## Chiến dịch \{#campaigns\}

### adapty asa campaigns list

Liệt kê các [chiến dịch](ads-manager-create-campaign). Chỉ trả về metadata — đọc số liệu hiệu suất bằng [`asa metrics`](#adapty-asa-metrics).

```bash
adapty asa campaigns list --app <app-id> --status PAUSED
```

Chấp nhận [cờ phân trang](#global-flags) và các [bộ lọc danh sách](#list-filters) `--campaign-group`, `--app`, `--search`, và `--status`.

### adapty asa campaigns get

Lấy thông tin chi tiết cho một chiến dịch cụ thể.

```bash
adapty asa campaigns get <campaign-id>
```

| Argument | Description |
|---|---|
| `campaign-id` | Campaign ID (UUID) |

### adapty asa campaigns create

Tạo một chiến dịch.

```bash
adapty asa campaigns create --org <campaign-group-id> --name "Winter push" --adam-id 123456 --country US --daily-budget 50
```

| Cờ | Bắt buộc | Mô tả |
|---|---|---|
| `--org` | Có | ID nhóm chiến dịch (UUID). Xem [`orgs list`](#adapty-asa-orgs-list) |
| `--name` | Có | Tên chiến dịch |
| `--adam-id` | Có | ID ứng dụng trên App Store (`adam_id`) |
| `--country` | Có | Mã quốc gia hoặc khu vực. Lặp lại để chọn nhiều: `--country US --country CA` |
| `--daily-budget` | Có | Ngân sách hàng ngày dưới dạng số tiền, ví dụ `50` hoặc `12.50` |
| `--budget` | Không | Ngân sách trọn đời |
| `--target-cpa` | Không | Chi phí mục tiêu trên mỗi lượt thu hút người dùng |
| `--currency` | Không | Mã tiền tệ cho các khoản tiền trong lần gọi này. Mặc định: `USD` |
| `--bidding-strategy` | Không | `MANUAL_CPT` hoặc `MAX_CONVERSIONS`. Apple mặc định là `MANUAL_CPT` |
| `--ad-channel-type` | Không | `SEARCH` hoặc `DISPLAY`. Mặc định: `SEARCH` |
| `--billing-event` | Không | `TAPS` hoặc `IMPRESSIONS`. Mặc định: `TAPS` |
| `--supply-source` | Không | Nguồn cung cấp, có thể lặp lại. Mặc định: `APPSTORE_SEARCH_RESULTS` |
| `--status` | Không | Trạng thái ban đầu: `ENABLED` hoặc `PAUSED` |

### adapty asa campaigns update

Cập nhật một chiến dịch hiện có.

```bash
adapty asa campaigns update <campaign-id> --daily-budget 80 --status PAUSED
```

| Đối số | Mô tả |
|---|---|
| `campaign-id` | ID chiến dịch (UUID) |

| Flag | Mô tả |
|---|---|
| `--name` | Tên chiến dịch mới |
| `--status` | `ENABLED` hoặc `PAUSED` |
| `--country` | Thay thế danh sách quốc gia. Lặp lại để chọn nhiều quốc gia |
| `--daily-budget` | Ngân sách hàng ngày mới |
| `--budget` | Ngân sách trọn đời mới |
| `--target-cpa` | Chi phí mục tiêu mới trên mỗi lượt chuyển đổi |
| `--bidding-strategy` | `MANUAL_CPT` hoặc `MAX_CONVERSIONS` |
| `--currency` | Mã tiền tệ cho các khoản tiền trong lần gọi này. Mặc định: `USD` |

Cần có ít nhất một flag.

## Nhóm quảng cáo \{#ad-groups\}

### adapty asa ad-groups list

Liệt kê [nhóm quảng cáo](ads-manager-create-ad-group). Chỉ trả về metadata — đọc số liệu hiệu suất bằng [`asa metrics`](#adapty-asa-metrics).

```bash
adapty asa ad-groups list --campaign <campaign-id>
```

Hỗ trợ [cờ phân trang](#global-flags) và các [bộ lọc danh sách](#list-filters) `--campaign-group`, `--app`, `--campaign`, `--search`, và `--status`.

### adapty asa ad-groups get

Lấy thông tin chi tiết cho một nhóm quảng cáo cụ thể.

```bash
adapty asa ad-groups get <ad-group-id>
```

| Argument | Description |
|---|---|
| `ad-group-id` | ID nhóm quảng cáo (UUID) |

### adapty asa ad-groups create

Tạo một nhóm quảng cáo trong một chiến dịch.

```bash
adapty asa ad-groups create --campaign <campaign-id> --name "Brand terms" --default-bid 1.20
```

| Cờ | Bắt buộc | Mô tả |
|---|---|---|
| `--campaign` | Có | ID chiến dịch (UUID) |
| `--name` | Có | Tên nhóm quảng cáo |
| `--default-bid` | Có | Giá thầu mặc định dưới dạng số tiền, ví dụ `1.20` |
| `--cpa-goal` | Không | Mục tiêu chi phí mỗi lần chuyển đổi |
| `--pricing-model` | Không | `CPC` hoặc `CPM`. Apple yêu cầu chỉ định một trong hai cho mỗi nhóm quảng cáo. Mặc định: `CPC` |
| `--start-time` | Không | Thời gian bắt đầu lịch chạy (`YYYY-MM-DD`). Mặc định là hôm nay |
| `--end-time` | Không | Thời gian kết thúc lịch chạy (`YYYY-MM-DD`) |
| `--automated-keywords` / `--no-automated-keywords` | Không | Cho phép Apple tự động thêm từ khóa |
| `--currency` | Không | Mã tiền tệ cho các số tiền trong lần gọi này. Mặc định: `USD` |
| `--status` | Không | Trạng thái ban đầu: `ENABLED` hoặc `PAUSED` |

### adapty asa ad-groups update

Cập nhật một nhóm quảng cáo hiện có.

```bash
adapty asa ad-groups update <ad-group-id> --default-bid 1.50 --status PAUSED
```

| Argument | Description |
|---|---|
| `ad-group-id` | ID nhóm quảng cáo (UUID) |

| Flag | Mô tả |
|---|---|
| `--name` | Tên nhóm quảng cáo mới |
| `--status` | `ENABLED` hoặc `PAUSED` |
| `--default-bid` | Giá thầu mặc định mới |
| `--cpa-goal` | Mục tiêu chi phí mỗi lần chuyển đổi mới |
| `--start-time` | Thời gian bắt đầu lịch trình (`YYYY-MM-DD`) |
| `--end-time` | Thời gian kết thúc lịch trình (`YYYY-MM-DD`) |
| `--automated-keywords` / `--no-automated-keywords` | Cho phép Apple tự động thêm từ khóa |
| `--currency` | Mã tiền tệ cho các số tiền trong lần gọi này. Mặc định: `USD` |

Cần có ít nhất một flag. Campaign cha được xác định trên server và không bao giờ được truyền vào.

## Từ khóa \{#keywords\}

Các lệnh từ khóa được áp dụng theo lô tối đa 100 mục mỗi lần gọi. Xem [Quản lý từ khóa](ads-manager-manage-keywords) để biết thao tác tương đương trên dashboard.

### adapty asa keywords list

Liệt kê các từ khóa targeting. Chỉ trả về metadata — đọc số liệu hiệu suất bằng [`asa metrics`](#adapty-asa-metrics).

```bash
adapty asa keywords list --ad-group <ad-group-id> --status ACTIVE
```

Chấp nhận [cờ phân trang](#global-flags) và các [bộ lọc danh sách](#list-filters) `--campaign-group`, `--app`, `--campaign`, `--ad-group`, `--search`, và `--status`. Lọc theo `--ad-group` — nếu không có bộ lọc, đây là truy vấn rộng nhất trong chủ đề này.

### adapty asa keywords add

Thêm từ khóa nhắm mục tiêu vào một nhóm quảng cáo.

```bash
adapty asa keywords add --ad-group <ad-group-id> --text "running shoes" --text "trail shoes" --bid 1.20
```

Đọc từ khóa từ một file, mỗi dòng một từ khóa:

```bash
adapty asa keywords add --ad-group <ad-group-id> --from-file keywords.txt
```

| Cờ | Bắt buộc | Mô tả |
|---|---|---|
| `--ad-group` | Có | ID nhóm quảng cáo (UUID). Chiến dịch được xác định từ đây |
| `--text` | Có, trừ khi dùng `--from-file` | Văn bản từ khóa. Lặp lại để thêm nhiều từ khóa |
| `--from-file` | Không | File chứa một từ khóa mỗi dòng. Kết hợp với các giá trị `--text` nếu có |
| `--bid` | Không | Giá thầu cho mỗi từ khóa dưới dạng số tiền thuần |
| `--match-type` | Không | `BROAD` hoặc `EXACT`. Mặc định: `BROAD` |
| `--currency` | Không | Mã tiền tệ cho các số tiền trong lần gọi này. Mặc định: `USD` |
| `--status` | Không | `ACTIVE` hoặc `PAUSED`. Mặc định: `ACTIVE` |

Một ID không hợp lệ sẽ khiến toàn bộ batch thất bại trước khi Apple được gọi. Apple vẫn có thể từ chối từng keyword riêng lẻ, và mỗi lần từ chối sẽ được báo cáo kèm lý do.

### adapty asa keywords update

Thay đổi giá thầu, trạng thái, văn bản hoặc loại khớp của một hoặc nhiều từ khóa.

```bash
adapty asa keywords update <keyword-id> <keyword-id> --bid 2.00 --status PAUSED
```

| Đối số | Mô tả |
|---|---|
| `keyword-id` | ID từ khóa (UUID). Truyền nhiều ID bằng cách thêm làm đối số bổ sung |

| Flag | Mô tả |
|---|---|
| `--bid` | Giá thầu mới |
| `--status` | `ACTIVE` hoặc `PAUSED` |
| `--match-type` | `BROAD` hoặc `EXACT` |
| `--text` | Văn bản từ khóa mới. Chỉ có ý nghĩa khi áp dụng cho một từ khóa duy nhất |
| `--currency` | Mã tiền tệ cho các giá trị trong lệnh gọi này. Mặc định: `USD` |

Một thay đổi được áp dụng cho mỗi ID được truyền vào.

## Từ khóa loại trừ \{#negative-keywords\}

### adapty asa negative-keywords list

Liệt kê các từ khóa phủ định. Các hàng có `ad_group_id` trống là cấp chiến dịch.

```bash
adapty asa negative-keywords list --campaign <campaign-id>
```

| Flag | Mô tả |
|---|---|
| `--campaign-level-only` | Chỉ giữ các hàng cấp chiến dịch |

Chấp nhận [pagination flags](#global-flags) và các [list filters](#list-filters) `--campaign-group`, `--app`, `--campaign`, `--ad-group`, và `--search`.

### adapty asa negative-keywords add

Thêm từ khóa phủ định vào một nhóm quảng cáo hoặc một chiến dịch.

```bash
adapty asa negative-keywords add --ad-group <ad-group-id> --text free
```

Áp dụng cho tất cả nhóm quảng cáo của một chiến dịch:

```bash
adapty asa negative-keywords add --campaign <campaign-id> --all-ad-groups --text free
```

| Flag | Bắt buộc | Mô tả |
|---|---|---|
| `--ad-group` | Một trong `--ad-group` hoặc `--campaign` | ID nhóm quảng cáo (UUID). Campaign sẽ được xác định từ đây |
| `--campaign` | Một trong `--ad-group` hoặc `--campaign` | ID campaign (UUID) |
| `--text` | Có | Văn bản từ khóa. Lặp lại để thêm nhiều từ khóa |
| `--all-ad-groups` | Không | Áp dụng cho mọi nhóm quảng cáo của campaign thay vì chính campaign. Yêu cầu `--campaign` |
| `--match-type` | Không | `BROAD` hoặc `EXACT`. Mặc định: `EXACT` |
| `--status` | Không | `ACTIVE` hoặc `PAUSED`. Mặc định: `ACTIVE` |

`--ad-group` và `--campaign` là hai tùy chọn loại trừ lẫn nhau. Chỉ truyền đúng một trong hai.

## Thuật ngữ tìm kiếm \{#search-terms\}

### adapty asa search-terms list

Liệt kê các cụm từ tìm kiếm đã kích hoạt quảng cáo của bạn. Dùng để tìm từ khóa mới và từ khóa phủ định mới.

```bash
adapty asa search-terms list --ad-group <ad-group-id> --date-from 2026-07-01 --date-to 2026-07-31
```

| Flag | Mặc định | Mô tả |
|---|---|---|
| `--date-from` | Hôm nay | Ngày bắt đầu kỳ báo cáo (`YYYY-MM-DD`) |
| `--date-to` | Hôm nay | Ngày kết thúc kỳ báo cáo (`YYYY-MM-DD`) |

Chấp nhận [flag phân trang](#global-flags) và các [bộ lọc danh sách](#list-filters) `--campaign-group`, `--app`, `--campaign`, `--ad-group`, và `--search`.

Lệnh này dùng chung pool phân tích với [`asa metrics`](#metrics). Xem [Lỗi](#errors).

## Quảng cáo \{#ads\}

### adapty asa ads list

Liệt kê [ads](ads-manager-manage-ads). Trường `serving_state_reasons` giải thích lý do tại sao một ad không chạy.

```bash
adapty asa ads list --ad-group <ad-group-id>
```

Chấp nhận [pagination flags](#global-flags) và các [list filters](#list-filters) `--campaign-group`, `--campaign`, `--ad-group`, `--search`, và `--status`. Danh sách này không có bộ lọc `--app` vì ads thuộc về ad groups.

### adapty asa ads get

Lấy thông tin chi tiết của một quảng cáo cụ thể.

```bash
adapty asa ads get <ad-id>
```

| Argument | Description |
|---|---|
| `ad-id` | Ad ID (UUID) |

### adapty asa ads create

Tạo một quảng cáo trong một nhóm quảng cáo.

```bash
adapty asa ads create --ad-group <ad-group-id> --creative-id 4321 --name "Summer ad"
```

| Flag | Required | Description |
|---|---|---|
| `--ad-group` | Yes | Ad group ID (UUID). The campaign is resolved from it |
| `--creative-id` | Yes | Apple creative ID. See [`creatives list`](#adapty-asa-creatives-list) |
| `--name` | Yes | Ad name |
| `--status` | No | Initial status: `ENABLED` or `PAUSED` |

### adapty asa ads update

Cập nhật một quảng cáo hiện có.

```bash
adapty asa ads update <ad-id> --status PAUSED
```

| Đối số | Mô tả |
|---|---|
| `ad-id` | ID quảng cáo (UUID) |

| Flag | Mô tả |
|---|---|
| `--name` | Tên quảng cáo mới |
| `--status` | `ENABLED` hoặc `PAUSED` |

Cần có ít nhất một flag. Creative và nhóm quảng cáo cha được cố định khi tạo.

## Creatives \{#creatives\}

### adapty asa creatives list

Liệt kê các creative có sẵn để tạo quảng cáo mới.

```bash
adapty asa creatives list --app <app-id>
```

`creative_id` trả về ở đây chính là giá trị `--creative-id` dùng cho [`ads create`](#adapty-asa-ads-create).

Chấp nhận [cờ phân trang](#global-flags) và các bộ lọc danh sách `--campaign-group` và `--app` trong [list filters](#list-filters).

## Trang sản phẩm \{#product-pages\}

### adapty asa product-pages list

Liệt kê các trang sản phẩm tùy chỉnh có sẵn cho ứng dụng của bạn.

```bash
adapty asa product-pages list --app <app-id>
```

Chấp nhận [cờ phân trang](#global-flags) và bộ lọc danh sách `--campaign-group` và `--app` trong phần [list filters](#list-filters).

### adapty asa product-pages sync

Làm mới các trang sản phẩm tùy chỉnh từ App Store Connect.

```bash
adapty asa product-pages sync --adam-id 123456
```

| Flag | Mô tả |
|---|---|
| `--adam-id` | Giới hạn việc làm mới cho một ứng dụng cụ thể. Bỏ qua để áp dụng cho tất cả ứng dụng |

Việc làm mới được đưa vào hàng đợi thay vì thực hiện ngay lập tức, và lệnh xác nhận bằng `Sync queued.` Nếu cùng một yêu cầu làm mới đang được xử lý, thay vào đó sẽ báo `Already running; nothing new was queued.`

## Tự động hóa \{#automations\}

CLI lưu trữ JSON quy tắc bạn cung cấp — nó không tự tạo quy tắc. Xem [Tự động hóa](ads-manager-automations) để biết từng loại quy tắc làm gì, và [Chạy quy tắc tự động hóa](developer-cli-ads-manager#run-automation-rules) để biết cách tạo file quy tắc.

### danh sách adapty asa automations \{#adapty-asa-automations-list\}

Liệt kê các [quy tắc tự động hóa](ads-manager-automations). Trường `status` có giá trị `1` là đang hoạt động và `0` là đã dừng.

```bash
adapty asa automations list
```

Chấp nhận [cờ phân trang](#global-flags).

### adapty asa automations get

Lấy thông tin một quy tắc tự động hóa cụ thể, bao gồm các điều kiện và hành động của nó.

```bash
adapty asa automations get <automation-id>
```

| Argument | Description |
|---|---|
| `automation-id` | Automation rule ID (UUID) |

### adapty asa automations create

Tạo một quy tắc tự động từ file JSON.

```bash
adapty asa automations create --file rule.json
```

| Flag | Mô tả |
|---|---|
| `--file` | File JSON chứa nội dung quy tắc, hoặc `-` để đọc từ standard input |
| `--run-now` | Xếp lần chạy đầu tiên vào hàng đợi ngay sau khi quy tắc được lưu |

`--file` là bắt buộc.

### adapty asa automations update

Thay đổi một quy tắc tự động: dừng, đổi tên, hoặc thay thế các phần của quy tắc.

```bash
adapty asa automations update <automation-id> --stop
```

| Đối số | Mô tả |
|---|---|
| `automation-id` | ID quy tắc tự động (UUID) |

| Flag | Mô tả |
|---|---|
| `--start` | Kích hoạt quy tắc |
| `--stop` | Dừng quy tắc và xóa lần chạy tiếp theo |
| `--name` | Tên quy tắc mới |
| `--file` | File JSON chứa các phần cần thay đổi, hoặc `-` để đọc từ standard input |

`--start` và `--stop` không thể dùng đồng thời. File truyền vào đây không được chứa `internal_id`.

### adapty asa automations run

Chạy một quy tắc tự động một lần, ngoài lịch trình của nó.

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

| Đối số | Mô tả |
|---|---|
| `automation-id` | ID quy tắc tự động (UUID) |

| Cờ | Mô tả |
|---|---|
| `--dry-run` | Đánh giá quy tắc và ghi lại kết quả mà không thay đổi bất kỳ điều gì trong Apple Ads |

Lần chạy được đưa vào hàng đợi, và lệnh in ra một run ID. Xem kết quả với [`automations runs`](#adapty-asa-automations-runs).

### adapty asa automations runs

Liệt kê các lần chạy trước đây của một quy tắc tự động hóa, bao gồm cả dry run.

```bash
adapty asa automations runs <automation-id>
```

| Đối số | Mô tả |
|---|---|
| `automation-id` | ID quy tắc tự động hóa (UUID) |

Chấp nhận [cờ phân trang](#global-flags).

## Chỉ số \{#metrics\}

### adapty asa metrics

Truy vấn các chỉ số cho bất kỳ cấp độ nào của tài khoản trong một khoảng thời gian.

```bash
adapty asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31
```

| Cờ | Bắt buộc | Mô tả |
|---|---|---|
| `--entity` | Có | Đối tượng cần báo cáo: `campaign`, `ad-group`, `keyword`, hoặc `ad` |
| `--date-from` | Có | Ngày bắt đầu kỳ báo cáo (`YYYY-MM-DD`) |
| `--date-to` | Có | Ngày kết thúc kỳ báo cáo (`YYYY-MM-DD`) |
| `--metric` | Không | Tên chỉ số, có thể lặp lại. Bỏ qua để lấy tất cả chỉ số |
| `--group-by` | Không | Phân nhóm các hàng theo `country`, `day`, `week`, `month`, `quarter`, hoặc `year`. Có thể lặp lại |
| `--by-days` | Không | Khoảng thời gian gia hạn tính bằng ngày cho các chỉ số cohort, có thể lặp lại. Tối đa 16 lần gọi. Bỏ qua để dùng giá trị mặc định của dashboard |
| `--order-by` | Không | Chỉ số hoặc trường dùng để sắp xếp |
| `--order-by-day` | Không | Xếp hạng theo chỉ số cohort tại khoảng thời gian gia hạn này. Phải là một trong các giá trị `--by-days` |
| `--order` | Không | `asc` hoặc `desc`. Mặc định: `desc` |

Chấp nhận [cờ phân trang](#global-flags). Lệnh này không nhận [bộ lọc danh sách](#list-filters) — hãy thu hẹp báo cáo theo cấp độ thực thể và khoảng thời gian, sau đó đối chiếu các hàng với ID từ lệnh `list` có phạm vi tương ứng.

Mỗi hàng là một thực thể, được tổng hợp trên máy chủ và sắp xếp theo `--order-by`. Vì vậy, câu hỏi top-N chỉ cần một lần gọi — đặt `--order-by` và `--page-size N` thay vì phân trang qua kết quả rồi cộng dồn:

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

`--metric` nhận tên các chỉ số mà Ads Manager theo dõi, theo tên trong dashboard — ví dụ `spend`, `taps`, hay `gross_roas`. Xem [Chỉ số](adapty-ads-manager-metrics) để biết danh sách đầy đủ và cách tính từng chỉ số. Tên không tồn tại sẽ báo lỗi kèm danh sách các tên hợp lệ.

Độ dài của kỳ báo cáo bị giới hạn bởi giá trị `--group-by` thô nhất. Để báo cáo cho kỳ dài hơn, hãy dùng nhóm thô hơn thay vì chia yêu cầu thành nhiều lần gọi:

| `--group-by` thô nhất | Khoảng thời gian tối đa |
|---|---|
| `day`, hoặc không có nhóm theo khoảng thời gian | 90 ngày |
| `week` | 180 ngày |
| `month` và thô hơn | 365 ngày |

Không có chỉ số `ltv`. Giá trị trọn đời là một chỉ số cohort được đọc tại một cửa sổ gia hạn, vì vậy `--by-days` là cách bạn yêu cầu giá trị ngày-7 hoặc ngày-90:

```bash
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` xếp hạng các hàng theo một trong những cửa sổ đó, trả về các chiến dịch hàng đầu theo ROAS ngày-90 chỉ trong một lần gọi.

### adapty asa metrics overview

Query totals for a period, bucketed by a unit of time.

```bash
adapty asa metrics overview --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --period-unit week
```

| Cờ | Bắt buộc | Mô tả |
|---|---|---|
| `--entity` | Có | Đối tượng báo cáo: `campaign`, `ad-group`, `keyword`, hoặc `ad` |
| `--date-from` | Có | Ngày bắt đầu kỳ (`YYYY-MM-DD`) |
| `--date-to` | Có | Ngày kết thúc kỳ (`YYYY-MM-DD`) |
| `--period-unit` | Không | Kích thước nhóm: `day`, `week`, `month`, `quarter`, hoặc `year`. Mặc định: `day` |
| `--metric` | Không | Tên chỉ số, có thể lặp lại. Bỏ qua để lấy tất cả chỉ số |
| `--by-days` | Không | Cửa sổ gia hạn tính bằng ngày cho các chỉ số cohort, có thể lặp lại. Tối đa 16 mỗi lần gọi |

Lệnh này trả về tổng hợp cho toàn bộ cấp độ entity cùng với một chuỗi theo từng kỳ, giúp trả lời câu hỏi "tôi đã chi tiêu hoặc thu được bao nhiêu tổng cộng" chỉ trong một lần gọi. Lệnh này không có cờ sắp xếp và không có phân trang.

Đối với lệnh này, `--metric` chỉ chấp nhận các cohort gốc — `revenue`, `roas`, và `arpu` — không chấp nhận các biến thể `gross_`, `proceeds_`, hoặc `net_` của chúng.

Độ dài của kỳ báo cáo bị giới hạn bởi `--period-unit`:

| `--period-unit` | Kỳ tối đa |
|---|---|
| `day` | 90 ngày |
| `week` | 180 ngày |
| `month` và thô hơn | 365 ngày |

## Đối thủ cạnh tranh \{#competitors\}

### adapty asa competitors summary

Tóm tắt các từ khóa Apple Ads mà một tập hợp ứng dụng App Store đang đặt giá thầu. Trả về dữ liệu đối thủ cạnh tranh giống như [Market Intelligence](ads-manager-market-intelligence) trên dashboard.

```bash
adapty asa competitors summary --app-ids 1668337467,6503873027
```

| Cờ | Bắt buộc | Mô tả |
|---|---|---|
| `--app-ids` | Có | ID Apple App Store (`adam_id`), phân cách bằng dấu phẩy. Từ 1 đến 5 giá trị |

Khoảng thời gian báo cáo và tập hợp quốc gia được cố định trên máy chủ — tháng đầy đủ gần nhất, trên tất cả các quốc gia. Lệnh này không có cờ về khoảng thời gian, quốc gia hay phân trang.

Lệnh in ra ba khối: tổng số liệu phân tích, các ứng dụng hàng đầu theo hiệu suất, và các từ khóa cạnh tranh nhất. Thêm `--json` để lấy kết quả đầy đủ, trong đó cũng phân tích từ khóa của từng ứng dụng theo quốc gia.

Lần gọi đầu tiên cho một tập hợp ứng dụng có thể mất vài chục giây trong khi dữ liệu đang được chuẩn bị. Các lần gọi sau cho cùng những ứng dụng đó sẽ nhanh hơn.

## Lỗi \{#errors\}

| Trạng thái | Mã | Ý nghĩa |
|---|---|---|
| `402` | `ads_manager_subscription_required` | Công ty không có gói đăng ký Ads Manager đang hoạt động |
| `404` | — | Thực thể không tồn tại, hoặc thuộc về một công ty khác |
| `409` | `cli_idempotency_in_progress` | Một yêu cầu ghi với cùng idempotency key đang được xử lý |
| `422` | `cli_idempotency_key_reuse` | Cùng một idempotency key đã được dùng với một request body khác |
| `429` | `cli_analytics_busy` | Pool analytics đang bận. Thời gian chờ nằm trong header `Retry-After` |
| `429` | `cli_cooldown_active` | Quá nhiều yêu cầu bị từ chối khiến token rơi vào trạng thái cool-down |

Chỉ số và danh sách từ khóa tìm kiếm dùng chung một ngân sách API theo từng công ty: 5 lần gọi mỗi phút, và tối đa 2 lần trong bất kỳ khoảng 10 giây nào. Nếu có 20 request bị từ chối trong vòng 5 phút, hệ thống sẽ kích hoạt cool-down theo cấp độ tăng dần: 5 phút, rồi 30 phút, rồi 3 tiếng. Retry trong thời gian chờ không kéo dài thêm thời gian đó, nhưng cách xử lý đúng là sửa request lỗi thay vì lặp lại nó.

CLI sẽ tự xử lý các lần chờ ngắn cho bạn. Khi nhận được `429` mà không phải cool-down, nếu `Retry-After` từ 60 giây trở xuống, lệnh sẽ chờ đúng thời gian đó rồi thử lại một lần, đồng thời thông báo thời gian chờ ra standard error.