Xác định người dùng trong iOS 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 — giá trị 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ó qua tham số customerUserId vào phương thức .activate():

// In your AppDelegate class:

let configurationBuilder =
    AdaptyConfiguration
        .builder(withAPIKey: "PUBLIC_SDK_KEY")
        .with(customerUserId: "YOUR_USER_ID")

do {
  try await Adapty.activate(with: configurationBuilder.build())
} catch {
  // handle the error
}

// In your AppDelegate class:

let configurationBuilder =
    AdaptyConfiguration
        .builder(withAPIKey: "PUBLIC_SDK_KEY")
        .with(customerUserId: "YOUR_USER_ID")

Adapty.activate(with: configurationBuilder.build()) { error in
  // 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 để 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 người dùng đã xác thực.

do {
    try await Adapty.identify("YOUR_USER_ID")
} catch {
    // handle the error
}

Adapty.identify("YOUR_USER_ID") { error in
    if let error {
        // handle the error
    }
}

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, máy chủ Adapty đã có thông tin về người dùng đó. Trong những trường hợp 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 dữ liệu 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 cần gửi lại dữ liệu đó cho người dùng đã xác định.

Ngoài ra, cần lưu ý rằng bạn nên yêu cầu lại tất 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():

do {
    try await Adapty.logout()
} catch {
    // handle the error
}

Adapty.logout { error in
    if error == nil {
        // successful logout
    }
}

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

Đặt appAccountToken

appAccountToken là một UUID giúp StoreKit 2 của Apple xác định người dùng qua các lần cài đặt ứng dụng và thiết bị khác nhau.

Từ Adapty iOS SDK 3.10.2 trở đi, bạn có thể truyền appAccountToken khi cấu hình SDK hoặc khi xác định người dùng:

// During configuration:
let configurationBuilder =
    AdaptyConfiguration
        .builder(withAPIKey: "PUBLIC_SDK_KEY")
        .with(customerUserId: "YOUR_USER_ID", withAppAccountToken: UUID())

do {
  try await Adapty.activate(with: configurationBuilder.build())
} catch {
  // handle the error
}

// Or when identifying a user:
do {
    try await Adapty.identify("YOUR_USER_ID", withAppAccountToken: UUID())
} catch {
    // handle the error
}

// During configuration:
let configurationBuilder =
    AdaptyConfiguration
        .builder(withAPIKey: "PUBLIC_SDK_KEY")
        .with(customerUserId: "YOUR_USER_ID", withAppAccountToken: UUID())

Adapty.activate(with: configurationBuilder.build()) { error in
  // handle the error
}

// Or when identifying a user:
Adapty.identify("YOUR_USER_ID", withAppAccountToken: UUID()) { error in
    if let error {
        // handle the error
    }
}

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

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.