Tích hợp Adapty vào ứng dụng Capacitor của bạn với sự hỗ trợ của AI

Hướng dẫn này sẽ đưa bạn qua từng bước tích hợp Adapty vào ứng dụng Capacitor bằng công cụ lập trình AI — bạn chỉ cần cung cấp đúng tài liệu Adapty theo đúng thứ tự.

Trước khi bắt đầu: thiết lập dashboard

Adapty yêu cầu một số cấu hình trên dashboard trước khi bạn viết bất kỳ dòng code SDK nào. Bạn có thể thực hiện điều này bằng một LLM skill tương tác, hoặc thủ công qua Dashboard.

Cách dùng Skill (khuyến nghị)

Adapty CLI skill cho phép LLM của bạn thiết lập ứng dụng, sản phẩm, mức độ truy cập, paywall và placement trực tiếp — mà không cần mở Dashboard cho từng bước. Bạn chỉ cần kết nối cửa hàng trong Dashboard.

npx skills add adaptyteam/adapty-cli --skill adapty-cli

Sau khi thêm skill, chạy /adapty-cli trong agent của bạn. Nó sẽ hướng dẫn bạn qua từng bước — kể cả khi nào cần mở Dashboard để kết nối cửa hàng.

Phương pháp cấu hình qua Dashboard

Nếu bạn muốn tự cấu hình mọi thứ theo cách thủ công, đây là những gì bạn cần chuẩn bị trước khi viết code. LLM của bạn không thể tra cứu các giá trị trên dashboard thay bạn — bạn sẽ cần tự cung cấp chúng.

Kết nối cửa hàng ứng dụng: Trong Adapty Dashboard, vào App settings → General. Kết nối cả App Store và Google Play nếu ứng dụng Capacitor của bạn nhắm đến cả hai nền tảng. Đây là yêu cầu bắt buộc để mua hàng hoạt động được. Kết nối cửa hàng ứng dụng
Sao chép Public SDK key của bạn: Trong Adapty Dashboard, vào App settings → General, sau đó tìm phần API keys. Trong code, đây là chuỗi bạn truyền vào adapty.activate().
Tạo ít nhất một sản phẩm: Trong Adapty Dashboard, vào trang Products. Bạn không tham chiếu trực tiếp các sản phẩm trong code — Adapty phân phối chúng thông qua các paywall. Thêm sản phẩm
Tạo paywall và placement: Trong Adapty Dashboard, tạo một paywall trên trang Paywalls, sau đó gán nó vào một placement trên trang Placements. Trong code, placement ID là chuỗi bạn truyền vào adapty.getFlow(). Tạo paywall
Thiết lập mức độ truy cập: Trong Adapty Dashboard, cấu hình theo từng sản phẩm trên trang Products. Trong code, chuỗi được kiểm tra là profile.accessLevels['premium']?.isActive. Mức độ truy cập premium mặc định phù hợp với hầu hết các ứng dụng. Nếu người dùng trả phí được truy cập các tính năng khác nhau tùy theo sản phẩm (ví dụ: gói basic và gói pro), hãy tạo thêm mức độ truy cập trước khi bắt đầu lập trình.

Khi bạn đã có đủ năm thông tin trên, bạn đã sẵn sàng để viết code. Hãy nói với LLM của bạn: “Public SDK key của tôi là X, placement ID của tôi là Y” để nó có thể tạo ra code khởi tạo và lấy flow chính xác.

Thiết lập khi sẵn sàng

Những bước này không bắt buộc để bắt đầu code, nhưng bạn sẽ cần chúng khi tích hợp trở nên hoàn chỉnh hơn:

A/B test: Cấu hình trên trang Placements. Không cần thay đổi code. A/B test
Thêm paywall và placement: Thêm các lệnh gọi getPaywall với các placement ID khác nhau.
Tích hợp analytics: Cấu hình trên trang Integrations. Cách thiết lập khác nhau tùy theo tích hợp. Xem tích hợp analytics và tích hợp attribution.

Cung cấp tài liệu Adapty cho LLM

Sử dụng Context7 (khuyến nghị)

Context7 là một MCP server cho phép LLM của bạn truy cập trực tiếp vào tài liệu Adapty cập nhật mới nhất. LLM sẽ tự động tìm và lấy đúng tài liệu cần thiết dựa trên câu hỏi của bạn — không cần dán URL thủ công.

Context7 hoạt động với Cursor, Claude Code, Windsurf và các công cụ tương thích MCP khác. Để cài đặt, chạy lệnh:

npx ctx7 setup

Lệnh này sẽ tự động nhận diện trình soạn thảo của bạn và cấu hình Context7 server. Để cài đặt thủ công, xem kho lưu trữ Context7 trên GitHub. Sau khi cấu hình xong, hãy tham chiếu thư viện Adapty trong các prompt của bạn:

Use the adaptyteam/adapty-docs library to look up how to install the Capacitor SDK

Dù Context7 giúp bạn không cần dán link tài liệu thủ công, thứ tự triển khai vẫn rất quan trọng. Hãy làm theo hướng dẫn triển khai bên dưới từng bước một để đảm bảo mọi thứ hoạt động đúng.

Dùng tài liệu dạng văn bản thuần

Bạn có thể truy cập bất kỳ tài liệu Adapty nào dưới dạng Markdown thuần. Thêm .md vào cuối URL, hoặc nhấn Copy for LLM bên dưới tiêu đề bài viết. Ví dụ: adapty-cursor-capacitor.md.

Mỗi giai đoạn trong hướng dẫn triển khai bên dưới đều có khối “Gửi cho LLM của bạn” với các link .md để dán vào.

Để lấy nhiều tài liệu hơn cùng một lúc, xem file index và các tập con theo nền tảng bên dưới.

Hướng dẫn triển khai

Phần còn lại của hướng dẫn này sẽ dẫn bạn qua tích hợp Adapty theo đúng thứ tự triển khai. Mỗi giai đoạn bao gồm tài liệu cần gửi cho LLM, kết quả mong đợi khi hoàn thành và các lỗi thường gặp.

Lập kế hoạch tích hợp

Trước khi bắt đầu viết code, hãy nhờ LLM phân tích dự án của bạn và tạo một kế hoạch triển khai. Nếu công cụ AI của bạn hỗ trợ chế độ lập kế hoạch (như chế độ plan mode của Cursor hoặc Claude Code), hãy dùng nó để LLM có thể đọc cả cấu trúc dự án lẫn tài liệu Adapty trước khi viết bất kỳ dòng code nào.

Hãy cho LLM biết bạn đang dùng cách tiếp cận nào cho in-app purchase — điều này ảnh hưởng đến các hướng dẫn mà LLM sẽ theo:

Adapty Flow Builder: Bạn tạo flow trong trình xây dựng không cần code của Adapty, và SDK sẽ tự động render chúng.
Paywalls tạo thủ công: Bạn tự xây dựng giao diện paywall bằng code nhưng vẫn dùng Adapty để lấy sản phẩm và xử lý thanh toán.
Observer mode: Bạn giữ nguyên hạ tầng thanh toán hiện có và chỉ dùng Adapty cho analytics và tích hợp.

Chưa biết chọn cái nào? Đọc bảng so sánh trong phần quickstart.

Cài đặt và cấu hình SDK

Thêm dependency Adapty SDK bằng npm và kích hoạt nó với Public SDK key của bạn. Đây là nền tảng — mọi thứ khác đều không hoạt động nếu thiếu bước này.

Hướng dẫn: Cài đặt & cấu hình Adapty SDK

Hướng dẫn này dành cho Adapty Capacitor SDK v4 (beta) — API được hướng dẫn trong quickstart. v4 là bản phát hành trước, vì vậy hãy đảm bảo LLM của bạn ghim đúng phiên bản (npm install @adapty/capacitor@4.0.0-beta.2) thay vì cài đặt phiên bản ổn định 3.x mới nhất. Xem phần cài đặt SDK 4.0 và hướng dẫn migration.

Gửi nội dung này cho LLM của bạn:

Read these Adapty docs before writing code:
- https://adapty.io/docs/vi/sdk-installation-capacitor.md

Checkpoint

Kết quả mong đợi: Ứng dụng build và chạy được trên cả iOS và Android. Console hiển thị log kích hoạt Adapty.
Lưu ý: “Public API key is missing” → kiểm tra lại xem bạn đã thay thế placeholder bằng key thật từ App settings chưa.

Hiển thị paywall và xử lý giao dịch mua

Lấy paywall theo placement ID, hiển thị nó và xử lý các sự kiện mua hàng. Các hướng dẫn bạn cần sẽ phụ thuộc vào cách bạn xử lý giao dịch mua.

Hãy kiểm tra từng giao dịch mua trong sandbox trong quá trình thực hiện — đừng đợi đến cuối. Xem Kiểm tra giao dịch mua trong sandbox để biết hướng dẫn cài đặt.

Hướng dẫn:

Read these Adapty docs before writing code:
- https://adapty.io/docs/vi/capacitor-quickstart-paywalls.md
- https://adapty.io/docs/vi/capacitor-get-pb-paywalls.md
- https://adapty.io/docs/vi/capacitor-present-paywalls.md
- https://adapty.io/docs/vi/capacitor-handling-events.md
- https://adapty.io/docs/vi/capacitor-handle-paywall-actions.md

Checkpoint

Kết quả mong đợi: Flow hiển thị với các sản phẩm bạn đã cấu hình. Nhấn vào một sản phẩm sẽ kích hoạt hộp thoại mua hàng sandbox.
Lưu ý: Flow trống hoặc lỗi getFlow → kiểm tra xem placement ID có khớp chính xác với dashboard không và placement đã được gán đối tượng chưa.

Hướng dẫn:

Read these Adapty docs before writing code:
- https://adapty.io/docs/vi/capacitor-quickstart-manual.md
- https://adapty.io/docs/vi/fetch-paywalls-and-products-capacitor.md
- https://adapty.io/docs/vi/present-remote-config-paywalls-capacitor.md
- https://adapty.io/docs/vi/capacitor-making-purchases.md
- https://adapty.io/docs/vi/capacitor-restore-purchase.md

Checkpoint

Expected: Paywall tùy chỉnh của bạn hiển thị các sản phẩm lấy từ Adapty. Nhấn vào một sản phẩm sẽ kích hoạt hộp thoại mua hàng sandbox.
Gotcha: Mảng sản phẩm trống → kiểm tra xem paywall đã được gán sản phẩm trong dashboard chưa và placement có đối tượng chưa.

Hướng dẫn:

Read these Adapty docs before writing code:
- https://adapty.io/docs/vi/observer-vs-full-mode.md
- https://adapty.io/docs/vi/implement-observer-mode-capacitor.md
- https://adapty.io/docs/vi/report-transactions-observer-mode-capacitor.md

Checkpoint

Kết quả mong đợi: Sau khi thực hiện mua hàng sandbox bằng flow mua hàng hiện có của bạn, giao dịch sẽ xuất hiện trong Event Feed trên Adapty dashboard.
Lưu ý: Không có sự kiện nào → hãy kiểm tra xem bạn đã báo cáo giao dịch cho Adapty chưa và thông báo máy chủ đã được cấu hình cho cả hai cửa hàng chưa.

Kiểm tra trạng thái gói đăng ký

Sau khi mua hàng, kiểm tra hồ sơ người dùng để xác nhận mức độ truy cập đang hoạt động nhằm kiểm soát nội dung premium.

Hướng dẫn: Kiểm tra trạng thái gói đăng ký

Gửi cho LLM của bạn:

Read these Adapty docs before writing code:
- https://adapty.io/docs/vi/capacitor-check-subscription-status.md

Checkpoint

Kết quả mong đợi: Sau khi mua hàng sandbox, profile.accessLevels['premium']?.isActive trả về true.
Lỗi thường gặp: accessLevels rỗng sau khi mua → kiểm tra sản phẩm đã được gán mức độ truy cập trong dashboard chưa.

Xác định người dùng

Liên kết tài khoản người dùng trong ứng dụng của bạn với hồ sơ người dùng Adapty để lịch sử mua hàng được lưu giữ trên tất cả các thiết bị.

Bỏ qua bước này nếu ứng dụng của bạn không có xác thực.

Hướng dẫn: Xác định người dùng

Gửi nội dung này cho LLM của bạn:

Read these Adapty docs before writing code:
- https://adapty.io/docs/vi/capacitor-quickstart-identify.md

Checkpoint

Kết quả mong đợi: Sau khi gọi adapty.identify(), phần Profiles trên dashboard hiển thị custom user ID của bạn.
Lưu ý: Gọi identify sau khi kích hoạt nhưng trước khi tải paywall để tránh việc attribution hồ sơ người dùng ẩn danh.

Chuẩn bị phát hành

Khi tích hợp của bạn hoạt động tốt trong sandbox, hãy xem qua danh sách kiểm tra phát hành để đảm bảo mọi thứ đã sẵn sàng cho môi trường production.

Hướng dẫn: Danh sách kiểm tra phát hành

Gửi nội dung này cho LLM của bạn:

Read these Adapty docs before releasing:
- https://adapty.io/docs/vi/release-checklist.md

Checkpoint

Kết quả mong đợi: Tất cả các mục trong danh sách đã được xác nhận: kết nối cửa hàng, thông báo máy chủ, luồng mua hàng, kiểm tra mức độ truy cập và các yêu cầu về quyền riêng tư.
Lưu ý: Thiếu thông báo máy chủ → cấu hình App Store Server Notifications trong App settings → iOS SDK và Google Play Real-Time Developer Notifications trong App settings → Android SDK.

Tệp chỉ mục tài liệu dạng văn bản thuần túy

Nếu bạn cần cung cấp cho LLM của mình ngữ cảnh rộng hơn ngoài các trang riêng lẻ, chúng tôi lưu trữ các tệp chỉ mục liệt kê hoặc tổng hợp toàn bộ tài liệu Adapty:

llms.txt: Liệt kê tất cả các trang với các liên kết .md. Đây là tiêu chuẩn mới nổi giúp các LLM có thể truy cập website. Lưu ý rằng với một số AI agent (ví dụ: ChatGPT), bạn cần tải llms.txt xuống và tải lên chat dưới dạng file.
llms-full.txt: Toàn bộ tài liệu Adapty được gộp thành một file duy nhất. Rất lớn — chỉ dùng khi bạn cần xem toàn bộ nội dung.
Các file dành riêng cho Capacitor: capacitor-llms.txt và capacitor-llms-full.txt: Các tập con theo nền tảng giúp tiết kiệm token so với toàn bộ tài liệu.