Adapty CLI có thể quản lý tài khoản Ads Manager của bạn từ terminal, thông qua chủ đề adapty asa. CLI hỗ trợ quản lý chiến dịch, nhóm quảng cáo, từ khóa, quảng cáo, trang sản phẩm, quy tắc tự động, chỉ số và nghiên cứu đối thủ cạnh tranh.

Dùng nó cho những việc mà trình duyệt xử lý chậm: cấp cho AI agent quyền truy cập trực tiếp vào hiệu suất quảng cáo, thêm vài trăm từ khóa từ một file, và chạy cùng một thiết lập trên nhiều chiến dịch. Với mọi thứ còn lại, dashboard vẫn nhanh hơn.

Trước khi bắt đầu

Các lệnh Ads Manager sử dụng cùng cài đặt và đăng nhập với phần còn lại của CLI. Nếu bạn chưa thiết lập, hãy làm theo bước 1 và 2 của hướng dẫn quickstart.

Điều kiện tiên quyết

Hai điều kiện sau áp dụng cho mọi lệnh adapty asa:

• Tài khoản Apple Ads đã kết nối: Kết nối bằng adapty asa connect, hoặc trên dashboard như mô tả trong Bắt đầu với Adapty Ads Manager.
• Gói đăng ký Ads Manager đang hoạt động: Nếu không có, mọi lệnh sẽ thất bại với lỗi 402 ads_manager_subscription_required.

Một lệnh duy nhất báo cáo cả hai:

adapty asa whoami

Điểm khác biệt so với phần còn lại của CLI

• Không có flag --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ò bộ lọc.
• Thao tác ghi tác động trực tiếp đến Apple: Mỗi lệnh thay đổi tài khoản của bạn sẽ in ra nội dung request và yêu cầu xác nhận trước khi gửi. Không có bước staging.
• Đọc thì rẻ, ghi thì không: Chạy lệnh list và --dry-run thoải mái. Còn lại hãy xem như không thể hoàn tác.

Để bỏ qua lời nhắc xác nhận trong một script, hãy truyền --yes. Khi dùng --json hoặc trong một pipe, lệnh ghi sẽ từ chối thay vì chờ câu trả lời không bao giờ đến, vì vậy --yes là bắt buộc trong trường hợp đó.

Tìm các ID bạn cần

Mỗi lệnh đều yêu cầu UUID, và mọi UUID đều lấy từ lệnh list. Làm theo thứ tự phân cấp sau:

adapty asa orgs list
adapty asa campaigns list --campaign-group <campaign-group-id>
adapty asa ad-groups list --campaign <campaign-id>

Hãy giới hạn phạm vi mỗi lần đọc bằng bộ lọc. Bộ lọc thu hẹp truy vấn thay vì chỉ lọc kết quả hiển thị, nên đọc có phạm vi sẽ nhẹ hơn nhiều so với đọc không có phạm vi vì phải duyệt qua toàn bộ tài khoản. adapty asa keywords list không có --ad-group là lệnh đọc rộng nhất trong phần này.

Các danh sách này chỉ trả về metadata. Số liệu hiệu suất đến từ asa metrics.

Nhận gợi ý từ khóa

Để bắt đầu danh sách từ khóa mà không cần nghiên cứu, hãy lấy một tập hợp từ khóa có sẵn cho ứng dụng của bạn. Truyền adam_id của ứng dụng từ adapty asa apps list và loại tập hợp — brand, generic, hoặc competitor:

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

Pool không có bids hay match types. Hãy tự chọn những thông số đó, rồi thêm keywords theo hướng dẫn tại Thêm keywords hàng loạt. Nếu output hiển thị status: building, hãy thử lại sau khoảng một phút. Xem Lệnh Ads Manager để biết các loại pool và giới hạn.

Thêm từ khóa hàng loạt

Thêm từng từ khóa một là lý do chính để rời khỏi dashboard. Đặt mỗi từ khóa trên một dòng trong tệp văn bản:

adapty asa keywords add --ad-group <ad-group-id> --from-file keywords.txt --bid 1.20 --match-type EXACT

Từ khóa được áp dụng theo từng lô tối đa 100 từ mỗi lần gọi. Hãy chia danh sách lớn hơn thành nhiều lần gọi.

Có hai loại lỗi có thể xảy ra, và chúng hoạt động khác nhau. Một ID không hợp lệ sẽ làm hỏng toàn bộ batch trước khi Apple được gọi, nên không có gì được áp dụng. Apple cũng có thể từ chối từng keyword riêng lẻ — các keyword còn lại vẫn được thêm vào, và mỗi lần từ chối được báo cáo kèm theo lý do. Hãy kiểm tra dòng tóm tắt thay vì chỉ dựa vào mã thoát.

Bắt đầu với một vài keyword và kiểm tra kết quả trước khi gửi cả file.

Tạo chiến dịch Max Conversions

Một chiến dịch đặt giá thầu với MAX_CONVERSIONS chỉ hoạt động khi có một nhóm quảng cáo tự động, vì vậy hãy tạo cả hai cùng lúc:

adapty asa campaigns create --org <campaign-group-id> --name "Max Conv" --adam-id 123456 --country US --daily-budget 50 --bidding-strategy MAX_CONVERSIONS
adapty asa ad-groups create --campaign <campaign-id> --name "Automated Max Conv" --automated

Cho đến khi nhóm quảng cáo đó tồn tại, chiến dịch báo cáo serving_status: NOT_RUNNING với AUTOMATED_KEYWORDS_REQUIRED_AD_GROUP_MISSING trong serving_state_reasons, và campaigns create sẽ in ra cả lý do lẫn lệnh để giải quyết vấn đề đó.

--automated là thứ đáp ứng yêu cầu — một nhóm quảng cáo thông thường với --automated-keywords thì không đủ. Apple tự lên lịch và chạy nhóm quảng cáo tự động, vì vậy nó không cần --start-time, --default-bid là tùy chọn, và nó luôn ở trạng thái bật: để dừng chi tiêu, hãy tạm dừng chiến dịch.

Trên chiến dịch, hãy giữ --target-cpa thấp hơn --daily-budget.

Đặt tùy chọn lập hóa đơn cho hạn mức tín dụng

Apple yêu cầu Invoicing Options trên mọi chiến dịch trong một tổ chức thanh toán theo hạn mức tín dụng. adapty asa orgs list báo cáo payment_model của từng tổ chức — LOC có nghĩa là năm cờ --invoice-* sẽ được áp dụng:

adapty asa campaigns create --org <campaign-group-id> --name "LOC push" --adam-id 123456 --country US --daily-budget 50 --invoice-advertiser "Acme Inc" --invoice-order-number PO-42 --invoice-contact-name "Jane Doe" --invoice-contact-email jane@acme.com --invoice-billing-email billing@acme.com

Pass all five in one call — a partial set is rejected before the request reaches Apple. Without them, the campaign is created but reports serving_status: NOT_RUNNING with MISSING_BO_OR_INVOICING_FIELDS.

Truyền đủ cả năm tham số trong một lần gọi — nếu thiếu bất kỳ tham số nào, yêu cầu sẽ bị từ chối trước khi đến Apple. Nếu không có chúng, campaign được tạo nhưng sẽ báo serving_status: NOT_RUNNING với lỗi MISSING_BO_OR_INVOICING_FIELDS.

Năm flag tương tự trên lệnh adapty asa campaigns update sẽ đặt Invoicing Options cho một campaign đã tồn tại. Chúng thay thế toàn bộ tập hợp đã lưu, vì vậy hãy truyền đủ cả năm kể cả khi chỉ muốn thay đổi một trong số đó.

Tạo cấu trúc campaign trong một thao tác

campaigns bulk-create thay thế cho script lặp qua campaigns create và ad-groups create. Lệnh này gửi toàn bộ cấu trúc campaign — bao gồm các campaign cùng ad group, từ khóa, từ khóa phủ định và quảng cáo — trong một thao tác duy nhất:

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

Đầu vào là mô tả JSON của cấu trúc — xem định dạng cấu trúc để biết các trường. JSON là lựa chọn tự nhiên cho AI agent: nó tạo ra cấu trúc và truyền vào:

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

Một mẫu bulk của Apple Ads gốc cũng được chấp nhận làm đầu vào — server sẽ chuyển đổi Campaign_And_Adgroup_Template.xlsx hoặc keywords .csv thành một cấu trúc. --org-id nhận giá trị số org_id từ adapty asa orgs list. Để xem trước kết quả chuyển đổi trước khi tạo bất cứ thứ gì, thêm --preview:

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

Các vấn đề chuyển đổi sẽ được báo cáo kèm theo sheet, hàng và cột tương ứng. Khi cấu trúc hiển thị trông đúng, hãy bỏ --preview để gửi.

Kết quả --preview cũng là cách nhanh nhất để lấy file cấu trúc ban đầu: lưu lại, chỉnh sửa và gửi bằng --file — tương tự như cách automations get cung cấp template cho rule.

Toàn bộ cấu trúc được xác thực trước khi tạo bất cứ thứ gì, và nếu bị từ chối, danh sách sẽ liệt kê mọi node không hợp lệ. Sau khi được chấp nhận, các đối tượng sẽ được tạo trên server trong khi lệnh báo cáo tiến trình. Kết quả cuối cùng là success, partial, hoặc failed — kết quả partial liệt kê từng đối tượng chưa được tạo, kèm theo lỗi từ Apple.

Đối với cấu trúc lớn, truyền --no-wait để nhận ngay operation ID và xem tiến trình sau:

adapty asa campaigns bulk-status <operation-id>

Truy vấn chỉ số từ agent và script

asa metrics báo cáo ở bất kỳ cấp độ nào trong tài khoản theo khoảng thời gian. Thêm --json để AI agent hoặc script có thể sử dụng kết quả trực tiếp:

adapty asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --metric spend --metric roas --json

--metric là tham số bắt buộc và có thể dùng nhiều lần, nhận tên các chỉ số mà Ads Manager theo dõi. Xem Chỉ số để biết danh sách đầy đủ. Mỗi chỉ số bạn chỉ định đều được tính toán trên toàn bộ cấp thực thể trước khi phân trang, vì vậy hãy chỉ yêu cầu các cột bạn thực sự cần thay vì toàn bộ danh mục.

--app, --campaign, và --ad-group thu hẹp phạm vi báo cáo, và đây là cách rẻ nhất để tăng tốc độ gọi API, 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. Bốn chỉ số đếm hồ sơ người dùng duy nhất theo từng thực thể — subscribers, paid_subscribers, arppu, và arpas — và những chỉ số này yêu cầu bộ lọc campaign hoặc ad group ở bất kỳ cấp thực thể nào:

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

Các chỉ số cohort hoạt động khác với phần còn lại. Không có chỉ số ltv, vì giá trị vòng đời được đọc theo cửa sổ gia hạn chứ không phải theo ngày. Hãy truyền cửa sổ thay thế:

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 90

Lệnh này trả về danh sách các chiến dịch được xếp hạng theo ROAS ngày 90. Một lần gọi có thể chứa tối đa 16 cửa sổ.

Mỗi hàng là một entity, đã được tổng hợp và sắp xếp sẵn trên server. Câu hỏi “top 5 chiến dịch theo chi tiêu” vì vậy chỉ cần một lần gọi, không cần duyệt qua từng trang:

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

Metrics và danh sách từ khóa tìm kiếm dùng chung một ngân sách analytics theo công ty: tối đa 5 lần gọi mỗi phút và không quá 2 lần trong bất kỳ 10 giây nào. Hãy đặt câu hỏi cụ thể một lần thay vì polling liên tục.

Hai giới hạn áp dụng cho một báo cáo. Khoảng thời gian báo cáo bị giới hạn bởi mức độ chi tiết của nhóm — 28 ngày với --group-by day, 90 ngày khi không có nhóm theo khoảng thời gian, 180 ngày theo tuần, 365 ngày theo tháng — và mỗi trang bị giới hạn ở 5000 hàng phân tích, tính một hàng cho mỗi thực thể × quốc gia × khoảng thời gian. Vì vậy, hãy mở rộng báo cáo bằng cách giảm độ chi tiết của --group-by, không phải bằng cách chia thành nhiều lần gọi hơn.

Kiểm tra từ khóa của đối thủ cạnh tranh

Một lệnh duy nhất trả về các từ khóa mà các ứng dụng cạnh tranh đang đặt giá thầu, cho tối đa năm ứng dụng App Store cùng một lúc:

adapty asa competitors summary --app-ids 1668337467,6503873027 --json

Khoảng thời gian và quốc gia được cố định trên máy chủ — tháng đầy đủ gần nhất, trên toàn bộ các quốc gia — vì vậy lệnh này không có cờ nào ngoài các app ID. Lần gọi đầu tiên cho một tập hợp ứng dụng có thể mất hàng chục giây.

Sử dụng công cụ này để tự động lấy dữ liệu từ khóa của đối thủ và đưa vào báo cáo theo lịch định kỳ. Để lọc kết quả, so sánh các quốc gia với nhau, hoặc thêm trực tiếp các từ khóa tìm được vào chiến dịch, hãy dùng Market Intelligence trên dashboard.

Chạy automation rules

CLI lưu trữ JSON bạn cung cấp, vì vậy cách nhanh nhất để có được file automation rule hợp lệ là tạo một rule trong dashboard, sau đó đọc lại:

adapty asa automations get <automation-id> --json > rule.json

Chỉnh sửa file đó và dùng làm template cho các rule mới:

adapty asa automations create --file rule.json

A rule file contains exactly one condition and exactly one action, which is what the API keeps per rule. When you pass a file to automations update, remove the internal_id field first — the update is rejected if it is present.

Tạo hành động Add as keyword từ các flag

Một hành động là ngoại lệ so với JSON viết tay. Add as keyword, dùng để đưa một từ khóa tìm kiếm lên hoặc sao chép từ khóa vào một nhóm quảng cáo khác, lấy nhóm quảng cáo đích, giá thầu và kiểu khớp từ các flag:

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

Các flag tương tự trên automations update sẽ sửa một rule đã được lưu với shape sai. CLI đọc rule đó, xây dựng lại action từ đầu, rồi ghi lại, chỉ giữ những cài đặt đã lưu phù hợp với action Add as keyword:

adapty asa automations update <automation-id> --target-ad-group <ad-group-id> --match-type EXACT --cpt-bid-type search_term_current_cpt

Bất kỳ quy tắc nào bị thiếu đều phải được bổ sung thông qua một flag. Xem Lệnh Ads Manager để biết toàn bộ danh sách.

Kiểm tra một quy tắc trước khi cho phép nó thay đổi giá thầu:

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

Một lần chạy thử (dry run) sẽ đánh giá các điều kiện và ghi log những gì rule sẽ thực hiện mà không tác động đến Apple Ads. Các lần chạy được xếp vào hàng đợi thay vì thực hiện ngay lập tức, vì vậy lệnh sẽ in ra một run ID và kết quả sẽ xuất hiện trong adapty asa automations runs.

Chạy lại script an toàn

Mỗi lần ghi đều gửi kèm một idempotency key. CLI tạo một key cho mỗi lần chạy và thử lại một lần nếu xảy ra lỗi mạng, đảm bảo một request bị lỗi giữa chừng sẽ không bao giờ được áp dụng hai lần.

Trong script, hãy tự đặt key để toàn bộ pipeline có thể chạy lại:

adapty asa campaigns create --org <campaign-group-id> --name "Winter push" --adam-id 123456 --country US --daily-budget 50 --idempotency-key winter-push-2026 --yes

Re-running the same command within 24 hours returns the stored result and prints Already applied earlier instead of creating a second campaign. The same key with a different body fails with 422, which catches an edited script that reuses a key by mistake.

Tiếp theo là gì

• Quản lý Apple Ads bằng công cụ AI — cài plugin Apple Ads để Claude Code, Copilot CLI, Codex hoặc Gemini CLI có thể chạy các lệnh này cho bạn.
• Lệnh Ads Manager — tất cả các lệnh kèm đối số, flag và giá trị được chấp nhận.
• Automations — mỗi loại rule hoạt động như thế nào và có thể thực hiện những action gì.
• Chỉ số — tên các chỉ số được chấp nhận bởi --metric và cách tính từng chỉ số.