Các lệnh Adapty CLI này quản lý placement, các đối tượng trên đó, và các phân khúc mà các đối tượng đó nhắm đến.

Placements

Placements là nơi các flow, paywall và onboarding của bạn tiếp cận người dùng. Loại nội dung của một placement được cố định khi tạo, vì vậy việc chuyển ứng dụng từ paywall sang flow đồng nghĩa với việc tạo các placement mới thay vì cập nhật các placement hiện có — skill migrate-placements sẽ điều khiển các lệnh này để thực hiện hàng loạt.

adapty placements list

Liệt kê tất cả các placement của một ứng dụng.

adapty placements list --app <app-id>

Flag	Required	Description
--app	Yes	App ID (UUID)

Chấp nhận pagination flags.

Mỗi mục chứa id, developer_id, title, và is_active. is_active là true cho placement đang hoạt động và false cho placement không hoạt động.

adapty placements get

Lấy thông tin chi tiết của một placement cụ thể.

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

Argument	Description
placement-id	Placement ID (UUID)

Flag	Required	Description
--app	Yes	App ID (UUID)

Phản hồi chứa id, developer_id, title, is_active, và một mảng audiences. is_active là true cho một placement đang hoạt động và false cho placement không hoạt động. Mỗi mục audience chứa content_type, segment_ids, priority, và ID của nội dung tương ứng: paywall_id cho paywall, flow_id cho flow, hoặc ab_test_id và ab_test_title cho một audience chạy A/B test. Đối tượng mặc định có segment_ids: [] và giá trị priority cao nhất (được đánh giá sau cùng). Xem Cấu trúc Audiences.

adapty placements create

Tạo một placement mới.

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

Flag	Required	Description
--app	Yes	App ID (UUID)
--title	Yes	Tiêu đề placement
--developer-id	Yes	Chuỗi định danh dùng trong code ứng dụng để yêu cầu placement này
--audiences	Một trong hai	Mảng JSON gồm các mục đối tượng, mỗi mục có content_type rõ ràng. Xem Cấu trúc Audiences
--paywall-id	Một trong hai	Không còn được hỗ trợ. ID Paywall (UUID). Được bọc phía client thành một đối tượng mặc định duy nhất

Chỉ truyền một trong hai tham số --audiences hoặc --paywall-id. Truyền cả hai hoặc không truyền tham số nào đều gây lỗi.

adapty placements update

Thay thế tất cả các trường của một placement hiện có.

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

Lệnh này thay thế toàn bộ các trường của placement, bao gồm cả danh sách đối tượng đầy đủ.

Đối số	Mô tả
placement-id	ID placement (UUID)

Flag	Bắt buộc	Mô tả
--app	Có	App ID (UUID)
--title	Có	Tiêu đề placement
--developer-id	Có	Chuỗi định danh dùng trong code ứng dụng để gọi placement này
--audiences	Một trong hai	Mảng JSON các mục đối tượng, mỗi mục có content_type tường minh. Xem Định dạng Audiences
--paywall-id	Một trong hai	Không còn được hỗ trợ. ID Paywall (UUID). Thay thế tất cả đối tượng bằng một đối tượng mặc định duy nhất

Cấu trúc audiences

Cờ --audiences nhận một mảng JSON. Mỗi mục có:

Trường	Kiểu	Mô tả
content_type	string	Bắt buộc ở mỗi mục. "paywall", "flow", "ab_test" (A/B test paywall), "flow_ab_test" (A/B test flow), "cross_ab_test" hoặc "flow_cross_ab_test" (A/B test đa placement). Dùng paywall, ab_test và cross_ab_test trong paywall placement, và flow, flow_ab_test và flow_cross_ab_test trong flow placement
segment_ids	string[]	ID phân khúc được nhắm mục tiêu bởi đối tượng này. Độ dài 0 hoặc 1. Mảng rỗng đánh dấu đối tượng mặc định — dự phòng cho người dùng không khớp với phân khúc nào khác
paywall_id	string	ID (UUID) paywall hiển thị cho người dùng trong đối tượng này. Bắt buộc khi content_type là "paywall"
flow_id	string	ID (UUID) flow hiển thị cho người dùng trong đối tượng này. Bắt buộc khi content_type là "flow"
ab_test_id	string	ID A/B test chạy cho người dùng trong đối tượng này. Bắt buộc với bốn kiểu nội dung A/B test
ab_test_title	string	Tiêu đề A/B test. Chỉ đọc: API bỏ qua giá trị này khi ghi
priority	number	Bắt đầu từ 0, duy nhất trong placement. Các đối tượng được đánh giá từ thấp đến cao; đối tượng mặc định phải có giá trị cao nhất

Một placement phải có đúng một đối tượng mặc định.

Các mục A/B test liên placement (cross_ab_test, flow_cross_ab_test) là chỉ đọc. API bỏ qua chúng khi ghi và giữ nguyên dữ liệu đã lưu.

Loại nội dung của một placement được cố định khi bạn tạo, vì vậy placements update không thể chuyển một paywall placement sang flow hoặc ngược lại. Hãy phục vụ flow từ một placement riêng — xem Tạo một placement mới cho flow của bạn.

CLI kiểm tra từng mục trước khi gửi yêu cầu. Một mục thiếu hoặc có content_type không xác định, hoặc thiếu ID mà content_type yêu cầu, sẽ thoát với mã 2 và không gửi gì cả. Với content_type mà CLI không nhận ra, CLI in ra this CLI does not know this audience kind; update the CLI. Nếu mục đó đến từ lệnh placements get, hãy cập nhật CLI thay vì xóa mục đó: mục đó có thể là một A/B test đang chạy.

Một flow chỉ có thể được gắn vào sau khi đã được xuất bản. Flow ở trạng thái draft, hoặc flow đang trong quá trình xuất bản lần đầu, sẽ bị server từ chối; CLI nhận ra lỗi đó và thoát với code 2, đồng thời in ra lệnh flows publish cho flow đó. Để xuất bản một flow, hãy dùng flows publish hoặc Flow & Paywall Builder, rồi chờ cho đến khi trạng thái của flow chuyển thành published.

Ví dụ với một đối tượng mục tiêu và một đối tượng mặc định:

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

Ví dụ về một placement phục vụ flow đã xuất bản cho tất cả người dùng:

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

Để thay thế paywall trên nhiều placement mà không mất các routing theo phân khúc:

1. Tìm các placement bị ảnh hưởng:

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

2. Với mỗi placement, đọc toàn bộ mảng audiences:

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

3. Thay thế các giá trị paywall_id tương ứng ở phía client. Giữ nguyên tất cả các mục khác, kể cả các mục A/B test.

4. Ghi lại payload đã chỉnh sửa:

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

Phân khúc

Phân khúc nhóm người dùng theo các thuộc tính hồ sơ của họ. Sử dụng các lệnh này để tạo phân khúc và tra cứu ID phân khúc khi tạo đối tượng placement. Để xây dựng phân khúc từ các chiến dịch Apple Ads, nhóm quảng cáo hoặc từ khóa, hãy dùng adapty asa segments create thay thế: lệnh này sẽ tra cứu Apple ID cho bạn và đặt tên phân khúc theo cách Ads Manager thực hiện.

Danh sách phân khúc adapty

Liệt kê tất cả phân khúc của một ứng dụng.

adapty segments list --app <app-id>

Flag	Required	Description
--app	Yes	App ID (UUID)

Chấp nhận pagination flags.

adapty segments get

Lấy thông tin chi tiết cho một phân khúc cụ thể.

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

Đối số	Mô tả
segment-id	ID phân khúc (UUID)

Cờ	Bắt buộc	Mô tả
--app	Có	ID ứng dụng (UUID)

Phản hồi chứa id, title, description, filters, profile_count, refresh_in_progress, created_at và updated_at. Lệnh list chỉ trả về id, title và description.

adapty segments create

Tạo một phân khúc từ một hoặc nhiều bộ lọc.

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

Flag	Bắt buộc	Mô tả
--app	Có	App ID (UUID)
--title	Có	Tiêu đề phân khúc
--filter	Có	Quy tắc lọc. Có thể lặp lại. Xem Cú pháp bộ lọc
--description	Không	Mô tả phân khúc

Người dùng chỉ khớp với phân khúc khi họ khớp với mọi bộ lọc. Phản hồi có các trường giống như segments get. 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 segments update

Thay thế tiêu đề, mô tả và bộ lọc của một phân khúc hiện có.

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

Argument	Description
segment-id	Segment ID (UUID)

Flag	Required	Description
--app	Yes	App ID (UUID)
--title	Yes	Tiêu đề phân khúc
--filter	Yes	Quy tắc lọc. Có thể lặp lại. Xem Cú pháp filter
--description	No	Mô tả phân khúc

Cú pháp filter

Viết mỗi --filter theo dạng field:OPERATOR:value. Để khớp với nhiều giá trị, hãy phân cách chúng bằng dấu phẩy: ip_country:IN:US,CA.

Toán tử	Giá trị	Ví dụ
IN, NOT IN	Một hoặc nhiều	ip_country:NOT IN:US,CA
>, >=, <, <=	Một	age:>:18
BETWEEN	Hai	total_revenue_usd:BETWEEN:10,100
IS NULL, IS NOT NULL	Không có	age:IS NULL

Truyền số dưới dạng giá trị thông thường, ví dụ age:>:18. Adapty tự động chuyển đổi cho các trường số như age, total_revenue_usd và các thuộc tính tùy chỉnh kiểu float.

Với giá trị mà dạng rút gọn này không thể biểu diễn, hãy truyền bộ lọc dưới dạng đối tượng JSON:

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

Adapty xác thực tên trường, toán tử và kiểu giá trị, đồng thời báo cáo một lỗi cho mỗi bộ lọc không hợp lệ. Để xem tên trường và định dạng giá trị của các bộ lọc hiện có, chạy adapty segments get --app <app-id> <segment-id> --json trên một phân khúc đã được tạo trong dashboard.

Tiếp theo là gì

• Tham chiếu lệnh — mọi chủ đề CLI, các cờ toàn cục và cờ phân trang.