Sử dụng Adapty flow với hệ thống thanh toán của bạn

Bạn không cần chuyển hệ thống thanh toán sang Adapty để sử dụng flow. Trong chế độ Observer, code của bạn vẫn xử lý toàn bộ giao dịch mua, trong khi Adapty hiển thị paywall hoặc onboarding, quyết định ai được xem, A/B test và báo cáo kết quả.

Hướng dẫn này trình bày những gì thay đổi, những gì không thay đổi, và các bước thiết lập cần thực hiện.

Tip

Bạn mới làm quen với flow? Flow & Paywall Builder sẽ giới thiệu những gì bạn có thể xây dựng trước khi kết nối bất kỳ thứ gì.

Những gì bạn giữ lại, những gì Adapty đảm nhận

Code của bạn vẫn xử lý:

  • Lệnh gọi mua hàng
  • Hoàn tất và xác nhận giao dịch
  • Cấp và thu hồi quyền truy cập
  • Gia hạn và thử lại thanh toán

Adapty đảm nhận:

Không có gì thay đổi trong quy trình thanh toán của bạn. Adapty hiển thị flow và chuyển thao tác mua hàng về code của bạn để thực hiện giao dịch.

Tạo sản phẩm trong Adapty

Bỏ qua phần này nếu flow của bạn không hiển thị giá hay thực hiện giao dịch mua nào — một flow chỉ gồm các màn hình onboarding thì không cần sản phẩm trong Adapty.

Ngay khi một màn hình hiển thị sản phẩm, hãy tạo một sản phẩm trong Adapty cho mỗi gói đăng ký hoặc sản phẩm mua một lần mà màn hình đó cung cấp. Flow đọc giá hiển thị trên thẻ từ sản phẩm, do đó thẻ luôn hiển thị giá hiện tại từ cửa hàng, bạn có thể A/B test mức giá đó, và Adapty sẽ phân nhóm doanh thu theo sản phẩm trong phần analytics.

Một sản phẩm trong Adapty trỏ đến sản phẩm trong cửa hàng mà bạn đã bán, vì vậy việc tạo sản phẩm không ảnh hưởng đến thanh toán: code của bạn vẫn xử lý mọi giao dịch. Mỗi sản phẩm cần gắn với một mức độ truy cập, và trong Observer mode Adapty không tự cấp quyền — code của bạn vẫn quản lý quyền truy cập — nhưng sản phẩm vẫn cần có một mức độ truy cập.

Adapty CLI cho phép tạo sản phẩm mà không cần mở dashboard. Cài đặt (yêu cầu Node.js 18 trở lên) và đăng nhập:

npm install -g adapty
adapty auth login

Lấy app ID, sau đó xem mức độ truy cập cần gắn — mỗi app mới đều có sẵn mức premium:

adapty apps list
adapty access-levels list --app <app-id>

Sau đó tạo một sản phẩm Adapty cho mỗi sản phẩm bạn bán trên cửa hàng, sử dụng ID sản phẩm từ App Store Connect và Google Play Console:

adapty products create --app <app-id> --title "Monthly" --access-level-id <access-level-id> --period monthly --ios-product-id com.example.monthly --android-product-id com.example.monthly --android-base-plan-id monthly

Truyền --period lifetime cho sản phẩm mua một lần, và --stripe-product-id cùng --stripe-price-id (hoặc cặp Paddle tương ứng) cho sản phẩm bán trên web. products create liệt kê đầy đủ các flag. ID sản phẩm của cửa hàng không thể thay đổi sau khi tạo, vì vậy nếu muốn gắn một sản phẩm với ID cửa hàng khác, bạn cần tạo một sản phẩm mới.

Warning

Một phần tử sản phẩm chưa được gán sẽ chặn việc lưu và xuất bản, vì vậy bạn sẽ phát hiện ra ngay trong builder. Một hành động Purchase chưa được gán sản phẩm thì vẫn lưu được nhưng sẽ không hoạt động trên thiết bị — nút đó sẽ không làm gì cả. Hãy gán sản phẩm cho mọi hành động Purchase.

Hoặc bỏ qua sản phẩm và viết giá dưới dạng văn bản tĩnh

Một flow không có phần tử sản phẩm vẫn lưu và xuất bản được, vì vậy bạn có thể gõ giá trực tiếp vào văn bản và để code của bạn quyết định nút nhấn sẽ mua gì. Điều này đánh đổi:

  • Bạn phải cập nhật giá ở hai nơi — cửa hàng và văn bản trong flow — và chúng sẽ lệch nhau ngay khi bạn thay đổi một trong hai.
  • Không có A/B test giá, trong khi đó lại là mục đích chính của flow.
  • Biểu đồ và các tích hợp nhóm doanh thu kém gọn hơn, vì Adapty chỉ biết sản phẩm từ giao dịch bạn báo cáo.
  • Code của bạn ánh xạ từng phần tử được nhấn vào một sản phẩm, thay vì nhận sản phẩm từ flow.

Thiết lập

  1. Kích hoạt SDK ở chế độ Observer. Bật observerMode khi cấu hình SDK: iOS, Android, React Native, Flutter, Unity, Kotlin Multiplatform, Capacitor.
  2. Tạo sản phẩm của bạn trong Adapty, trừ khi không có màn hình nào trong flow hiển thị giá. Mỗi sản phẩm tương ứng một lệnh CLI — xem Tạo sản phẩm của bạn trong Adapty.
  3. Xây dựng flow. Xem Flow & Paywall Builder để thiết kế màn hình, thiết lập giao dịch mua cho sản phẩm trên màn hình paywall, và tạo placement để quyết định flow xuất hiện ở đâu trong ứng dụng của bạn.
  4. Hiển thị flow và thực hiện giao dịch mua trong code của bạn. Adapty chuyển thao tác nhấn mua hàng đến một handler mà bạn đăng ký.
  5. Báo cáo giao dịch kèm theo paywall variation ID của sản phẩm đã mua, để giao dịch mua được ghi nhận vào analytics với attribution từ paywall đã bán sản phẩm đó.

Bước 4 và 5 khác nhau tùy theo nền tảng. Trong mọi đoạn code, flow là AdaptyFlow bạn đã lấy cho placement, product là AdaptyPaywallProduct mà người dùng đã nhấn, và myPurchaseApi hoặc yourBillingClient đại diện cho code mua hàng bạn đã có sẵn.

Giới hạn của Observer mode

  • Adapty không cấp quyền truy cập: Adapty không phản hồi các sự kiện mua hàng bằng cách cấp hoặc thu hồi quyền truy cập trả phí, không xử lý việc gia hạn hay thử lại thanh toán. Code của bạn mới là bên quản lý mức độ truy cập.
  • Code của bạn tự hoàn tất giao dịch: Adapty không hoàn tất hoặc xác nhận các giao dịch mà code của bạn thực hiện, vì vậy việc đóng từng giao dịch vẫn thuộc trách nhiệm của bạn.
  • Báo cáo là bắt buộc: variationId bạn truyền vào khi báo cáo là mối liên kết duy nhất giữa một giao dịch và flow đã tạo ra nó. Hãy báo cáo mọi giao dịch, nếu không các chỉ số flow và kết quả A/B test của bạn sẽ bị sai.

Nếu bạn đang dùng một nhà cung cấp khác

Observer mode chỉ yêu cầu code của bạn thực hiện giao dịch mua — không quan trọng SDK của ai được gọi. Flow hoạt động tương tự dù bạn đang dùng RevenueCat, Superwall, Qonversion hay code StoreKit/Billing Library của chính bạn.

Có ba quyết định cần đưa ra trước khi triển khai:

  • Một hệ thống hoàn tất mỗi giao dịch: Hai SDK cùng hoàn tất một giao dịch là lỗi phổ biến nhất ở đây.
  • Một hệ thống quản lý quyền truy cập: Adapty không cấp quyền gì trong chế độ Observer, vì vậy hãy giữ nguyên mức độ truy cập như cũ.
  • Báo cáo mỗi giao dịch một lần: Báo cáo cùng một giao dịch từ hai nơi sẽ làm sai lệch dữ liệu analytics của bạn.

Để chuyển hoàn toàn khỏi nhà cung cấp khác, hãy xem Migrate từ RevenueCat hoặc Migrate từ Superwall.

Để Adapty thực hiện giao dịch mua thay thế

Tip

Ứng dụng của bạn thực hiện giao dịch mua thông qua Adapty ở đây, vì vậy phần code là một tích hợp Adapty bình thường. Làm theo hướng dẫn bắt đầu nhanh hoặc Migrate từ RevenueCat, hoặc giao cho SDK integration skill.

Observer mode là cách nhanh nhất để bắt đầu. Nếu bạn muốn giữ lại analytics của RevenueCat nhưng tránh các giới hạn của Observer mode, hãy đảo ngược hai cái lại: Adapty chạy ở chế độ đầy đủ và xử lý toàn bộ giao dịch mua, trong khi RevenueCat chạy ở observer mode của chính nó và ghi lại các giao dịch mua mà Adapty thực hiện.

Adapty khi đó sẽ biết flow, placement và biến thể A/B test nào tạo ra mỗi khoản thanh toán, đồng thời cấp mức độ truy cập và xử lý gia hạn, thử lại thanh toán và hoàn tiền.

Ở phía RevenueCat, hãy đặt purchasesAreCompletedBy thành app của bạn khi cấu hình SDK — .myApp trên iOS, MY_APP trên Android. Tài liệu Using the SDK with your own IAP code của RevenueCat có hướng dẫn cấu hình cho từng nền tảng, phiên bản StoreKit mà iOS yêu cầu, và lệnh syncPurchases() để đồng bộ các giao dịch mua mà người dùng đã thực hiện trước đó. Hãy đặt cùng một user ID cho cả hai SDK — customer user ID của Adapty và appUserID của RevenueCat — nếu không, hai dashboard sẽ hiển thị dữ liệu của những người dùng khác nhau.

Warning

Việc này sẽ kết thúc vai trò của các entitlement RevenueCat với tư cách là nguồn dữ liệu chính xác, và mức độ truy cập của Adapty sẽ đảm nhận vai trò đó. RevenueCat vẫn tiếp tục theo dõi và dashboard của nó vẫn tiếp tục báo cáo, nhưng từ đây nó chỉ nhận thông tin về mỗi lần mua hàng một cách gián tiếp và trong phạm vi giới hạn mà tài liệu của chính nó đã nêu. Bất kỳ thành phần nào hiện đang đọc entitlement RevenueCat — ứng dụng của bạn, backend, bản build web hay desktop — đều cần chuyển sang dùng Adapty hoặc đọc từ một bản sao. Hãy giải quyết điều đó trước khi phát hành. Mọi thứ khác không thay đổi: tài khoản RevenueCat, lịch sử và các tích hợp của nó vẫn giữ nguyên.