--- title: "Tích hợp Adapty vào ứng dụng Capacitor của bạn với sự hỗ trợ của AI" description: "Hướng dẫn từng bước tích hợp Adapty vào ứng dụng Capacitor của bạn bằng Cursor, Context7, ChatGPT, Claude hoặc các công cụ AI khác." --- Hướng dẫn này sẽ dẫn bạn qua từng bước tích hợp Adapty vào ứng dụng Capacitor với sự hỗ trợ của công cụ AI — bạn chỉ cần cung cấp đúng tài liệu Adapty theo đúng thứ tự. For a fully automated integration, use the [adapty-sdk-integration skill](https://github.com/adaptyteam/adapty-sdk-integration-skill): it runs the whole integration from your AI coding tool in one command. ## Trước khi bắt đầu: thiết lập dashboard \{#before-you-start-dashboard-setup\} 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ị) \{#skill-approach-recommended\} 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](integrate-payments) 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. ### Cách thiết lập thủ công qua Dashboard \{#dashboard-approach\} Nếu bạn muốn cấu hình mọi thứ thủ công, đây là những gì bạn cần trước khi viết code. LLM của bạn không thể tự tra cứu các giá trị trên dashboard — bạn sẽ phải cung cấp chúng. 1. **Kết nối cửa hà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 hỗ trợ cả hai nền tảng. Đây là bước bắt buộc để giao dịch mua hàng hoạt động. [Kết nối cửa hàng](integrate-payments) 2. **Sao chép Public SDK key**: Trong Adapty Dashboard, vào **App settings → General**, rồi tìm phần **API keys**. Trong code, đây là chuỗi bạn truyền vào `adapty.activate()`. 3. **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 sản phẩm trực tiếp trong code — Adapty phân phối chúng qua paywall. [Thêm sản phẩm](quickstart-products) 4. **Tạo một paywall và một placement**: Trong Adapty Dashboard, tạo paywall trên trang **Paywalls**, rồi 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.getPaywall()`. [Tạo paywall](quickstart-paywalls) 5. **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 ứ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` so với gói `pro`), hãy [tạo thêm mức độ truy cập](assigning-access-level-to-a-product) trước khi bắt đầu code. :::tip Khi đã có đủ năm yếu tố 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 code khởi tạo và lấy paywall chính xác. ::: ### Thiết lập khi sẵn sàng \{#set-up-when-ready\} 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](ab-tests) - **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](analytics-integration) và [tích hợp attribution](attribution-integration). ## Cung cấp tài liệu Adapty cho LLM \{#feed-adapty-docs-to-your-llm\} ### Dùng Context7 (khuyến nghị) \{#use-context7-recommended\} [Context7](https://context7.com) là một MCP server cho phép LLM của bạn truy cập trực tiếp tài liệu Adapty mới nhất. LLM sẽ tự động lấy đúng tài liệu 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: ``` npx ctx7 setup ``` Lệnh này sẽ tự phát hiện editor của bạn và cấu hình Context7 server. Để cài đặt thủ công, xem [kho GitHub của Context7](https://github.com/upstash/context7). Sau khi cấu hình, tham chiếu thư viện Adapty trong prompt của bạn: ``` Use the adaptyteam/adapty-docs library to look up how to install the Capacitor SDK ``` :::warning 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](#implementation-walkthrough) 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 \{#use-plain-text-docs\} 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](https://adapty.io/docs/vi/adapty-cursor-capacitor.md). Mỗi giai đoạn trong [hướng dẫn triển khai](#implementation-walkthrough) 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](#plain-text-doc-index-files) bên dưới. ## Hướng dẫn triển khai \{#implementation-walkthrough\} 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ên kế hoạch tích hợp \{#plan-your-integration\} Trước khi bắt đầu code, hãy yêu cầu LLM phân tích dự án và tạo 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 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 code. Hãy cho LLM biết bạn dùng cách nào để xử lý giao dịch mua hàng — điều này ảnh hưởng đến các hướng dẫn nó cần theo: - [**Adapty Paywall Builder**](adapty-paywall-builder): Bạn tạo paywall trong công cụ no-code của Adapty, và SDK tự động hiển thị chúng. - [**Paywall tự tạo**](capacitor-making-purchases): Bạn tự xây dựng giao diện paywall trong code nhưng vẫn dùng Adapty để lấy sản phẩm và xử lý giao dịch mua. - [**Observer mode**](observer-vs-full-mode): Bạn giữ nguyên hạ tầng mua hàng 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 quickstart](capacitor-quickstart-paywalls). ### Cài đặt và cấu hình SDK \{#install-and-configure-the-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 phụ thuộc vào bước này. **Hướng dẫn:** [Cài đặt & cấu hình Adapty SDK](sdk-installation-capacitor) Gửi cho LLM của bạn: ``` Read these Adapty docs before writing code: - https://adapty.io/docs/vi/sdk-installation-capacitor.md ``` :::tip[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ỗi thường gặp:** "Public API key is missing" → kiểm tra lại xem bạn đã thay placeholder bằng key thật từ App settings chưa. ::: ### Hiển thị paywall và xử lý giao dịch mua \{#show-paywalls-and-handle-purchases\} 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 phụ thuộc vào cách bạn xử lý giao dịch mua. Hãy test từng giao dịch trong sandbox ngay khi triển khai xong — đừng để đến cuối. Xem [Test giao dịch trong sandbox](test-purchases-in-sandbox) để biết hướng dẫn cài đặt. **Hướng dẫn:** - [Kích hoạt giao dịch mua bằng paywall (quickstart)](capacitor-quickstart-paywalls) - [Lấy Paywall Builder paywall và cấu hình của chúng](capacitor-get-pb-paywalls) - [Hiển thị paywall](capacitor-present-paywalls) - [Xử lý sự kiện paywall](capacitor-handling-events) - [Phản hồi hành động nút bấm](capacitor-handle-paywall-actions) Gửi cho LLM của bạ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 ``` :::tip[Checkpoint] - **Kết quả mong đợi:** Paywall hiển thị với các sản phẩm đã 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ỗi thường gặp:** Paywall trống hoặc lỗi `getPaywall` → kiểm tra 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:** - [Kích hoạt giao dịch mua trong paywall tùy chỉnh (quickstart)](capacitor-quickstart-manual) - [Lấy paywall và sản phẩm](fetch-paywalls-and-products-capacitor) - [Hiển thị paywall được thiết kế bằng Remote Config](present-remote-config-paywalls-capacitor) - [Thực hiện giao dịch mua](capacitor-making-purchases) - [Khôi phục giao dịch mua](capacitor-restore-purchase) Gửi cho LLM của bạ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 ``` :::tip[Checkpoint] - **Kết quả mong đợi:** 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. - **Lỗi thường gặp:** Mảng sản phẩm rỗng → kiểm tra paywall đã được gán sản phẩm trong dashboard chưa và placement đã có đối tượng chưa. ::: **Hướng dẫn:** - [Tổng quan về Observer mode](observer-vs-full-mode) - [Triển khai Observer mode](implement-observer-mode-capacitor) - [Báo cáo giao dịch trong Observer mode](report-transactions-observer-mode-capacitor) Gửi cho LLM của bạ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 ``` :::tip[Checkpoint] - **Kết quả mong đợi:** Sau khi thực hiện giao dịch sandbox bằng flow mua hàng hiện có, giao dịch xuất hiện trong **Event Feed** trên Adapty dashboard. - **Lỗi thường gặp:** Không có sự kiện → kiểm tra bạn đã báo cáo giao dịch cho Adapty chưa và server notification đã đượ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ý \{#check-subscription-status\} 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ý](capacitor-check-subscription-status) 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 ``` :::tip[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 \{#identify-users\} Liên kết tài khoản người dùng trong ứng dụng với hồ sơ Adapty để giao dịch mua được duy trì trên nhiều thiết bị. :::important 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](capacitor-quickstart-identify) Gửi cho LLM của bạn: ``` Read these Adapty docs before writing code: - https://adapty.io/docs/vi/capacitor-quickstart-identify.md ``` :::tip[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ỗi thường gặp:** Gọi `identify` sau khi kích hoạt nhưng trước khi lấy paywall để tránh attribution cho hồ sơ ẩn danh. ::: ### Chuẩn bị phát hành \{#prepare-for-release\} Sau khi tích hợp hoạt động trong sandbox, hãy đi 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](release-checklist) Gửi cho LLM của bạn: ``` Read these Adapty docs before releasing: - https://adapty.io/docs/vi/release-checklist.md ``` :::tip[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, server notification, flow 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ỗi thường gặp:** Thiếu server notification → 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**. ::: ## File index tài liệu dạng văn bản thuần \{#plain-text-doc-index-files\} Nếu bạn cần cung cấp cho LLM bối cảnh rộng hơn ngoài các trang riêng lẻ, chúng tôi cung cấp các file index tổng hợp toàn bộ tài liệu Adapty: - [`llms.txt`](https://adapty.io/docs/vi/llms.txt): Liệt kê tất cả các trang với link `.md`. Đây là [tiêu chuẩn đang nổi lên](https://llmstxt.org/) để làm cho website dễ truy cập với LLM. Lưu ý: với một số AI agent (ví dụ: ChatGPT), bạn cần tải `llms.txt` về và tải lên chat dưới dạng file. - [`llms-full.txt`](https://adapty.io/docs/vi/llms-full.txt): Toàn bộ tài liệu Adapty được gộp vào một file. Rất lớn — chỉ dùng khi bạn cần toàn cảnh đầy đủ. - Tập con dành riêng cho Capacitor: [`capacitor-llms.txt`](https://adapty.io/docs/vi/capacitor-llms.txt) và [`capacitor-llms-full.txt`](https://adapty.io/docs/vi/capacitor-llms-full.txt): Tiết kiệm token hơn so với toàn bộ tài liệu.