Hướng dẫn bắt đầu nhanh cho Adapty Developer CLI

Adapty CLI cho phép bạn thiết lập cấu hình ứng dụng hoàn toàn từ dòng lệnh. Hãy dùng nó như một lựa chọn thay thế cho hướng dẫn bắt đầu nhanh trên dashboard nếu bạn thích làm việc với terminal hoặc MCP clients.

Sau khi hoàn thành, ứng dụng, mức độ truy cập, sản phẩm, flow hoặc paywall và placement của bạn sẽ hiển thị trong Adapty dashboard.

Nếu bạn chạy CLI trong Claude Cowork, hãy thiết lập trong Claude trước — xem Thiết lập Adapty CLI trong Claude Cowork.

1. Cài đặt CLI

Yêu cầu Node.js phiên bản 18 trở lên.

Để cài đặt CLI, chạy lệnh:

npm install -g adapty

Hoặc, chạy trực tiếp:

npx adapty auth login

2. Xác thực

Chạy lệnh đăng nhập để kết nối CLI với tài khoản Adapty của bạn.

adapty auth login

CLI sẽ mở một tab trình duyệt. Khớp mã hiển thị trong terminal với mã hiển thị trên trình duyệt, sau đó nhấp Authorize. Terminal xác nhận khi quá trình xác thực hoàn tất.

3. Tạo app của bạn

Một app trong Adapty đại diện cho ứng dụng di động của bạn. Một Adapty app kết nối với cả App Store lẫn Google Play — bạn chỉ cần tạo một app, bất kể bạn phát hành trên bao nhiêu cửa hàng.

adapty apps create --title "My App" --platform ios --platform android --apple-bundle-id com.example.app --google-bundle-id com.example.app

adapty apps create --title "My App" --platform ios --apple-bundle-id com.example.app

adapty apps create --title "My App" --platform android --google-bundle-id com.example.app

Lệnh trả về một <app-id>. Dùng ID này trong tất cả các lệnh tiếp theo.

4. Tạo mức độ truy cập (tùy chọn)

Mức độ truy cập kiểm soát những gì người dùng có thể truy cập sau khi mua hàng. Thay vì kiểm tra xem người dùng đã mua sản phẩm cụ thể nào, app của bạn chỉ cần kiểm tra xem người dùng có mức độ truy cập tương ứng hay không. Cách này giúp tách biệt logic app của bạn khỏi các ID sản phẩm cụ thể.

Mức độ truy cập premium được tự động tạo cùng với mỗi app mới. Với hầu hết các app, bạn có thể bỏ qua bước này. Dùng premium làm access level ID ở bước 5.

Chỉ chạy lệnh này nếu các sản phẩm khác nhau mở khóa các tính năng khác nhau cho các nhóm người dùng khác nhau — ví dụ, nếu người đăng ký “Basic” và người đăng ký “Pro” có quyền truy cập vào các phần khác nhau của app.

adapty access-levels create --app <app-id> --sdk-id "pro" --title "Pro"

• --sdk-id là định danh bạn sẽ dùng trong code app để kiểm tra xem một tính năng có nên khả dụng với người dùng hay không (ví dụ: if user.hasAccessLevel("pro")). Nếu bạn bỏ qua bước này và dùng mức độ truy cập mặc định, --sdk-id của nó là premium.
• --title là nhãn hiển thị để bạn tham khảo trên Adapty dashboard.

Lệnh trả về một <access-level-id>.

5. Tạo sản phẩm

Trong Adapty, một sản phẩm đại diện cho bất kỳ thứ gì app của bạn bán — gói đăng ký hoặc sản phẩm mua một lần. Các mục từ App Store Connect và Google Play có thể được nhóm thành một sản phẩm Adapty duy nhất và quản lý từ một nơi.

Bạn sẽ cần ID sản phẩm từ mỗi cửa hàng: Apple product ID từ App Store Connect, và Android product ID cùng base plan ID từ Google Play Console. Xem Sản phẩm để biết chi tiết về nơi tìm chúng.

Nếu bạn đã bỏ qua bước 4, hãy dùng default_access_level.id được trả về từ lệnh apps create ở bước 3 làm <access-level-id> của bạn.

adapty products create --app <app-id> --title "My Product" --access-level-id <access-level-id> --period monthly --ios-product-id <your.apple.id> --android-product-id <your.google.id> --android-base-plan-id <your.base-plan.id>

adapty products create --app <app-id> --title "My Product" --access-level-id <access-level-id> --period monthly --ios-product-id <your.apple.id>

adapty products create --app <app-id> --title "My Product" --access-level-id <access-level-id> --period monthly --android-product-id <your.google.id> --android-base-plan-id <your.base-plan.id>

Lệnh này trả về một <product-id>.

Nếu bạn cũng bán sản phẩm này trên web thông qua Stripe hoặc Paddle, hãy thêm các ID đó vào cùng lệnh. Xem products create trong tài liệu tham chiếu lệnh.

6. Tạo flow hoặc paywall

Mỗi sản phẩm phải được đặt trong một flow hoặc paywall trước khi có thể hiển thị trong ứng dụng của bạn. Hãy chọn một trong hai:

• Flow là một màn hình, hoặc một chuỗi màn hình, mà bạn thiết kế trong Flow & Paywall Builder không cần code và SDK Adapty sẽ render trực tiếp: màn hình paywall, onboarding, quiz. Chọn flow khi bạn muốn Adapty tự render màn hình mua hàng. Flow yêu cầu Adapty SDK 4.0 trở lên.
• Paywall là một tập hợp các sản phẩm không kèm thiết kế. Chọn paywall khi bạn tự render màn hình mua hàng trong code ứng dụng và chỉ cần Adapty cung cấp danh sách sản phẩm, có thể kèm theo remote config.

A placement serves one content type, so decide before step 7.

6a. Tạo một flow

CLI tạo bản ghi flow. Các màn hình của nó nằm trong một builder config — một tài liệu JSON mà CLI không tự tạo ra. Để soạn thảo config từ terminal, hãy dùng flow-generator skill, công cụ này sẽ điều khiển CLI thay bạn.

Tạo flow:

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

Lệnh trả về một <flow-id>.

Xây dựng các màn hình bằng flow-generator skill hoặc trong Flow & Paywall Builder. Dù theo cách nào, kết quả vẫn là một bản nháp đã lưu mà người dùng chưa thể thấy.

Xuất bản flow:

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

Lệnh này yêu cầu xác nhận. Quá trình xuất bản chạy ở nền, vì vậy hãy kiểm tra trạng thái bằng adapty flows get --app <app-id> <flow-id> cho đến khi hiển thị published. Nếu gặp publication_failed, flows config get sẽ cho biết nguyên nhân. Một placement chỉ chấp nhận flow đã được xuất bản.

6b. Tạo paywall

Một paywall là nơi chứa các sản phẩm của bạn.

adapty paywalls create --app <app-id> --title "My Paywall" --product-id <product-id>

adapty paywalls create --app <app-id> --title "My Paywall" --product-id <product-id-1> --product-id <product-id-2>

Lệnh này trả về một <paywall-id>.

7. Tạo một placement

Placement là điểm trong ứng dụng của bạn nơi bạn hiển thị một flow hoặc paywall. Thứ duy nhất bạn hardcode trong code ứng dụng là placement ID. Mọi thứ còn lại — flow hay paywall nào sẽ hiển thị và cho những người dùng nào — đều được quản lý trên dashboard mà không cần phát hành phiên bản ứng dụng mới.

--developer-id là chuỗi bạn sẽ tham chiếu sau này trong code ứng dụng khi yêu cầu Adapty hiển thị nội dung gì tại điểm này. Hãy chọn tên mô tả vị trí, chẳng hạn như "main", "onboarding", hoặc "settings".

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

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

Cờ --audiences kiểm soát flow hoặc paywall nào được hiển thị cho người dùng nào. Các ví dụ trên đặt một đối tượng mặc định duy nhất: mọi người dùng tại placement này đều thấy cùng một nội dung. Một placement chỉ phục vụ một loại nội dung, vì vậy mọi mục đối tượng phải có cùng content_type. Để nhắm mục tiêu theo phân khúc, xem Cấu trúc Audiences trong tài liệu tham khảo lệnh.

Tiếp theo là gì

Tất cả các thực thể hiện đã hiển thị trong Adapty Dashboard. Tiếp theo:

• Thay đổi một flow sau này — mô tả thay đổi cho flow-generator skill, hoặc mở flow trong Flow & Paywall Builder.
• Hiển thị paywall trong app của bạn — lấy paywall và các sản phẩm của nó bằng SDK và tự xây dựng màn hình trong code của bạn.
• Tích hợp Adapty SDK — thêm SDK vào app để lấy và hiển thị placement.
• Định tuyến các phân khúc người dùng khác nhau đến các flow hoặc paywall khác nhau — xem placements update và segments list trong tài liệu tham khảo lệnh.