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>
FlagRequiredDescription
--appYesApp ID (UUID)
--typeNoChỉ 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>
ArgumentDescription
placement-idPlacement ID (UUID)
FlagRequiredDescription
--appYesApp 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}]'
FlagRequiredDescription
--appYesApp ID (UUID)
--titleYesTiêu đề placement
--developer-idYesChuỗi định danh dùng trong code ứng dụng để yêu cầu placement này
--audiencesMột trong haiMả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-idMột trong haiKhô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.

Warning

--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-idID placement (UUID)
FlagBắt buộcMô tả
--appCóApp ID (UUID)
--titleCóTiêu đề placement
--developer-idCóChuỗi định danh dùng trong code ứng dụng để gọi placement này
--audiencesMột trong haiMả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-idMột trong haiKhô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
Warning

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ườngKiểuMô tả
content_typestringBắ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_idsstring[]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_idstringID (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_idstringID (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_idstringID 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_titlestringTiêu đề A/B test. Chỉ đọc: API bỏ qua giá trị này khi ghi
prioritynumberBắ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.

Warning

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:

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

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>
FlagRequiredDescription
--appYesApp ID (UUID)
--typeYesLoại placement, như placements list hiển thị: flow hoặc paywall
--idsYesPlacement ID (UUID). Phân tách bằng dấu phẩy, hoặc lặp lại flag
--csvNoIn 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-idID của placement (UUID)
FlagBắt buộcMô tả
--appCóID ứng dụng (UUID)
--typeCó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-idID của placement (UUID)
FlagBắt buộcMô tả
--appCóApp ID (UUID)
--typeCóLoại placement: flow hoặc paywall
--based-onCó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-byKhôngVớ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-fromKhôngNgà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-toKhôngNgà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-typeKhôngNgà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
--granularityKhôngChia khoảng thời gian thành các điểm: day, week, month, quarter, hoặc year
--filterKhôngChỉ 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ố
--timezoneKhôngMú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
--depthKhôngSố cấp của cây sẽ hiển thị bên dưới Total. Mặc định: 1
--csvKhôngIn 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>
FlagRequiredDescription
--appYesApp 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-idID phân khúc (UUID)
CờBắt buộcMô tả
--appCó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
FlagBắt buộcMô tả
--appCóApp ID (UUID)
--titleCóTiêu đề phân khúc
--filterCóQuy tắc lọc. Có thể lặp lại. Xem Cú pháp bộ lọc
--descriptionKhôngMô 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
ArgumentDescription
segment-idSegment ID (UUID)
FlagRequiredDescription
--appYesApp ID (UUID)
--titleYesTiêu đề phân khúc
--filterYesQuy tắc lọc. Có thể lặp lại. Xem Cú pháp filter
--descriptionNoMô tả phân khúc
Warning

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 INMột hoặc nhiềuip_country:NOT IN:US,CA
>, >=, <, <=Mộtage:>:18
BETWEENHaitotal_revenue_usd:BETWEEN:10,100
IS NULL, IS NOT NULLKhô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ì