Lệnh Placements và Segments
Các lệnh Adapty CLI này quản lý placements, các đối tượng trên đó, và các phân khúc mà những đố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) |
--type | No | Chỉ liệt kê các placement thuộc loại này: paywall, flow, hoặc onboarding |
Chấp nhận pagination flags.
Mỗi mục chứa id, developer_id, title, is_active và type. is_active là true nếu placement đang hoạt động và false nếu không hoạt động. type là loại nội dung của placement: paywall, flow hoặc onboarding. Trong --json, một placement không có type sẽ có type: null. Cờ --type và trường type yêu cầu CLI phiên bản 0.15.0 trở lên.
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, type, và mảng audiences. is_active là true cho placement đang hoạt động và false cho placement không hoạt động. Mỗi mục trong audiences 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 đối tượng 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.
--paywall-id đã bị deprecated và sẽ bị xóa. Khi được truyền vào, CLI sẽ in cảnh báo ra stderr và chuyển đổi giá trị thành một đối tượng mặc định. Hãy dùng --audiences cho các tác vụ tự động mớ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 |
Truyền --paywall-id sẽ ghi đè tất cả các đối tượng trên placement. Các đối tượng dành riêng cho phân khúc sẽ bị xóa. Để giữ lại chúng, hãy dùng --audiences và đưa vào tất cả các mục bạn muốn giữ.
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.
placements update thay thế toàn bộ danh sách đối tượng, bao gồm cả các đối tượng đang chạy A/B test. Để giữ nguyên một test đang chạy, hãy sao chép mục đó từ placements get vào --audiences mà không thay đổi gì, với cùng ab_test_id và segment_ids. Nếu bạn ghi đè mà xóa hoặc thay thế mục đó, test sẽ dừng lại mà không có người thắng. Nếu bạn chuyển mục đó sang các phân khúc khác, test sẽ bắt đầu lại, và nếu có ab_test_id trên một đối tượng khác thì test sẽ chạy ở đó. Nếu bạn chỉ thay đổi thứ tự ưu tiên, test sẽ tiếp tục chạy bình thường. CLI sẽ không cảnh báo bạn về các trường hợp này.
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:
-
Tìm các placement bị ảnh hưởng:
adapty paywalls placements --app <app-id> <old-paywall-id> -
Với mỗi placement, đọc toàn bộ mảng
audiences:adapty placements get --app <app-id> <placement-id> --json -
Thay thế các giá trị
paywall_idtươ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. -
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>'
danh sách chỉ số placement adapty
Hiển thị chỉ số trọn đời của một số flow placement hoặc paywall placement, mỗi dòng là một placement. Đây là dữ liệu của bảng placement trong dashboard.
adapty placements metrics list --app <app-id> --type flow --ids <placement-id>,<placement-id>
| Flag | Required | Description |
|---|---|---|
--app | Yes | App ID (UUID) |
--type | Yes | Loại placement, như placements list hiển thị: flow hoặc paywall |
--ids | Yes | Placement ID (UUID). Phân tách bằng dấu phẩy, hoặc lặp lại flag |
--csv | No | In CSV: một hàng cho mỗi placement, gồm placement ID và các chỉ số dạng số. Không dùng được cùng với --json |
Các lệnh placements metrics đọc các con số trên trang chỉ số placement. Chúng yêu cầu CLI phiên bản 0.15.0 trở lên đối với flow placement và 0.16.0 trở lên đối với paywall placement. --type phải khớp với loại của placement: Adapty sẽ từ chối placement thuộc loại khác, và không có chỉ số nào cho onboarding placement.
Mỗi dòng hiển thị ID của placement cùng với số lượt xem, lượt mua, lượt dùng thử và doanh thu. Đối với flow placement, --json và --csv chứa đầy đủ 27 chỉ số.
Hàng lifetime của một placement paywall không có lượt xem, vì vậy cột views hiển thị —. Nó mang 15 chỉ số, chẳng hạn như purchases, revenue, và refunds. Để đọc viewers của một placement paywall, hãy dùng placements metrics get với một khoảng thời gian.
adapty placements metrics values
Liệt kê các khóa và giá trị bộ lọc của một placement kiểu flow hoặc paywall: đây là những gì placements metrics get --filter nhận vào.
adapty placements metrics values --app <app-id> <placement-id> --type flow
| Đối số | Mô tả |
|---|---|
placement-id | ID của placement (UUID) |
| Flag | Bắt buộc | Mô tả |
|---|---|---|
--app | Có | ID ứng dụng (UUID) |
--type | Có | Loại placement: flow hoặc paywall |
Đầu ra có cùng dạng với flows metrics values: giá trị đầu tiên của mỗi nhóm là khóa bộ lọc, và các giá trị bên trong cùng là những gì khóa đó nhận. Một placement không có khóa bộ lọc sẽ in ra No filter values.
adapty placements metrics get
Hiển thị các chỉ số của một flow placement hoặc paywall placement dưới dạng cây của trang placement metrics. Một flow placement có thể lấy toàn bộ thời gian tồn tại hoặc một khoảng thời gian cụ thể. Một paywall placement lấy theo một khoảng thời gian.
adapty placements metrics get --app <app-id> <placement-id> --type flow --based-on flow
| Đối số | Mô tả |
|---|---|
placement-id | ID của placement (UUID) |
| Flag | Bắt buộc | Mô tả |
|---|---|---|
--app | Có | App ID (UUID) |
--type | Có | Loại placement: flow hoặc paywall |
--based-on | Có | Tiêu chí phân chia cấp đầu tiên của cây. Với placement kiểu flow: audience, flow, hoặc placement. Với placement kiểu paywall: audience hoặc paywall |
--group-by | Không | Với placement kiểu flow, phân chia từng đối tượng theo country hoặc store. Với placement kiểu paywall, nhóm sản phẩm theo product, store, hoặc country |
--date-from | Không | Ngày đầu tiên của khoảng thời gian, bao gồm ngày đó (YYYY-MM-DD). Dùng kết hợp với --date-to và --date-type |
--date-to | Không | Ngày cuối cùng của khoảng thời gian, bao gồm ngày đó (YYYY-MM-DD). Dùng kết hợp với --date-from và --date-type |
--date-type | Không | Ngày nào được áp dụng cho khoảng thời gian: purchase_date hoặc profile_install_date. Dùng kết hợp với --date-from và --date-to |
--granularity | Không | Chia khoảng thời gian thành các điểm: day, week, month, quarter, hoặc year |
--filter | Không | Chỉ giữ lại dữ liệu có giá trị khớp với khóa lọc. Có thể dùng nhiều lần. Xem Lọc các chỉ số |
--timezone | Không | Múi giờ IANA cho các điểm thời gian, ví dụ Europe/Berlin. Nếu không có, Adapty sẽ dùng múi giờ của ứng dụng |
--depth | Không | Số cấp của cây sẽ hiển thị bên dưới Total. Mặc định: 1 |
--csv | Không | In dữ liệu dạng CSV: mỗi hàng tương ứng với một nút trong toàn bộ cây. Không thể dùng cùng với --json |
Đối với placement dạng flow, lệnh trả về chỉ số theo toàn bộ thời gian nếu không có --date-from, --date-to, và --date-type. Để lấy theo khoảng thời gian, cần truyền cả ba tham số: nếu chỉ truyền khoảng thời gian mà thiếu --date-type thì lệnh sẽ thoát với mã lỗi 4. Với placement dạng paywall, luôn cần cả ba tham số, và sẽ thoát với mã lỗi 4 nếu thiếu.
Đối với placement dạng flow, đầu ra, --depth, --json, --csv, và --filter hoạt động giống như trong flows metrics get. Đối với placement dạng paywall, chúng hoạt động giống như trong paywalls metrics get. Ví dụ, để so sánh các đối tượng của một placement theo cửa hàng:
adapty placements metrics get --app <app-id> <placement-id> --type flow --based-on audience --group-by store \
--date-from 2026-09-01 --date-to 2026-10-21 --date-type purchase_date --depth 2
Để đọc từng nhánh của A/B test trên một paywall placement, hãy tách cây theo paywall. Dưới mỗi paywall, dòng của A/B test chứa số liệu của nhánh đó:
adapty placements metrics get --app <app-id> <placement-id> --type paywall --based-on paywall \
--date-from 2026-09-01 --date-to 2026-10-21 --date-type purchase_date --depth 3
Tổng của toàn bộ A/B test được hiển thị trên dòng riêng trong cây --based-on audience. Tổng này đếm mỗi người dùng một lần, do đó có thể thấp hơn tổng của các nhánh: một người dùng đã xem cả hai nhánh sẽ được tính trong từng nhánh.
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 |
segments update thay thế toàn bộ phân khúc. Hãy truyền vào mọi filter bạn muốn giữ, không chỉ filter đang thay đổi. Để đọc các filter hiện tại, chạy adapty segments get --app <app-id> <segment-id> --json.
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.