Lệnh Flows

Flows là các paywall và onboarding bạn xây dựng trong Flow & Paywall Builder. CLI quản lý bản ghi flow, cấu hình builder và quá trình xuất bản. Cấu hình builder là một tài liệu JSON lớn mà Flow & Paywall Builder thường tạo ra, và CLI không tự tạo cấu hình này. Để soạn thảo hoặc chỉnh sửa cấu hình từ terminal, hãy dùng skill flow-generator, vốn điều khiển các lệnh này cho bạn. Trước khi xuất bản, skill flow-audit sẽ kiểm tra xem flow đã sẵn sàng cho môi trường production chưa. Các lệnh được liệt kê ở đây như một tài liệu tham khảo.

adapty flows list

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

adapty flows list --app <app-id>

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

Chấp nhận cờ phân trang.

adapty flows get

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

adapty flows get --app <app-id> <flow-id>

Argument	Description
`flow-id`	Flow ID (UUID)

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

Kết quả trả về gồm các trường id, name, status và updated_at. Giá trị của status là một trong các trạng thái sau:

Trạng thái	Ý nghĩa
`draft`	Flow chưa được xuất bản lần nào
`published`	Phiên bản hiện tại đang hoạt động
`dirty`	Flow đã được xuất bản trước đó, và phiên bản hiện tại có thay đổi chưa được xuất bản. Người dùng vẫn thấy phiên bản đã xuất bản lần cuối
`publishing`	Đang trong quá trình xuất bản
`publication_failed`	Lần xuất bản gần nhất thất bại. Hãy sửa cấu hình và xuất bản lại
`archived`	Flow đã được lưu trữ

adapty flows create

Tạo một flow. Flow mới có tên và chưa có config. Để thêm config, dùng flows config update.

adapty flows create --app <app-id> --name "Onboarding"

Flag	Bắt buộc	Mô tả
`--app`	Có	App ID (UUID)
`--name`	Có	Tên flow

adapty flows update

Đổi tên một flow.

adapty flows update --app <app-id> <flow-id> --name "Onboarding v2"

Argument	Description
`flow-id`	Flow ID (UUID)

Flag	Required	Description
`--app`	Yes	App ID (UUID)
`--name`	Yes	Tên flow mới

adapty flows publish

Xuất bản phiên bản hiện tại của một flow cho người dùng.

adapty flows publish --app <app-id> <flow-id>

Đối số	Mô tả
`flow-id`	ID của flow (UUID)

Cờ	Bắt buộc	Mô tả
`--app`	Có	ID của ứng dụng (UUID)
`--yes`, `-y`	Không	Xuất bản mà không cần xác nhận. Bắt buộc khi đầu ra được chuyển qua pipe hoặc dùng `--json`

Vì việc xuất bản ảnh hưởng trực tiếp đến những gì người dùng thấy, lệnh này sẽ in tên flow và yêu cầu xác nhận. Bất kỳ câu trả lời nào khác y đều hủy lệnh với mã thoát 1. Khi dùng --json hoặc trong pipe, lệnh sẽ từ chối với mã thoát 2 thay vì chờ câu trả lời, vì vậy hãy truyền --yes trong các script và phiên agent.

Quá trình xuất bản là bất đồng bộ: phản hồi trả về status: publishing, và flow chưa được kích hoạt ngay. Hãy gọi flows get theo chu kỳ cho đến khi trạng thái chuyển thành published hoặc publication_failed. Nếu là publication_failed, hãy dùng flows config get để xem nguyên nhân.

Xuất bản sẽ thất bại với HTTP 400 khi flow chưa có config, khi config không thể xuất bản được, hoặc khi phiên bản hiện tại đã được kích hoạt. Để kiểm tra config trước khi xuất bản, hãy dùng flows config validate.

adapty flows config get

Đọc cấu hình builder của một flow.

adapty flows config get --app <app-id> <flow-id>

Argument	Description
`flow-id`	Flow ID (UUID)

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

Phản hồi chứa config, remote_configs, status, và updated_at. updated_at là timestamp tính bằng mili giây của lần thay đổi config gần nhất. Truyền giá trị này vào flows config update qua tham số --expected-updated-at để tránh ghi đè khi có chỉnh sửa đồng thời. Một flow chưa từng được ghi config sẽ trả về 404.

Sau khi thực hiện publication, phản hồi cũng chứa ba trường mô tả kết quả. Đọc các trường này khi flows get báo publication_failed:

Field	Description
`publication_status`	Trạng thái xuất bản của phiên bản flow này: `transforming`, `transformed`, `uploading`, `uploaded`, `published`, hoặc `failed`
`transform_error`	Lỗi transform thô — có thể là payload JSON liệt kê các vấn đề hoặc một chuỗi tóm tắt
`publication_error`	Thông báo dễ đọc cho một lần xuất bản thất bại

adapty flows config update

Ghi cấu hình builder của một flow.

adapty flows config update --app <app-id> <flow-id> --config-file config.json

Argument	Description
`flow-id`	Flow ID (UUID)

Cờ	Bắt buộc	Mô tả
`--app`	Có	ID ứng dụng (UUID)
`--config`	Một trong hai	Cấu hình builder dưới dạng chuỗi JSON
`--config-file`	Một trong hai	Đường dẫn đến file JSON chứa cấu hình builder, hoặc `-` để đọc từ stdin
`--remote-configs`	Không	Mảng JSON gồm các phần tử `{locale, data}`, trong đó `data` là Remote Config dưới dạng chuỗi
`--expected-updated-at`	Không	Giá trị `updated_at` lấy từ lệnh `flows config get` trước đó. Nếu cấu hình đã thay đổi sau lần đọc đó, lệnh sẽ thất bại thay vì ghi đè. Bỏ qua để ghi đè vô điều kiện

Việc ghi config sẽ lưu bản nháp và không xuất bản ngay. Trên một flow đã xuất bản, thao tác ghi sẽ tạo ra một phiên bản mới: trạng thái của flow sẽ chuyển thành dirty, và người dùng vẫn thấy phiên bản đã xuất bản cho đến khi bạn chạy flows publish.

adapty flows config validate

Kiểm tra xem một builder config có thể publish được hay không, mà không cần lưu.

adapty flows config validate --app <app-id> <flow-id> --config-file config.json

Argument	Description
`flow-id`	Flow ID (UUID)

Flag	Required	Description
`--app`	Yes	App ID (UUID)
`--config`	One of the two	Builder config dạng chuỗi JSON
`--config-file`	One of the two	Đường dẫn đến file JSON chứa builder config, hoặc `-` để đọc từ stdin

Phản hồi bao gồm valid và danh sách issues. Khi cấu hình không thể xuất bản, lệnh thoát với mã 1, giúp các script có thể dựa vào đó để kiểm soát luồng xử lý.

adapty flows config preview

Hiển thị file config cục bộ trên trình duyệt. Lệnh này không thực hiện lệnh gọi API và không nhận flag --app.

adapty flows config preview ./config.json --screen <screen-id> --device iphone-14 --orientation portrait

Đối số	Mô tả
`config-file`	Đường dẫn đến file JSON config của builder cục bộ

Flag	Mặc định	Mô tả
`--screen`	Màn hình đầu tiên của flow	ID màn hình cần hiển thị
`--device`	`iphone-14`	Khung thiết bị để hiển thị
`--orientation`	`portrait`	`portrait` hoặc `landscape`

Trong terminal, lệnh sẽ mở bản xem trước trong trình duyệt của bạn. Khi dùng pipe hoặc với --json, lệnh sẽ in URL ra thay thế. URL chứa toàn bộ cấu hình nên khá dài: hãy pipe vào công cụ chụp ảnh màn hình thay vì in ra trực tiếp. Các cấu hình vượt quá khoảng 32 KB sẽ render chậm.

adapty flows media upload

Tải lên một hình ảnh để sử dụng trong cấu hình flow.

adapty flows media upload --app <app-id> ./hero.png

Argument	Description
`file`	Đường dẫn đến file hình ảnh

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

Định dạng được chấp nhận: GIF, HEIC, JPEG, PNG, SVG và WebP. Phản hồi chứa id, name và url CDN của hình ảnh để tham chiếu từ cấu hình.

Tham khảo lệnh — tất cả các chủ đề CLI, cờ toàn cục và cờ phân trang.