Xác định người dùng trong Kotlin Multiplatform SDK

Adapty tạo một ID hồ sơ nội bộ cho mỗi người dùng. Tuy nhiên, nếu bạn có hệ thống xác thực riêng, bạn nên đặt Customer User ID của mình. Bạn có thể tìm người dùng theo Customer User ID trong phần Profiles và sử dụng nó trong server-side API, thông tin này sẽ được gửi đến tất cả các tích hợp.

Đặt customer user ID khi cấu hình

Nếu bạn có user ID trong quá trình cấu hình, chỉ cần truyền nó vào tham số customerUserId của phương thức .activate():


Adapty.activate(
    AdaptyConfig.Builder("PUBLIC_SDK_KEY")
        .withCustomerUserId("YOUR_USER_ID")
        .build()
).onSuccess {
    // successful activation
}.onError { error ->
    // handle the error
    }
}

Muốn xem ví dụ thực tế về cách tích hợp Adapty SDK vào ứng dụng di động? Hãy xem ứng dụng mẫu của chúng tôi, nơi minh họa toàn bộ quá trình thiết lập, bao gồm hiển thị paywall, thực hiện mua hàng và các chức năng cơ bản khác.

Đặt customer user ID sau khi cấu hình

Nếu bạn chưa có user ID khi cấu hình SDK, bạn có thể đặt nó sau bất kỳ lúc nào bằng phương thức .identify(). Trường hợp phổ biến nhất khi sử dụng phương thức này là sau khi đăng ký hoặc đăng nhập, khi người dùng chuyển từ trạng thái ẩn danh sang đã xác thực.


Adapty.identify("YOUR_USER_ID").onSuccess {
    // successful identify
}.onError { error ->
    // handle the error
}

Các tham số yêu cầu:

Customer User ID (bắt buộc): chuỗi định danh người dùng.

Gửi lại dữ liệu người dùng quan trọng

Trong một số trường hợp, chẳng hạn khi người dùng đăng nhập lại vào tài khoản của họ, máy chủ Adapty đã có thông tin về người dùng đó. Trong những tình huống này, Adapty SDK sẽ tự động chuyển sang làm việc với người dùng mới. Nếu bạn đã truyền bất kỳ dữ liệu nào cho người dùng ẩn danh, chẳng hạn như thuộc tính tùy chỉnh hoặc attribution từ các mạng bên thứ ba, bạn nên gửi lại dữ liệu đó cho người dùng đã được xác định.

Ngoài ra, hãy lưu ý rằng bạn nên yêu cầu lại tất cả các paywall và sản phẩm sau khi xác định người dùng, vì dữ liệu của người dùng mới có thể khác.

Đăng xuất và đăng nhập

Bạn có thể đăng xuất người dùng bất kỳ lúc nào bằng cách gọi phương thức .logout():


Adapty.logout().onSuccess {
    // successful logout
}.onError { error ->
    // handle the error
}

Sau đó, bạn có thể đăng nhập người dùng bằng phương thức .identify().

Gán `appAccountToken` (iOS)

iosAppAccountToken là một UUID cho phép bạn liên kết các giao dịch App Store với danh tính người dùng nội bộ của bạn. StoreKit gắn token này với mọi giao dịch, để backend của bạn có thể khớp dữ liệu App Store với người dùng của bạn.

Hãy sử dụng UUID ổn định được tạo cho mỗi người dùng và tái sử dụng nó cho cùng một tài khoản trên nhiều thiết bị. Điều này đảm bảo rằng các giao dịch mua và thông báo App Store được liên kết chính xác.

Bạn có thể đặt token theo hai cách – trong quá trình kích hoạt SDK hoặc khi xác định người dùng.

Bạn phải luôn truyền iosAppAccountToken cùng với customerUserId. Nếu chỉ truyền token, nó sẽ không được đưa vào giao dịch.


// During configuration:
Adapty.activate(
    AdaptyConfig.Builder("PUBLIC_SDK_KEY")
        .withCustomerUserId(
            id = "YOUR_USER_ID",
            iosAppAccountToken = "YOUR_IOS_APP_ACCOUNT_TOKEN"
        )
        .build()
).onSuccess {
    // successful activation
}.onError { error ->
    // handle the error
}

// Or when identifying users
Adapty.identify(
    customerUserId = "YOUR_USER_ID",
    iosAppAccountToken = "YOUR_IOS_APP_ACCOUNT_TOKEN"
).onSuccess {
    // successful identify
}.onError { error ->
    // handle the error
}

Đặt obfuscated account ID (Android)

Google Play yêu cầu obfuscated account ID cho một số trường hợp sử dụng nhất định nhằm tăng cường quyền riêng tư và bảo mật người dùng. Các ID này giúp Google Play xác định giao dịch mua trong khi vẫn giữ thông tin người dùng ở dạng ẩn danh, điều này đặc biệt quan trọng cho việc ngăn chặn gian lận và phân tích.

Bạn có thể cần đặt các ID này nếu ứng dụng của bạn xử lý dữ liệu người dùng nhạy cảm hoặc nếu bạn cần tuân thủ các quy định về quyền riêng tư cụ thể. Các ID ẩn danh cho phép Google Play theo dõi giao dịch mua mà không tiết lộ định danh người dùng thực.

Bạn phải luôn truyền androidObfuscatedAccountId cùng với customerUserId. Nếu chỉ truyền obfuscated account ID, nó sẽ không được đưa vào giao dịch.


// During configuration:
Adapty.activate(
    AdaptyConfig.Builder("PUBLIC_SDK_KEY")
        .withCustomerUserId(
            id = "YOUR_USER_ID",
            androidObfuscatedAccountId = "YOUR_OBFUSCATED_ACCOUNT_ID"
        )
        .build()
).onSuccess {
    // successful activation
}.onError { error ->
    // handle the error
}

// Or when identifying users
Adapty.identify(
    customerUserId = "YOUR_USER_ID",
    androidObfuscatedAccountId = "YOUR_OBFUSCATED_ACCOUNT_ID"
).onSuccess {
    // successful identify
}.onError { error ->
    // handle the error
}

Phát hiện người dùng trên nhiều thiết bị

Khi SDK được kích hoạt, nó tự động đọc các quyền hiện có của người dùng từ StoreKit (iOS) hoặc Google Play Billing (Android) và đồng bộ chúng với backend của Adapty. Một gói đăng ký đang hoạt động sẽ xuất hiện trên hồ sơ người dùng Adapty mà không cần ứng dụng gọi restorePurchases.

Điều không xảy ra tự động là nhận diện rằng một hồ sơ người dùng trên thiết bị mới thuộc về cùng một người dùng như hồ sơ trên thiết bị ban đầu. Adapty khớp các hồ sơ người dùng theo Customer User ID, vì vậy tính liên tục danh tính phụ thuộc vào những gì bạn sử dụng làm CUID.

Những gì Adapty có thể phát hiện trên nhiều thiết bị

Cài đặt của bạn	Adapty phát hiện được gì	Bạn phải làm gì
Customer User ID = `device_id` (không đăng nhập ứng dụng)	Thiết bị mới nhận được CUID khác và do đó có hồ sơ người dùng khác. Gói đăng ký đồng bộ với hồ sơ người dùng mới thông qua sự kiện Access level updated, nhưng `subscription_started` không kích hoạt — hồ sơ người dùng mới được coi là người kế thừa của giao dịch mua ban đầu. Các phân tích dựa trên `subscription_started` sẽ đếm thiếu những người dùng quay lại.	Sử dụng ID tài khoản ổn định làm Customer User ID để người dùng quay lại khớp với hồ sơ người dùng hiện có trên các thiết bị.
Customer User ID = ID tài khoản ổn định (đăng nhập trên mọi thiết bị)	SDK tự động đồng bộ gói đăng ký khi `activate()`, và `identify()` khớp hồ sơ người dùng hiện có theo CUID.	Không cần cài đặt thêm — cả danh tính lẫn gói đăng ký đều được xử lý tự động.
Người kế thừa Apple Family Sharing	Thành viên gia đình nhận gói đăng ký thông qua sự kiện Access level updated — `subscription_started` không kích hoạt.	Lắng nghe sự kiện Access level updated. Xem Apple Family Sharing để biết ma trận sự kiện đầy đủ.
Cùng tài khoản Apple/Google, người dùng khác nhau trong ứng dụng	Hồ sơ người dùng đầu tiên ghi lại giao dịch mua trở thành hồ sơ cha. Các hồ sơ người dùng tiếp theo thấy gói đăng ký thông qua chuỗi kế thừa, với một sự kiện Access level updated.	Yêu cầu đăng nhập, sau đó chọn chế độ chia sẻ phù hợp với mô hình của bạn.

Khôi phục giao dịch mua trên thiết bị mới

Hiển thị nút “Khôi phục giao dịch mua” do người dùng khởi tạo trên paywall của bạn. Apple App Review (hướng dẫn 3.1.1) yêu cầu có nút này, và nó đóng vai trò dự phòng khi quá trình đồng bộ tự động bỏ sót một trường hợp đặc biệt. Nút này nên gọi restorePurchases trên SDK của bạn.

Không cần gọi restorePurchases theo chương trình khi khởi chạy lần đầu trong điều kiện sử dụng bình thường — SDK đã thực hiện tương đương khi activate(). Chỉ dùng các lệnh gọi theo chương trình để buộc kiểm tra biên lai mới, ví dụ khi debug trường hợp mất quyền truy cập sau khi activate() đã hoàn thành.

Xác định người dùng trong Kotlin Multiplatform SDK

Đặt customer user ID khi cấu hình

Đặt customer user ID sau khi cấu hình

Đăng xuất và đăng nhập

Gán appAccountToken (iOS)

Đặt obfuscated account ID (Android)

Phát hiện người dùng trên nhiều thiết bị

Gán `appAccountToken` (iOS)