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

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 để kiểm tra cả hai. Để xem phần còn lại của CLI, hãy tham khảo tài liệu tham khảo lệnh.

Cờ toàn cục

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 output đượ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ại

Các lệnh Ads Manager không có 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 như một bộ lọc. Các lệnh segments là ngoại lệ: ở đó, --app là ứng dụng Adapty mà phân khúc đó thuộc về.

Bộ lọc danh sách

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:

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

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.

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.

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.

adapty asa orgs list

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

Trường	Dùng làm
internal_id	UUID mà --org nhận vào ở lệnh campaigns create, và mà --campaign-group nhận làm bộ lọc danh sách
org_id	ID tổ chức dạng số của Apple, được --org-id nhận vào ở lệnh campaigns bulk-create. --org và --campaign-group không chấp nhận giá trị này

--org chỉ có trong lệnh campaigns create. Không có lệnh liệt kê nào chấp nhận tham số này.

Mỗi hàng cũng có trường payment_model. Khi giá trị là LOC, tổ chức thanh toán theo hạn mức tín dụng, và mọi campaign trong đó đều cần các cờ --invoice-*.

Chấp nhận cờ phân trang.

adapty asa apps list

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

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
adam_id	ID App Store dạng số của Apple, được --adam-id nhận vào lệnh campaigns create và product-pages sync

Chấp nhận cờ phân trang.

Chiến dịch

adapty asa campaigns list

Liệt kê các chiến dịch. Chỉ trả về metadata — đọc số liệu hiệu suất bằng asa metrics.

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

Chấp nhận cờ phân trang và các bộ lọc danh sách --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ể.

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.

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
--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 theo số tiền thực tế, 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 mỗi lượt chuyển đổi. Phải thấp hơn --daily-budget
--currency	Không	Mã tiền tệ cho các số 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
--invoice-advertiser	Hạn mức tín dụng	Tùy chọn thanh toán hóa đơn: tên nhà quảng cáo
--invoice-order-number	Hạn mức tín dụng	Tùy chọn thanh toán hóa đơn: số đơn hàng
--invoice-contact-name	Hạn mức tín dụng	Tùy chọn thanh toán hóa đơn: tên người liên hệ của người mua
--invoice-contact-email	Hạn mức tín dụng	Tùy chọn thanh toán hóa đơn: email người liên hệ của người mua
--invoice-billing-email	Hạn mức tín dụng	Tùy chọn thanh toán hóa đơn: email liên hệ thanh toán

Một tổ chức có payment_model là LOC thanh toán theo hạn mức tín dụng, và Apple yêu cầu Tùy chọn Thanh toán cho từng chiến dịch. Truyền đủ cả năm flag --invoice-* trong một lần gọi — nếu thiếu bất kỳ flag nào, yêu cầu sẽ bị từ chối trước khi được gửi đi. Xem Đặt Tùy chọn Thanh toán cho hạn mức tín dụng.

Phản hồi trả về serving_status và serving_state_reasons. Một campaign có thể được tạo nhưng vẫn chưa phục vụ quảng cáo: campaign theo MAX_CONVERSIONS sẽ chờ nhóm quảng cáo được tạo tự động, còn campaign theo hình thức line-of-credit sẽ chờ Invoicing Options được thiết lập. Trong cả hai trường hợp, lệnh sẽ in ra lý do và lệnh cần thực hiện để giải quyết.

adapty asa campaigns update

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

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 để thêm 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 trên mỗi lần mua lại mới
--bidding-strategy	MANUAL_CPT hoặc MAX_CONVERSIONS
--currency	Mã tiền tệ cho các số tiền trong lệnh gọi này. Mặc định: USD
--invoice-advertiser	Tùy chọn hóa đơn: tên nhà quảng cáo
--invoice-order-number	Tùy chọn hóa đơn: số đơn hàng
--invoice-contact-name	Tùy chọn hóa đơn: tên liên hệ người mua
--invoice-contact-email	Tùy chọn hóa đơn: email liên hệ người mua
--invoice-billing-email	Tùy chọn hóa đơn: email liên hệ thanh toán

Ít nhất một flag là bắt buộc.

Năm flag --invoice-* đi cùng nhau và thay thế toàn bộ Invoicing Options đã lưu, vì vậy hãy truyền cả năm flag ngay cả khi chỉ muốn thay đổi một trong số chúng. Một tập hợp không đầy đủ sẽ bị từ chối trước khi yêu cầu được gửi đi.

adapty asa campaigns bulk-create

Tạo toàn bộ cấu trúc chiến dịch — các chiến dịch với nhóm quảng cáo, từ khóa, từ khóa phủ định và quảng cáo lồng nhau — trong một thao tác duy nhất.

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

Chuyển đổi từ template bulk của Apple Ads thay vì tự viết JSON:

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

Cờ	Mặc định	Mô tả
--file	—	File JSON chứa cấu trúc chiến dịch, hoặc - để đọc từ đầu vào tiêu chuẩn
--from-file	—	Template bulk Apple Ads để chuyển đổi trên server: Campaign_And_Adgroup_Template.xlsx hoặc một file keywords .csv
--org-id	—	ID tổ chức dạng số của Apple (org_id). Xem orgs list. Bắt buộc khi dùng --from-file
--preview	—	Dùng với --from-file: in cấu trúc đã chuyển đổi và dừng lại. Không có gì được tạo ra
--wait / --no-wait	--wait	Theo dõi thao tác cho đến khi hoàn thành. --no-wait in ID thao tác và trả về
--poll-interval	5	Số giây giữa các lần kiểm tra tiến độ
--timeout	900	Số giây tối đa để chờ thao tác hoàn thành

Chính xác một trong hai tùy chọn --file và --from-file là bắt buộc.

Cấu trúc đặt tên nhóm chiến dịch ở cấp cao nhất và lồng tất cả các phần còn lại vào bên trong:

{
  "campaign_group_id": 555777,
  "campaigns": [
    {
      "payload": {
        "name": "US Search",
        "adam_id": 123456,
        "countries_or_regions": ["US"],
        "daily_budget_amount": { "amount": "100", "currency": "USD" },
        "status": "ENABLED",
        "ad_channel_type": "SEARCH",
        "billing_event": "TAPS",
        "supply_sources": ["APPSTORE_SEARCH_RESULTS"]
      },
      "ad_groups": [
        {
          "payload": { "name": "Brand", "start_time": "2026-08-01T00:00:00Z", "status": "ENABLED" },
          "keywords": [{ "text": "meditation app", "match_type": "BROAD" }]
        }
      ]
    }
  ]
}

campaign_group_id nhận ID tổ chức dạng số của Apple; dùng campaign_group_internal_id để truyền UUID thay thế. Một node có payload sẽ được tạo mới. Một node chỉ định thực thể đã tồn tại bằng id của nó là một anchor — dùng anchor để thêm ad group vào một campaign đã có, và thêm update_payload để thay đổi thực thể đó trong cùng một thao tác. Mỗi campaign lồng ad_groups, và mỗi ad group lồng keywords, negative_keywords, và ads. Một campaign cũng nhận negative_keywords trực tiếp cho các từ khóa loại trừ ở cấp campaign.

Toàn bộ cấu trúc được xác thực trước khi tạo bất kỳ thứ gì, và danh sách từ chối sẽ liệt kê mọi node không hợp lệ. Với --from-file, các vấn đề chuyển đổi sẽ được báo cáo kèm sheet, row và column tương ứng; cảnh báo chuyển đổi không dừng việc gửi, nhưng lỗi chuyển đổi sẽ hủy bỏ nó. Trước khi gửi, lệnh sẽ báo cáo số lượng campaign, ad group, keyword, negative keyword và ad trong cấu trúc, đồng thời yêu cầu xác nhận.

Lệnh sau đó sẽ poll operation và in tiến trình cho đến khi đạt một trong ba trạng thái kết thúc:

Trạng thái	Ý nghĩa
success	Mọi đối tượng đã được tạo thành công
partial	Một số đối tượng chưa được tạo. Mỗi lỗi được in kèm thông báo lỗi từ Apple
failed	Thao tác thất bại và lệnh thoát với mã khác 0

Nếu thao tác chưa hoàn thành sau --timeout giây, lệnh sẽ trả về và in ra lệnh bulk-status để chạy sau.

adapty asa campaigns bulk-status

Hiển thị tiến trình của một thao tác bulk: trạng thái, số lượng đối tượng, và nhật ký theo từng đối tượng.

adapty asa campaigns bulk-status <operation-id>

Đối số	Mô tả
operation-id	ID thao tác (UUID) được in ra bởi campaigns bulk-create

Trường status có giá trị là pending, running, success, partial, hoặc failed. Khối counts báo cáo số lượng đối tượng đã áp dụng, thất bại và đang chờ xử lý trên tổng số.

Chấp nhận cờ phân trang.

Nhóm quảng cáo

adapty asa ad-groups list

Liệt kê nhóm quảng cáo. Chỉ trả về metadata — đọc số liệu hiệu suất bằng asa metrics.

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

Hỗ trợ cờ phân trang và các bộ lọc danh sách --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ể.

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.

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

Flag	Bắt buộc	Mô tả
--campaign	Có	Campaign ID (UUID)
--name	Có	Tên nhóm quảng cáo
--default-bid	Trừ khi dùng --automated	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ọn một trong mỗi nhóm quảng cáo. Mặc định: CPC
--start-time	Không	Thời điểm bắt đầu lịch chạy (YYYY-MM-DD). Mặc định là hôm nay
--end-time	Không	Thời điểm 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
--automated	Không	Tạo nhóm quảng cáo tự động mà campaign MAX_CONVERSIONS cần
--currency	Không	Mã tiền tệ cho các số tiền trong lệnh này. Mặc định: USD
--status	Không	Trạng thái ban đầu: ENABLED hoặc PAUSED

--automated chọn nhóm quảng cáo tham gia từ khóa tự động, do đó không thể kết hợp với --automated-keywords. Apple tự lên lịch cho nhóm quảng cáo tự động và giữ nó ở trạng thái bật, vì vậy --start-time và --status PAUSED sẽ bị từ chối — hãy tạm dừng chiến dịch thay thế. Xem Tạo chiến dịch Max Conversions.

adapty asa ad-groups update

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

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

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 để 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 keywords list --ad-group <ad-group-id> --status ACTIVE

Chấp nhận cờ phân trang và các bộ lọc danh sách --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 recommend

Lấy danh sách từ khóa có sẵn cho một trong các ứng dụng của bạn. Đây là các pool từ khóa mà Ads Manager sử dụng khi bạn thiết lập chiến dịch trên dashboard.

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

Flag	Bắt buộc	Mô tả
--adam-id	Có	ID App Store của Apple (adam_id) cho ứng dụng của bạn, lấy từ asa apps list
--type	Có	brand, generic, hoặc competitor
--country	Không	Mã quốc gia ISO hai chữ cái. Lặp lại để chọn nhiều quốc gia. Mặc định: tất cả các quốc gia trong pool

Cờ --type chọn pool:

Loại	Từ khóa
brand	Các từ khóa thương hiệu của ứng dụng, các biến thể chính tả và các từ khóa tự nhiên có chứa thương hiệu. Kết quả cũng liệt kê chính các từ khóa thương hiệu đó
generic	Các từ khóa không mang thương hiệu mà ứng dụng của bạn và các đối thủ cạnh tranh tự nhiên hàng đầu đang xếp hạng, đã loại bỏ toàn bộ từ khóa thương hiệu. relevance_tier: top_organic đánh dấu những từ khóa mà ứng dụng của bạn đã xếp hạng trong top 10 tự nhiên
competitor	Các từ khóa thương hiệu của từng đối thủ cạnh tranh được chọn cho ứng dụng trong AI Growth Advisor, mỗi đối thủ một nhóm riêng. Trống cho đến khi bạn chọn đối thủ cạnh tranh

Mỗi từ khóa đi kèm với quốc gia, mức độ phổ biến, điểm số và thứ hạng tự nhiên trung vị. Các từ khóa không có giá thầu hay loại đối sánh. Bạn tự chọn những thông số này, sau đó thêm từ khóa bằng asa keywords add.

Kiểm tra status của pool trước khi sử dụng từ khóa:

Status	Ý nghĩa
ready	Pool đã được xây dựng xong
building	Pool vẫn đang được xây dựng. Thử lại sau khoảng một phút
empty	Pool đã được xây dựng xong nhưng không có từ khóa nào
failed	Quá trình xây dựng thất bại. Thử lại sau

Lần gọi brand hoặc generic đầu tiên cho một ứng dụng sẽ khởi tạo pool trong quá trình xử lý yêu cầu và có thể mất vài chục giây. Lệnh này có giới hạn 10 lần gọi mỗi phút cho mỗi công ty, và chỉ có một lần build brand hoặc generic chạy tại một thời điểm cho mỗi công ty. Nếu có lần build thứ hai trong khoảng thời gian đó, hệ thống sẽ trả về 429 cli_analytics_busy với Retry-After: 5.

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.

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:

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.

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ừ

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.

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 và các 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.

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:

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

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.

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 và các bộ lọc danh sách --campaign-group, --app, --campaign, --ad-group, và --search.

Ngoài các chỉ số hiệu suất, mỗi hàng từ khóa tìm kiếm còn mang theo thông tin phân tích của Apple cho từ khóa đó:

Trường	Giá trị
impression_share_all, impression_share_first	Tỷ lệ hiển thị ở bất kỳ vị trí quảng cáo nào, hoặc ở vị trí quảng cáo đầu tiên
impression_midpoint_all, impression_midpoint_first	Tỷ lệ hiển thị dưới dạng một phần trăm đơn lẻ
rank_all, rank_first	Thứ hạng ứng dụng của bạn so với các ứng dụng khác cho từ khóa đó, ở bất kỳ vị trí quảng cáo nào hoặc ở vị trí đầu tiên
search_popularity	Độ phổ biến tìm kiếm từ 1 đến 5

Mỗi trường là null khi Apple không có dữ liệu cho chỉ số đó. Xem Insights để biết Apple định nghĩa các giá trị này như thế nào.

Lệnh này dùng chung bộ phân tích với asa metrics. Xem Errors.

Quảng cáo

adapty asa ads list

Liệt kê ads. Trường serving_state_reasons giải thích lý do tại sao một ad không chạy.

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

Chấp nhận pagination flags và các 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ể.

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.

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
--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ó.

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

adapty asa creatives list

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

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

creative_id trả về ở đây chính là giá trị --creative-id dùng cho ads create.

Chấp nhận cờ phân trang và các bộ lọc danh sách --campaign-group và --app trong list filters.

Trang sản phẩm

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.

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

Chấp nhận cờ phân trang và bộ lọc danh sách --campaign-group và --app trong phần 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.

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.

Phân khúc

Các lệnh này tạo phân khúc Adapty từ các chiến dịch, nhóm quảng cáo hoặc từ khóa của Apple Ads — tương tự như Create segment from… trong Ads Manager. Sử dụng các phân khúc làm đối tượng trong placement và A/B test để hiển thị paywall khác nhau cho người dùng đến từ một chiến dịch cụ thể.

Mỗi phân khúc có một bộ lọc attribution theo Apple ID của các thực thể bạn chọn. CLI sẽ tra cứu các ID đó, vì vậy bạn cần truyền vào các UUID được in ra bởi lệnh list.

Không giống các lệnh adapty asa khác, những lệnh này nhận tham số --app: ID của ứng dụng Adapty mà phân khúc thuộc về, lấy từ adapty apps list. Chúng không hỗ trợ --idempotency-key. Đối với các phân khúc có bộ lọc khác như quốc gia hoặc ngày cài đặt, hãy dùng adapty segments create.

adapty asa segments create

Tạo một phân khúc từ các chiến dịch, nhóm quảng cáo, hoặc từ khóa.

adapty asa segments create --app <app-id> --campaign <campaign-id>
adapty asa segments create --app <app-id> --ad-group <ad-group-id> --keyword <keyword-id> --keyword <other-keyword-id>

Flag	Required	Description
--app	Yes	Adapty app ID (UUID)
--campaign	Một loại thực thể	Campaign ID (UUID). Có thể lặp lại
--ad-group	Một loại thực thể	Ad group ID (UUID). Có thể lặp lại. Khi dùng với --keyword, chỉ truyền đúng một: ad group chứa các keyword
--keyword	Một loại thực thể	Keyword ID (UUID). Có thể lặp lại. Yêu cầu một --ad-group
--title	No	Tiêu đề phân khúc. Mặc định theo định dạng Ads Manager, ví dụ [ASA] Campaign: <name>
--description	No	Mô tả phân khúc. Mặc định theo định dạng Ads Manager

Hãy tạo mỗi phân khúc từ một loại thực thể. Truyền đồng thời --campaign và --ad-group, hoặc --campaign với --keyword, sẽ thất bại với mã thoát 2 trước khi gửi bất kỳ yêu cầu nào. Nhiều thực thể cùng loại sẽ tạo ra một phân khúc khớp với người dùng từ bất kỳ thực thể nào trong số đó.

Giữ tiêu đề mặc định trừ khi bạn cần tiêu đề khác. Ads Manager nhận diện các phân khúc của mình thông qua tiền tố [ASA], và asa segments list chỉ liệt kê các phân khúc có tiền tố này.

Phản hồi chứa toàn bộ phân khúc, bao gồm id và filters. profile_count bắt đầu từ 0, và Adapty sẽ tính toán lại sau khi phân khúc được tạo.

adapty asa segments update

Thay thế các chiến dịch, nhóm quảng cáo hoặc từ khóa của một phân khúc hiện có.

adapty asa segments update <segment-id> --app <app-id> --campaign <campaign-id> --campaign <other-campaign-id>

Đối số	Mô tả
segment-id	ID phân khúc (UUID), lấy từ asa segments list hoặc adapty segments list

Nhận các flag tương tự như asa segments create. Bộ lọc của phân khúc sẽ được thay thế bằng các thực thể bạn truyền vào. Tiêu đề và mô tả vẫn giữ nguyên trừ khi bạn truyền --title hoặc --description.

adapty asa segments list

Liệt kê các phân khúc được tạo từ các thực thể Apple Ads — những phân khúc có tiêu đề bắt đầu bằng [ASA].

adapty asa segments list --app <app-id> --campaign <campaign-id>

Flag	Bắt buộc	Mô tả
--app	Có	ID ứng dụng Adapty (UUID)
--campaign	Không	Chỉ giữ lại các phân khúc được xây dựng từ campaign này (UUID)
--ad-group	Không	Chỉ giữ lại các phân khúc được xây dựng từ ad group này (UUID)

Truyền --campaign hoặc --ad-group, không truyền cả hai. Để tránh tạo phân khúc thứ hai cho cùng một chiến dịch, hãy chạy lệnh này trước asa segments create: kết quả rỗng nghĩa là chiến dịch chưa có phân khúc nào.

Lệnh này đọc 100 phân khúc đầu tiên của ứng dụng.

Tự động hóa

CLI lưu trữ JSON quy tắc bạn cung cấp, với một ngoại lệ: cài đặt của hành động Add as keyword đến từ các flag. Xem Tự động hóa để biết từng loại quy tắc làm gì, và Chạy quy tắc tự động hóa để biết cách tạo tệp quy tắc.

Cờ tham số hành động add-as-keyword

automations create và automations update dùng chung một tập cờ để thiết lập actions[0].params cho hành động add-as-keyword-to — Add as keyword trong quy tắc search terms, Add as keyword to… trong quy tắc keyword. Truyền bất kỳ cờ nào trong số này sẽ thay thế toàn bộ object params, vì vậy hành động này không cần JSON viết tay.

Cờ	Trường JSON	Mô tả
--target-ad-group	targets.internal_ids	Ad group nhận keyword (UUID), có thể lặp lại. Một rule không có target ad group sẽ không làm gì
--match-type	match_type	BROAD hoặc EXACT
--cpt-bid-type	cpt_bid.type	Nguồn gốc của bid cho keyword mới: ad_group_default_bid, set_to, search_term_current_cpt, hoặc keyword_current_bid
--cpt-bid	cpt_bid.value	Với set_to, là giá trị bid. Với search_term_current_cpt hoặc keyword_current_bid, là phần trăm markup trên bid đang được sao chép. Không được chấp nhận với ad_group_default_bid
--negate	negate	Đồng thời thêm search term dưới dạng negative keyword, trong ad-group riêng của nó hoặc campaign riêng của nó. --no-negate không để lại gì. Chỉ áp dụng cho search terms rules
--skip-enable-duplicates	skip_enable_duplicate_keywords	Bỏ qua keyword đã tồn tại trong target ad group thay vì kích hoạt nó. Chỉ áp dụng cho search terms rules
--pause-original	pause_in_original_ad_group	Tạm dừng keyword nguồn trong ad group của chính nó. Chỉ áp dụng cho keyword rules

--cpt-bid-type và --match-type không có giá trị mặc định, vì vậy cả hai đều bắt buộc khi file rule không có params riêng.

Bốn flag này phụ thuộc vào trường operate_with của rule: --negate, --no-negate, và --skip-enable-duplicates thuộc về rule search-term, còn --pause-original thuộc về rule targeting-keyword. Nếu dùng flag thuộc nhóm kia, lệnh sẽ thất bại với exit code 2 kèm danh sách các flag thực sự áp dụng.

danh sách adapty asa automations

Liệt kê các quy tắc tự động hóa. Trường status có giá trị 1 là đang hoạt động và 0 là đã dừng.

adapty asa automations list

Chấp nhận cờ phân trang.

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ó.

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 hóa từ file quy tắc JSON.

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 hàng lần chạy đầu tiên ngay sau khi quy tắc được lưu

--file là bắt buộc, và file phải chứa đúng một action: API chỉ giữ một action và một điều kiện cho mỗi quy tắc.

Cũng chấp nhận các flag action add-as-keyword, dùng để điền hoặc ghi đè actions[0].params:

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

adapty asa automations update

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

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 của nó
--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ừ đầu vào chuẩn

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

Cũng chấp nhận các cờ hành động add-as-keyword. Truyền một cờ sẽ biến lệnh gọi thành thao tác đọc-sửa-ghi: CLI đọc rule, xây dựng lại actions[0].params, rồi gửi toàn bộ danh sách actions trở lại, vì API thay thế actions thay vì merge vào. Mọi chỉnh sửa được thực hiện trên dashboard trong khoảng thời gian giữa lần đọc và lần ghi sẽ bị ghi đè.

An update with an action flag also repairs a rule whose stored params carry the shape of another action. The params are rebuilt from scratch, so only the stored keys that fit add-as-keyword-to are kept and everything else has to come from a flag.

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ó.

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

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.

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.

Chỉ số

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.

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

Flag	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	Có	Tên chỉ số, có thể lặp lại
--app	Không	Chỉ báo cáo cho các app này. Có thể lặp lại
--campaign	Không	Chỉ báo cáo cho các campaign này. Có thể lặp lại
--ad-group	Không	Chỉ báo cáo cho các ad group này. Có thể lặp lại
--group-by	Không	Phân tách các hàng theo country, day, week, month, quarter, hoặc year. Có thể lặp lại
--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 lần mỗi 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 để sắp xếp
--order-by-day	Không	Xếp hạng theo chỉ số cohort tại cửa sổ 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ác cờ phân trang. Trong số các bộ lọc danh sách, lệnh này chỉ nhận --app, --campaign và --ad-group; không có --search và không có --status. Để thu hẹp báo cáo theo tiêu chí khác, hãy lọc các hàng theo ID lấy từ lệnh list có phạm vi.

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. Do đó, câu hỏi top-N chỉ cần một lần gọi duy nhất — đặt --order-by và --page-size N thay vì phân trang qua kết quả rồi cộng dồn:

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 cách đặt tên trên dashboard — ví dụ spend, taps, hoặc gross_roas. Xem Metrics để có 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ệ.

Với --entity keyword, --metric cũng chấp nhận các chỉ số chỉ dành cho keyword. Apple báo cáo impression share và rank cho cả vị trí quảng cáo bất kỳ lẫn vị trí quảng cáo đầu tiên, vì vậy mỗi chỉ số có hai phiên bản: _all và _first. Xem Insights để biết Apple định nghĩa chúng như thế nào.

Chỉ số	Giá trị
impression_midpoint_all, impression_midpoint_first	Tỷ lệ hiển thị trong khoảng thời gian báo cáo, tính theo phần trăm
rank_all, rank_first	Thứ hạng ứng dụng của bạn so với các ứng dụng khác cho từ khóa đó. Giá trị mới nhất, bất kể --date-from và --date-to
search_popularity	Độ phổ biến tìm kiếm từ 1 đến 5

Một từ khóa không có dữ liệu báo cáo sẽ trả về 0 cho các chỉ số này. Kể từ CLI 0.9.2, các tên này thay thế cho rank và impression_midpoint.

Mỗi chỉ số bạn đặt tên đều được tính trên toàn bộ cấp entity trước khi trang được cắt, vì vậy hãy chỉ yêu cầu các cột bạn thực sự cần thay vì lấy toàn bộ danh mục. subscribers và paid_subscribers đếm các hồ sơ người dùng duy nhất theo entity, chi phí cao hơn khoảng mười bảy lần so với một lần gọi chỉ lấy spend và installs — arppu và arpas cũng vậy vì chúng được tính từ các chỉ số đó. Ở bất kỳ --entity nào, bốn tên đó cần có --campaign hoặc --ad-group để thu hẹp phạm vi gọi:

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

Không có một trong hai bộ lọc đó, lệnh gọi sẽ thất bại với lỗi 422 cli_metric_scope_too_wide. Việc thu hẹp phạm vi là cách rẻ nhất để tăng tốc bất kỳ lệnh gọi metrics nào, vì chi phí phụ thuộc vào số lượng thực thể được tổng hợp chứ không phải kích thước trang.

Độ dài của khoảng thời gian báo cáo bị giới hạn bởi giá trị --group-by chi tiết nhất. Để báo cáo trên khoảng thời gian 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ệnh gọi:

Giá trị --group-by chi tiết nhất	Khoảng thời gian tối đa
day	28 ngày
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

Grain ngày do đó bao gồm tối đa bốn tuần. Để lấy dữ liệu trong khoảng thời gian dài hơn, hãy dùng grain week, vốn có thể gói gọn nửa năm trong một lần gọi.

Mỗi trang cũng bị giới hạn tối đa 5000 dòng breakdown, trong đó mỗi dòng là một thực thể × quốc gia × khoảng thời gian. Nếu trang vượt quá giới hạn này, lệnh gọi sẽ thất bại với lỗi 422 cli_response_too_large. Hãy thu gọn nhóm, thu hẹp khoảng thời gian, hoặc giảm --page-size; khi lệnh gọi nhóm theo day, thông báo lỗi sẽ cho biết kích thước trang phù hợp, vì vậy hãy thử lại với con số đó thay vì tự tính. metrics overview không trả về breakdown theo từng thực thể, nên giới hạn này không bao giờ áp dụng cho lệnh này.

Không có chỉ số ltv nào cả. Lifetime value là 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 lấy giá trị ngày thứ 7 hoặc ngày thứ 90:

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 campaign có ROAS ngày 90 cao nhất chỉ trong một lần gọi.

adapty asa metrics overview

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

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 số liệu cho toàn bộ cấp độ thực thể cộng với một chuỗi theo từng khoảng thời gian, giúp bạn biết “tổng doanh thu hoặc chi tiêu là bao nhiêu” chỉ trong một lần gọi. Lệnh này không có cờ sắp xếp và không hỗ trợ phân trang.

Với lệnh này, --metric chỉ chấp nhận các cohort root — revenue, roas, và arpu — không nhận các biến thể gross_, proceeds_, hay net_. Lệnh cũng không nhận các chỉ số dành riêng cho keyword.

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

--period-unit	Khoảng thời gian tối đa
day	90 ngày
week	180 ngày
month và thô hơn	365 ngày

Đối thủ cạnh tranh

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 trên dashboard.

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ịch sử thay đổi

Lịch sử thay đổi được lấy trực tiếp từ Apple Ads API. Adapty không lưu trữ dữ liệu này, và Apple chỉ giữ lại trong 6 tháng. Nó bao gồm mọi thay đổi trong tổ chức, kể cả những thay đổi thực hiện trực tiếp trên Apple Ads, bởi Apple Support, hoặc bởi các công cụ API khác.

adapty asa change-history list

Liệt kê các thay đổi đã thực hiện trong một tổ chức Apple Ads, mới nhất trước.

adapty asa change-history list --campaign-group <campaign-group-id> --date-from 2026-10-01 --entity-type Campaign --event-type UPDATE

Cờ	Bắt buộc	Mô tả
--campaign-group	Có	Tổ chức cần đọc (UUID từ orgs list). Mỗi lần gọi chỉ đọc được một tổ chức. Để đọc nhiều tổ chức, hãy chạy lệnh cho từng tổ chức một
--date-from	Không	Ngày bắt đầu khoảng thời gian (YYYY-MM-DD). Mặc định: 7 ngày trước
--date-to	Không	Ngày kết thúc khoảng thời gian (YYYY-MM-DD). Mặc định: hôm nay. Khoảng thời gian tối đa 14 ngày
--entity-type	Không	Campaign, AdGroup, Keyword, NegativeKeyword, Ad, Creative, LocationGroup, Org, hoặc AdAccount. Có thể dùng nhiều lần. Mặc định: mọi loại trừ Org và AdAccount. Org và AdAccount không thể kết hợp với các loại khác
--event-type	Không	CREATE, UPDATE, hoặc DELETE. Có thể dùng nhiều lần
--user-type	Không	Người thực hiện thay đổi: CUSTOMER (trong Apple Ads), CUSTOMER_API (qua Apple Ads API), hoặc APPLE_SUPPORT. Có thể dùng nhiều lần
--campaign, --ad-group, --entity-id	Không	ID số của Apple cho campaign, ad group, hoặc entity đã thay đổi. Có thể dùng nhiều lần
--user	Không	Apple user ID của người thực hiện thay đổi. Có thể dùng nhiều lần
--txn	Không	Apple transaction ID. Có thể dùng nhiều lần
--fields	Không	Mở rộng mỗi thay đổi thành một hàng cho mỗi trường đã thay đổi, kèm giá trị cũ và mới

Mỗi hàng là một giao dịch: ai thực hiện (modified_by, user_type), khi nào (event_time), và các thực thể đã thay đổi. Mỗi thực thể có detail_id dùng cho change-history get.

Với --fields, kích thước trang mặc định là 10, và --page-size lớn hơn sẽ bị từ chối. Một trang cần hơn 20 lần tra cứu sẽ thất bại: hãy thu hẹp bộ lọc, hoặc bỏ --fields và đọc từng thay đổi bằng change-history get.

Chấp nhận cờ phân trang. Tích --page × --page-size không được vượt quá 1000.

adapty asa change-history get

Hiển thị các thay đổi ở cấp độ trường của một thực thể trong một giao dịch.

adapty asa change-history get Campaign.444555666.TXN_ID --campaign-group <campaign-group-id>

Đối số	Mô tả
detail-id	detail_id từ change-history list, ở dạng EntityType.entityId.txnId

Cờ	Bắt buộc	Mô tả
--campaign-group	Có	Tổ chức mà thay đổi thuộc về. Lấy từ campaign_group_id trong hàng danh sách

Phản hồi liệt kê từng trường đã thay đổi cùng với old_values và new_values, cộng thêm metadata của entity trong entity_metadata. Một detail_id mà Apple không có bản ghi sẽ trả về 404.

Lỗi

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
403	cli_ad_account_unreadable	change-history không thể đọc tổ chức: token Apple Ads đã bị thu hồi, tổ chức không còn được liên kết, hoặc Apple từ chối truy cập
404	—	Thực thể không tồn tại hoặc thuộc về công ty khác
409	cli_idempotency_in_progress	Một lần ghi với cùng idempotency key vẫn đang chạy
422	cli_idempotency_key_reuse	Cùng một idempotency key được dùng với request body khác
422	cli_metric_scope_too_wide	Một chỉ số đếm hồ sơ người dùng được yêu cầu mà không có --campaign hoặc --ad-group
422	cli_response_too_large	Một trang metrics sẽ vượt quá 5000 dòng breakdown
429	cli_analytics_busy	Pool analytics đang bận, hoặc một quá trình xây dựng keyword pool khác cho công ty vẫn đang chạy. Thời gian chờ nằm trong header Retry-After
429	cli_cooldown_active	Quá nhiều request bị từ chối khiến token rơi vào trạng thái cool-down
429	cli_upstream_rate_limited	Apple đã rate-limit một request change-history. Thời gian chờ từ Apple nằm trong header Retry-After
504	cli_read_timeout	Một request change-history mất hơn 50 giây. Hãy thu hẹp khoảng thời gian hoặc bộ lọc

Chỉ số và danh sách từ khóa tìm kiếm dùng chung một ngân sách API theo công ty: 5 lần gọi mỗi phút, tối đa 2 lần trong bất kỳ 10 giây nào. change-history có ngân sách riêng: 30 lần gọi mỗi phút, tối đa 5 lần trong 10 giây, và chỉ một yêu cầu tại một thời điểm cho mỗi công ty. Nếu có 20 yêu cầu bị từ chối trong vòng 5 phút, thời gian chờ sẽ tăng dần: 5 phút, rồi 30 phút, rồi 3 giờ. Thử lại 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 yêu cầu lỗi thay vì lặp lại nó.

CLI xử lý các lần chờ ngắn cho bạn. Với lỗi 429 không phải cool-down, nếu Retry-After là 60 giây hoặc ít hơn, lệnh sẽ chờ trong khoảng thời gian đó rồi thử lại một lần, và thông báo thời gian chờ ra standard error.