Hướng dẫn này mô tả cách tích hợp Adapty vào các paywall tùy chỉnh của bạn. Bạn hoàn toàn kiểm soát việc triển khai paywall, trong khi Adapty SDK tự động lấy sản phẩm, xử lý các giao dịch mua mới và khôi phục các giao dịch trước đó. Hướng dẫn này sử dụng các API của Adapty Kotlin Multiplatform SDK v4 (beta) — nếu bạn đang dùng v3, hãy xem hướng dẫn migration để biết tên các phương thức tương ứng.

Trước khi bắt đầu

Thiết lập sản phẩm

Để kích hoạt in-app purchase, bạn cần nắm rõ ba khái niệm chính:

• Sản phẩm – bất cứ thứ gì người dùng có thể mua (gói đăng ký, consumable, quyền truy cập trọn đời)
• Paywalls – cấu hình xác định những sản phẩm nào sẽ được hiển thị. Trong Adapty, paywall là cách duy nhất để lấy sản phẩm, nhưng thiết kế này cho phép bạn chỉnh sửa sản phẩm, giá cả và ưu đãi mà không cần thay đổi code ứng dụng. Trong SDK v4, các biến thể paywall cho một placement được mang bởi đối tượng flow — bạn lấy một flow và truy vấn các sản phẩm của nó.
• Placements – nơi và thời điểm hiển thị paywall trong ứng dụng của bạn (ví dụ như main, onboarding, settings). Bạn thiết lập paywall cho các placement trong dashboard, sau đó yêu cầu chúng theo placement ID trong code. Điều này giúp bạn dễ dàng chạy A/B test và hiển thị các paywall khác nhau cho các người dùng khác nhau.

Hãy đảm bảo bạn hiểu những khái niệm này ngay cả khi làm việc với paywall tùy chỉnh của mình. Về cơ bản, đây chỉ là cách bạn quản lý các sản phẩm bán trong ứng dụng.

Để triển khai paywall tùy chỉnh, bạn cần tạo một paywall và thêm nó vào một placement. Thiết lập này cho phép bạn lấy danh sách sản phẩm. Để hiểu những gì cần thực hiện trên dashboard, hãy làm theo hướng dẫn quickstart tại đây.

Quản lý người dùng

Bạn có thể làm việc có hoặc không có xác thực backend ở phía mình.

Tuy nhiên, Adapty SDK xử lý người dùng ẩn danh và người dùng đã xác định theo cách khác nhau. Đọc hướng dẫn nhanh về xác định người dùng để hiểu rõ sự khác biệt và đảm bảo bạn đang làm việc với người dùng đúng cách.

Bước 1. Lấy sản phẩm

Để lấy danh sách sản phẩm cho paywall tùy chỉnh, bạn cần:

1. Lấy đối tượng flow bằng cách truyền ID placement vào phương thức getFlow.
2. Lấy mảng sản phẩm cho flow này bằng phương thức getPaywallProducts.

fun loadPaywall() {
    Adapty.getFlow(placementId = "YOUR_PLACEMENT_ID")
        .onSuccess { flow ->
            Adapty.getPaywallProducts(flow = flow)
                .onSuccess { products ->
                    // Use products to build your custom paywall UI
                }
                .onError { error ->
                    // Handle the error
                }
        }
        .onError { error ->
            // Handle the error
        }
}

Bước 2. Xử lý thanh toán

Khi người dùng chọn một sản phẩm trên paywall tùy chỉnh của bạn, hãy gọi phương thức makePurchase với sản phẩm đã chọn. Phương thức này sẽ xử lý flow thanh toán và trả về hồ sơ người dùng đã được cập nhật.

fun purchaseProduct(product: AdaptyPaywallProduct) {
    Adapty.makePurchase(product = product)
        .onSuccess { purchaseResult ->
            when (purchaseResult) {
                is AdaptyPurchaseResult.Success -> {
                    val profile = purchaseResult.profile
                    // Purchase successful, profile updated
                }
                is AdaptyPurchaseResult.UserCanceled -> {
                    // User canceled the purchase
                }
                is AdaptyPurchaseResult.Pending -> {
                    // Purchase is pending (e.g., user will pay offline with cash)
                }
            }
        }
        .onError { error ->
            // Handle the error
        }
}

Bước 3. Khôi phục giao dịch mua

Các cửa hàng ứng dụng yêu cầu tất cả ứng dụng có gói đăng ký phải cung cấp cách để người dùng có thể khôi phục giao dịch mua của họ.

Gọi phương thức restorePurchases khi người dùng nhấn nút khôi phục. Thao tác này sẽ đồng bộ lịch sử giao dịch mua của họ với Adapty và trả về hồ sơ người dùng đã được cập nhật.

fun restorePurchases() {
    Adapty.restorePurchases()
        .onSuccess { profile ->
            // Restore successful, profile updated
        }
        .onError { error ->
            // Handle the error
        }
}

Bước 4. Kiểm tra trạng thái gói đăng ký

Sau khi mua hàng hoặc khôi phục, hãy kiểm tra mức độ truy cập của người dùng để quyết định có hiển thị paywall hay mở khóa các tính năng trả phí. Các phương thức makePurchase và restorePurchases đã trả về hồ sơ người dùng đã cập nhật; khi bạn cần trạng thái hiện tại ở bất kỳ nơi nào khác trong ứng dụng, hãy dùng phương thức getProfile:

fun checkPremiumAccess() {
    Adapty.getProfile()
        .onSuccess { profile ->
            val hasPremiumAccess = profile.accessLevels["premium"]?.isActive == true
            // Grant access to paid features if hasPremiumAccess is true
        }
        .onError { error ->
            // Handle the error
        }
}

Để biết thêm các cách kiểm tra và theo dõi trạng thái gói đăng ký, bao gồm lắng nghe cập nhật theo thời gian thực, xem Kiểm tra trạng thái gói đăng ký.

Các bước tiếp theo

Paywall của bạn đã sẵn sàng để hiển thị trong ứng dụng. Hãy kiểm tra các giao dịch mua trong sandbox App Store hoặc Google Play Store để đảm bảo bạn có thể hoàn thành một giao dịch mua thử từ paywall. Để xem cách hoạt động trong một triển khai thực tế, hãy tham khảo AppViewModel.kt trong ứng dụng mẫu của chúng tôi, minh họa cách xử lý giao dịch mua với error handling và quản lý trạng thái phù hợp.