Truy vấn Analytics từ CLI

CLI Adapty đọc Adapty Analytics trực tiếp từ terminal, thông qua topic adapty analytics. Nó trả về các số liệu mà dashboard Analytics hiển thị cho một ứng dụng: các biểu đồ như doanh thu và MRR, chuyển đổi, phễu, retention, LTV, và install cohort.

Dùng nó để cấp cho AI agent quyền truy cập trực tiếp vào số liệu ứng dụng của bạn, kéo biểu đồ vào script hoặc bảng tính, hoặc tra cứu nhanh một chỉ số mà không cần mở dashboard.

Every analytics command is read-only and takes one app.

Trước khi bắt đầu

Chủ đề analytics sử dụng cùng cách cài đặt và đăng nhập như các 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 trong hướng dẫn quickstart. Chủ đề này yêu cầu CLI phiên bản 0.10.0 trở lên. Để xem phiên bản hiện tại, chạy lệnh adapty --version.

Khác với Export Analytics API, CLI không cần secret API key. Khi đăng nhập vào CLI, bạn có thể truy cập mọi ứng dụng mà tài khoản Adapty của bạn có quyền.

Mọi lệnh đều yêu cầu UUID của ứng dụng trong --app. Để tìm UUID, chạy:

adapty apps list

Xây dựng một truy vấn

Xây dựng mọi truy vấn theo cùng một thứ tự: tìm tên trong danh mục, tra cứu giá trị bộ lọc, rồi chạy một lệnh dữ liệu.

Liệt kê những gì analytics của ứng dụng có thể trả lời. Danh mục liệt kê mọi biểu đồ cùng đơn vị, mọi chuyển đổi, các nhóm và bộ lọc mà mỗi lệnh chấp nhận, cùng các giá trị được chấp nhận và mặc định của từng tùy chọn:
```
adapty analytics catalog --app <app-id>
```
Tên biểu đồ và chỉ số chuyển đổi như revenue, mrr, hay trial-paid đều lấy từ danh sách này. CLI không tự lưu danh sách riêng, nên khi Adapty bổ sung biểu đồ mới, CLI vẫn hoạt động bình thường mà không cần cập nhật.
Tra cứu giá trị bộ lọc. Bỏ qua bước này nếu bạn không dùng bộ lọc. Ví dụ, để liệt kê các quốc gia có thể lọc:
```
adapty analytics values --app <app-id> --dimension country
```

Chạy lệnh dữ liệu:

adapty analytics chart --app <app-id> --chart revenue \
  --date-from 2026-07-01 --date-to 2026-09-30 --group-by country

Câu trả lời có một hàng cho tổng cộng, sau đó một hàng cho mỗi nhóm.

Ví dụ

MRR quý này, so sánh với quý trước:

adapty analytics chart --app <app-id> --chart mrr \
  --date-from 2026-07-01 --date-to 2026-09-30 \
  --compare-from 2026-04-01 --compare-to 2026-06-30

Tỷ lệ chuyển đổi từ dùng thử sang trả phí hàng tháng tại hai quốc gia:

adapty analytics conversion --app <app-id> --conversion trial-paid \
  --date-from 2026-04-01 --date-to 2026-09-30 --granularity month --filter country=US,GB

Giữ chân người dùng theo quốc gia, tính từ thời điểm dùng thử:

adapty analytics retention --app <app-id> --date-from 2026-07-01 --date-to 2026-09-30 \
  --group-by country --use-trial

LTV sau 7, 30 và 90 ngày, tính trên doanh thu sau khi trừ hoa hồng và thuế, được lưu thành file CSV:

adapty analytics ltv --app <app-id> --date-from 2026-07-01 --date-to 2026-09-30 \
  --revenue-basis net --period-type days --renewal-days 7,30,90 --csv > ltv.csv

Cohort cài đặt theo tuần tính trên doanh thu sau khi trừ hoa hồng của cửa hàng:

adapty analytics cohort --app <app-id> --date-from 2026-07-01 --date-to 2026-09-30 \
  --granularity week --revenue-basis proceeds

Chọn định dạng đầu ra

Mỗi lệnh dữ liệu in ra theo một trong ba định dạng:

Đầu ra	Cờ	Dùng khi
Table	Không có	Đọc trong terminal. Mỗi bảng bắt đầu bằng tiêu đề ghi tên biểu đồ, khoảng thời gian, múi giờ và các bộ lọc. Tiền tệ có 2 chữ số thập phân. Một số trường bị bỏ qua, chẳng hạn như lý do churn trong funnel và dự đoán cohort, và một dòng bên dưới bảng sẽ ghi chú điều đó.
JSON	`--json`	Script và AI agent. Kết quả trả về từ API, nguyên vẹn, với đầy đủ các trường.
CSV	`--csv`	Bảng tính. Mỗi nhóm một hàng, với đầy đủ các trường của kết quả. Khoảng thời gian so sánh được đưa vào các cột `compare.*` của cùng hàng đó.

Bạn không thể dùng --csv và --json cùng lúc.

Trong JSON, tổng thể là mục đầu tiên của data.segments, còn data.value là con số cho toàn bộ khoảng thời gian. meta.query hiển thị truy vấn đã chạy, với mọi giá trị mặc định được điền đầy đủ và múi giờ đang áp dụng.

Đọc kết quả

Ngày tháng: --date-from và --date-to là các ngày bao gồm cả hai đầu theo múi giờ báo cáo của ứng dụng. Để đọc dữ liệu theo múi giờ khác, truyền tên IANA vào --timezone, ví dụ Europe/Berlin. meta.query.timezone cho biết múi giờ đang được áp dụng.
Doanh thu: --revenue-basis chọn cơ sở tính các giá trị tiền tệ: gross (mặc định), proceeds (sau khi trừ hoa hồng của cửa hàng), hoặc net (sau khi trừ hoa hồng và thuế). Tùy chọn này có tác dụng với ltv, cohort, và các biểu đồ hiển thị tiền tệ. Danh mục đánh dấu các biểu đồ đó bằng takes revenue_basis.
Giá trị rỗng: Giá trị rỗng có nghĩa là Adapty không có dữ liệu, không phải bằng không. Một khoảng thời gian LTV mà cohort chưa đạt đến sẽ là rỗng, tương tự với cohort không thể dự đoán được. Trong đầu ra --json, các giá trị này là null. Bảng in ra —, còn CSV để trống ô đó.
Hàng tổng cộng: Xác định tổng bằng is_total, không phải bằng key rỗng. key của một nhóm cũng có thể rỗng, ví dụ nhóm người dùng không có quốc gia.
Khóa nhóm: key của một nhóm không phải lúc nào cũng là giá trị mà --filter chấp nhận. Để lọc, hãy lấy giá trị từ analytics values.
Khoảng thời gian so sánh: Chỉ chart và conversion mới chấp nhận --compare-from và --compare-to. Khoảng thời gian so sánh có tổng và nhóm riêng, và bảng in nó dưới dạng bảng thứ hai.
Số liệu attribution: Đừng cộng các số liệu này với số liệu Attribution. Adapty tính chúng theo cách khác.

CLI trả về các số liệu của dashboard, với hai ngoại lệ:

funnel áp dụng bộ lọc cancellation_reason, còn funnel trên dashboard thì bỏ qua bộ lọc này. Do đó, hai con số có thể khác nhau.
retention cung cấp danh sách nhóm khác so với dashboard. Lấy danh sách từ catalog.

Giới hạn

Mỗi lệnh analytics chấp nhận tối đa 2 yêu cầu mỗi giây cho mỗi ứng dụng và 360 yêu cầu mỗi phút tổng cộng. CLI không bao giờ thử lại yêu cầu. Khi bạn gửi yêu cầu quá nhanh, lệnh sẽ thoát với mã 4. Với --json, lỗi bao gồm retry_after_seconds: hãy chờ khoảng thời gian đó, sau đó chạy lại lệnh.

Lỗi

Mỗi lỗi đều thoát ra với một mã lỗi cho bạn biết cần sửa gì:

Mã thoát	Nguyên nhân	Cách xử lý
2	CLI từ chối dữ liệu đầu vào trước khi gửi: UUID ứng dụng không hợp lệ, phạm vi ngày sai định dạng hoặc bị đảo ngược, khoảng thời gian so sánh thiếu một đầu, `--renewal-days` không có `--period-type days`, `--filter` không có `=`, hoặc dùng `--csv` cùng lúc với `--json`.	Sửa flag được nêu trong thông báo lỗi.
3	Bạn chưa đăng nhập, hoặc tài khoản Adapty của bạn không có quyền truy cập ứng dụng này.	Đăng nhập bằng `adapty auth login`. Nếu đã đăng nhập, tìm ID ứng dụng trong `adapty apps list` — lệnh này chỉ liệt kê các ứng dụng bạn có quyền đọc.
4	Adapty từ chối yêu cầu: biểu đồ, conversion, grouping, filter hoặc múi giờ không tồn tại; dùng `--revenue-basis` trên biểu đồ không hiển thị doanh thu; hoặc quá nhiều yêu cầu.	Sửa tên từ `adapty analytics catalog`. Với `--json`, lỗi sẽ bao gồm mã lỗi từ API. Với lỗi quá nhiều yêu cầu, xem Giới hạn.

Tài liệu tham khảo lệnh

Mỗi lệnh dữ liệu đều nhận các flag sau:

Flag	Bắt buộc	Mô tả
`--app`	Có	UUID của ứng dụng, lấy từ `adapty apps list`.
`--date-from`	Có	Ngày đầu tiên của khoảng thời gian, bao gồm cả ngày này, định dạng `YYYY-MM-DD`.
`--date-to`	Có	Ngày cuối cùng của khoảng thời gian, bao gồm cả ngày này. Không thể sớm hơn `--date-from`.
`--filter`	Không	`dimension=value[,value]`. Chỉ giữ lại dữ liệu có dimension khớp với một trong các giá trị. Lặp lại flag để lọc theo nhiều dimension. Dùng `\,` để nhập dấu phẩy trong một giá trị. Giá trị rỗng cũng là một giá trị hợp lệ: `country=` giữ lại dữ liệu không có thông tin quốc gia.
`--timezone`	Không	Múi giờ IANA của các ngày, ví dụ `Europe/Berlin`. Nếu bỏ qua, sẽ dùng múi giờ của ứng dụng.
`--csv`	Không	In bảng dạng CSV thay vì bảng thông thường. Không thể dùng cùng với `--json`.

Mỗi lệnh thêm các cờ riêng của nó vào đây.

`analytics catalog`

Liệt kê những gì analytics của ứng dụng có thể trả lời: mỗi lệnh với các tùy chọn, nhóm và bộ lọc; mỗi biểu đồ với đơn vị của nó; mọi chuyển đổi; và mọi chiều bộ lọc.

Flag	Bắt buộc	Mô tả
`--app`	Có	UUID của ứng dụng, lấy từ `adapty apps list`.

`analytics values`

Liệt kê các giá trị mà một chiều lọc nhận được cho ứng dụng. Mỗi value chính xác là những gì --filter <dimension>=<value> chấp nhận.

Flag	Required	Mô tả
`--app`	Yes	UUID của ứng dụng, lấy từ `adapty apps list`.
`--dimension`	Yes	Một chiều lọc từ `adapty analytics catalog`.

`analytics chart`

Đọc một biểu đồ: con số cho toàn bộ khoảng thời gian, các điểm dữ liệu, và các nhóm của nó.

Cờ	Bắt buộc	Mô tả
`--chart`	Có	Tên biểu đồ từ `adapty analytics catalog`, ví dụ `revenue` hoặc `mrr`.
`--group-by`	Không	Một nhóm của biểu đồ này, lấy từ catalog.
`--granularity`	Không	Độ dài một điểm dữ liệu: `day`, `week`, `month` (mặc định), `quarter`, hoặc `year`.
`--revenue-basis`	Không	`gross` (mặc định), `proceeds`, hoặc `net`. Chỉ dùng cho các biểu đồ hiển thị tiền.
`--compare-from`	Không	Ngày đầu tiên của kỳ cần so sánh. Cần có `--compare-to`.
`--compare-to`	Không	Ngày cuối cùng của kỳ cần so sánh. Cần có `--compare-from`.

`analytics conversion`

Đọc một conversion: tỷ lệ tính theo phần trăm, cùng hai số liệu được chia, cho từng điểm và nhóm.

Flag	Bắt buộc	Mô tả
`--conversion`	Có	Tên chuyển đổi từ `adapty analytics catalog`, ví dụ `trial-paid` hoặc `install-paid`.
`--group-by`	Không	Một nhóm từ catalog.
`--granularity`	Không	Độ dài một điểm: `day` (mặc định), `week`, `month`, `quarter`, hoặc `year`.
`--compare-from`	Không	Ngày đầu tiên của khoảng thời gian để so sánh. Cần có `--compare-to`.
`--compare-to`	Không	Ngày cuối cùng của khoảng thời gian để so sánh. Cần có `--compare-from`.

When the period has no conversions, meta.recommended_period in the --json output can name a period that has some.

`analytics funnel`

Đọc kênh: số lượng ở mỗi bước từ lần cài đặt đến các lần gia hạn.

Cờ	Bắt buộc	Mô tả
`--group-by`	Không	Một nhóm từ danh mục.

`analytics retention`

Đọc dữ liệu retention: số người đăng ký còn lại trong mỗi kỳ.

Flag	Bắt buộc	Mô tả
`--group-by`	Không	Một nhóm từ danh mục.
`--use-trial`	Không	Tính từ thời điểm dùng thử, không phải từ kỳ thanh toán đầu tiên.

`analytics ltv`

Đọc LTV: doanh thu trên mỗi người dùng trả phí sau mỗi lần gia hạn hoặc theo ngày.

Cờ	Bắt buộc	Mô tả
`--group-by`	Không	Một tiêu chí nhóm từ danh mục.
`--revenue-basis`	Không	`gross` (mặc định), `proceeds`, hoặc `net`.
`--period-type`	Không	`renewals` (mặc định) đếm theo lần gia hạn. `days` đếm theo số ngày kể từ khi cài đặt.
`--renewal-days`	Không	Số ngày cần đếm khi dùng `--period-type days`, cách nhau bằng dấu phẩy, theo thứ tự tăng dần, ví dụ `7,30,90`. Chỉ dùng với `--period-type days`.

`analytics cohort`

Đọc install cohorts: doanh thu, số người đăng ký, giá trị trung bình và các dự đoán của từng cohort theo lần gia hạn hoặc theo ngày. Mỗi cohort là một hàng, và ngày bắt đầu của nó là key. Các cohort không thể được nhóm lại.

Cờ	Bắt buộc	Mô tả
`--granularity`	Không	Độ dài của một cohort: `day`, `week`, `month` (mặc định), `quarter`, hoặc `year`.
`--revenue-basis`	Không	`gross` (mặc định), `proceeds`, hoặc `net`.
`--period-type`	Không	`renewals` (mặc định) đếm theo lần gia hạn. `days` đếm theo số ngày kể từ khi cài đặt.
`--renewal-days`	Không	Số ngày cần đếm với `--period-type days`, phân cách bằng dấu phẩy, theo thứ tự tăng dần. Chỉ dùng với `--period-type days`.

Tiếp theo là gì

Cách Adapty Analytics hoạt động — nguồn gốc của các con số.
Điều khiển, bộ lọc và nhóm — ý nghĩa của các bộ lọc và tùy chọn doanh thu trên dashboard.
Truy vấn Attribution từ CLI — chi tiêu, lượt cài đặt và ROAS theo kênh và chiến dịch.