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 dashboard quickstart nếu bạn thích làm việc trên terminal hoặc dùng MCP clients.

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

Nếu bạn chạy CLI trong Claude Cowork, hãy cho phép các domain của Adapty trước khi bắt đầu — xem Chạy CLI trong 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 paywall

Một paywall là nơi chứa các sản phẩm của bạn. Trong Adapty, paywall là cách duy nhất để đưa sản phẩm đến người dùng. Mọi sản phẩm đều phải nằm trong một paywall trước khi có thể xuất hiện trong app 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 trả về một <paywall-id>.

7. Tạo placement

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

--developer-id là chuỗi bạn sẽ tham chiếu sau này trong code app khi hỏi Adapty paywall nào cần hiển thị tại điểm này. Chọn tên mô tả vị trí, như "main", "onboarding", hoặc "settings".

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

Cờ --audiences kiểm soát paywall nào được hiển thị cho người dùng nào. Ví dụ trên thiết lập 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 paywall.

Chạy CLI trong Cowork

Claude Cowork chạy các lệnh trong một sandbox chỉ kết nối được với những domain được phép. Cho đến khi bạn cho phép Adapty, CLI không thể đăng nhập hay đọc tài khoản của bạn. Bỏ qua phần này nếu bạn chạy CLI từ terminal của chính mình.

Cho phép cả adapty.io và *.adapty.io. Wildcard không bao gồm apex domain trong hầu hết các cách triển khai allowlist. Bản thân CLI kết nối tới api.adapty.io, còn một agent đọc tài liệu Adapty trong khi hoạt động sẽ kết nối tới apex domain.

Cowork áp dụng các cài đặt này khi một task bắt đầu. Nếu bạn thay đổi chế độ truy cập hoặc thêm domain trong lúc đang hội thoại, hội thoại đó vẫn giữ nguyên cài đặt ban đầu — hãy bắt đầu một task mới.

Mỗi task cũng khởi động trên một máy sạch: không có CLI, không có token, và không có cấu hình nào được giữ lại từ phiên trước, vì vậy các bước cài đặt và đăng nhập phải lặp lại ở đầu mỗi task.

Tài khoản cá nhân

Bạn tự thiết lập danh sách cho phép:

1. Trong Claude, mở Settings → Capabilities.
2. Bật Code execution and file creation. Khối Allow network egress sẽ ẩn cho đến khi bạn thực hiện bước này.
3. Bật Allow network egress.
4. Trong Domain allowlist, chọn Package managers only.
5. Trong Additional allowed domains, thêm adapty.io, rồi thêm *.adapty.io.

Chế độ truy cập còn lại, All domains, cho phép sandbox truy cập bất kỳ trang web nào. Khi chọn tùy chọn này, bạn không cần thêm các domain của Adapty.

Không gian làm việc doanh nghiệp

Quản trị viên kiểm soát danh sách cho phép. Hãy nhờ họ thêm cả hai domain vào không gian làm việc.

Tiếp theo là gì

Tất cả các thực thể giờ đã hiển thị trên Adapty Dashboard. Tiếp theo:

• Thiết kế paywall của bạn — dùng Paywall Builder không cần code để thêm hình ảnh, bố cục và nội dung cho paywall vừa tạo.
• Tích hợp SDK Adapty — thêm SDK vào ứng dụng để tải và hiển thị placement.
• Định tuyến các phân khúc người dùng khác nhau đến các paywall khác nhau — xem placements update và segments list trong tài liệu tham chiếu lệnh.