Cài đặt & cấu hình iOS SDK

Adapty SDK bao gồm hai module chính để tích hợp liền mạch vào ứng dụng di động của bạn:

• Core Adapty: SDK thiết yếu này bắt buộc phải có để Adapty hoạt động đúng trong ứng dụng của bạn.
• AdaptyUI: Module tùy chọn này cần thiết nếu bạn sử dụng Adapty Paywall Builder, công cụ no-code thân thiện với người dùng để dễ dàng tạo paywall đa nền tảng.

Để xem hướng dẫn triển khai đầy đủ, bạn cũng có thể xem các video sau:

Yêu cầu

Adapty iOS SDK yêu cầu iOS 15.0 trở lên.

Cài đặt Adapty SDK

Adapty SDK được cài đặt qua Swift Package Manager. Trong Xcode, vào File -> Add Package Dependency…. Lưu ý rằng các bước thêm package dependency có thể khác nhau tùy phiên bản Xcode, vì vậy hãy tham khảo tài liệu của Xcode nếu cần.

1. Nhập URL repository:

   https://github.com/adaptyteam/AdaptySDK-iOS.git

2. Chọn phiên bản (khuyến nghị dùng phiên bản ổn định mới nhất) rồi nhấn Add Package.
3. Trong cửa sổ Choose Package Products, chọn các module bạn cần:
   • Adapty (module cốt lõi)
   • AdaptyUI (tùy chọn - chỉ cần thiết nếu bạn dùng Paywall Builder)
   Lưu ý:

   • Để bật Kids Mode trong SDK 3.x, hãy chọn Adapty_KidsMode thay vì Adapty. Từ SDK 4.0 trở đi, chọn các module thông thường — Kids Mode được bật thông qua package trait KidsMode.
   • Đừng chọn bất kỳ package nào khác trong danh sách — bạn sẽ không cần đến chúng.
4. Nhấn Add Package để hoàn tất cài đặt.
5. Kiểm tra cài đặt: Trong project navigator, bạn sẽ thấy “Adapty” (và “AdaptyUI” nếu đã chọn) xuất hiện dưới Package Dependencies.

Kích hoạt module Adapty trong Adapty SDK

Kích hoạt Adapty SDK trong code của ứng dụng.

Để lấy Public SDK Key:

1. Truy cập Adapty Dashboard và điều hướng đến App settings → General.
2. Trong phần Api keys, sao chép Public SDK Key (KHÔNG phải Secret Key).
3. Thay thế "YOUR_PUBLIC_SDK_KEY" trong code.

Hoặc lấy theo cách lập trình, sử dụng Adapty CLI:

npm install -g adapty
adapty auth login
adapty apps list

Hoặc, trực tiếp:

npx adapty auth login
adapty apps list

• Đảm bảo bạn sử dụng Public SDK key để khởi tạo Adapty, Secret key chỉ nên dùng cho server-side API.
• SDK keys là duy nhất cho mỗi ứng dụng, vì vậy nếu bạn có nhiều ứng dụng, hãy đảm bảo chọn đúng key.

@main
struct YourApp: App {
  init() {
    // Configure Adapty SDK
    let configurationBuilder = AdaptyConfiguration
      .builder(withAPIKey: "YOUR_PUBLIC_SDK_KEY") // Get from Adapty dashboard

   Adapty.logLevel = .verbose // recommended for development and the first production release

    let config = configurationBuilder.build()

    // Activate Adapty SDK asynchronously
    Task {
      do {
        try await Adapty.activate(with: config)
      } catch {
        // Handle error appropriately for your app
        print("Adapty activation failed: ", error)
      }
    }

    var body: some Scene {
      WindowGroup {
        // Your content view
      }
    }
  }
}

// In your AppDelegate class:
// If you only use an AppDelegate, place the following code in the
// application(_:didFinishLaunchingWithOptions:) method.

// If you use a SceneDelegate, place the following code in the
// scene(_:willConnectTo:options:) method.


Task {
  do {
    let configurationBuilder = AdaptyConfiguration
      .builder(withAPIKey: "YOUR_PUBLIC_SDK_KEY") // Get from Adapty dashboard
      .with(logLevel: .verbose) // recommended for development and the first production release

    let config = configurationBuilder.build()
    try await Adapty.activate(with: config)
  } catch {
    // Handle error appropriately for your app
    print("Adapty activation failed: ", error)
  }
}

Tiếp theo, hãy thiết lập paywall trong ứng dụng của bạn:

• Nếu bạn dùng Adapty Paywall Builder, trước tiên hãy kích hoạt module AdaptyUI bên dưới, sau đó làm theo hướng dẫn nhanh về Paywall Builder.
• Nếu bạn tự xây dựng giao diện paywall, xem hướng dẫn nhanh cho paywall tùy chỉnh.

Kích hoạt module AdaptyUI của Adapty SDK

Nếu bạn dự định sử dụng Paywall Builder và đã cài đặt module AdaptyUI, bạn cũng cần kích hoạt AdaptyUI.

@main
struct YourApp: App {
  init() {
    // ...ConfigurationBuilder steps

    // Activate Adapty SDK asynchronously
    Task {
      do {
        try await Adapty.activate(with: config)
        try await AdaptyUI.activate()
      } catch {
        // Handle error appropriately for your app
        print("Adapty activation failed: ", error)
      }
    }

    // main body...
  }
}

// If you only use an AppDelegate, place the following code in the
// application(_:didFinishLaunchingWithOptions:) method.

// If you use a SceneDelegate, place the following code in the
// scene(_:willConnectTo:options:) method.


Task {
   do {
      let configurationBuilder = AdaptyConfiguration
         .builder(withAPIKey: "YOUR_PUBLIC_SDK_KEY") // Get from Adapty dashboard
         .with(logLevel: .verbose) // recommended for development

   let config = configurationBuilder.build()
   try await Adapty.activate(with: config)
   try await AdaptyUI.activate()
      } catch {
      // Handle error appropriately for your app
      print("Adapty activation failed: ", error)
   }
}

Cài đặt tùy chọn

Ghi log

Thiết lập hệ thống ghi log

Adapty ghi lại các lỗi và thông tin quan trọng khác để giúp bạn hiểu chuyện gì đang xảy ra. Các cấp độ log có sẵn như sau:

 let configurationBuilder = AdaptyConfiguration
         .builder(withAPIKey: "YOUR_PUBLIC_SDK_KEY")
         .with(logLevel: .verbose) // recommended for development

Chuyển hướng thông báo từ hệ thống logging

Nếu bạn cần gửi thông báo log của Adapty đến hệ thống của mình hoặc lưu chúng vào file, hãy sử dụng phương thức setLogHandler và triển khai logic logging tùy chỉnh bên trong đó. Handler này nhận các bản ghi log chứa nội dung thông báo và mức độ nghiêm trọng.

Adapty.setLogHandler { record in
    writeToLocalFile("Adapty \(record.level): \(record.message)")
}

Chính sách dữ liệu

Adapty không lưu trữ dữ liệu cá nhân của người dùng trừ khi bạn chủ động gửi lên, nhưng bạn có thể triển khai thêm các chính sách bảo mật dữ liệu để tuân thủ quy định của cửa hàng hoặc từng quốc gia.

Tắt thu thập và chia sẻ IDFA

Khi kích hoạt module Adapty, đặt idfaCollectionDisabled thành true để tắt việc thu thập và chia sẻ IDFA. Sử dụng tham số này để tuân thủ Nguyên tắc Đánh giá App Store hoặc tránh kích hoạt lời nhắc App Tracking Transparency khi IDFA không cần thiết cho ứng dụng của bạn. Giá trị mặc định là false. Để biết thêm chi tiết về việc thu thập IDFA, hãy tham khảo phần Tích hợp Analytics.

let configurationBuilder =
    AdaptyConfiguration
        .builder(withAPIKey: "YOUR_PUBLIC_SDK_KEY")
        .with(idfaCollectionDisabled: true)

Tắt tính năng thu thập và chia sẻ địa chỉ IP

Khi kích hoạt module Adapty, đặt ipAddressCollectionDisabled thành true để tắt việc thu thập và chia sẻ địa chỉ IP của người dùng. Giá trị mặc định là false.

Dùng tham số này để tăng cường quyền riêng tư cho người dùng, tuân thủ các quy định bảo vệ dữ liệu theo khu vực (như GDPR hoặc CCPA), hoặc giảm bớt việc thu thập dữ liệu không cần thiết khi các tính năng dựa trên IP không cần thiết cho ứng dụng của bạn.

let configurationBuilder =
    AdaptyConfiguration
        .builder(withAPIKey: "YOUR_PUBLIC_SDK_KEY")
        .with(ipAddressCollectionDisabled: true)

Cấu hình cache media cho paywall trong AdaptyUI

Lưu ý rằng cấu hình AdaptyUI là tùy chọn. Bạn có thể kích hoạt module AdaptyUI mà không cần config. Tuy nhiên, nếu bạn sử dụng config, tất cả các tham số đều bắt buộc.

// Configure AdaptyUI
        let adaptyUIConfiguration = AdaptyUI.Configuration(
            mediaCacheConfiguration: .init(
                memoryStorageTotalCostLimit: 100 * 1024 * 1024,
                memoryStorageCountLimit: .max,
                diskStorageSizeLimit: 100 * 1024 * 1024
            )
        )

        // Activate AdaptyUI
        AdaptyUI.activate(configuration: adaptyUIConfiguration)

Tham số:

Hành vi hoàn tất giao dịch

Theo mặc định, Adapty tự động hoàn tất giao dịch sau khi xác thực thành công. Tuy nhiên, nếu bạn cần xác thực giao dịch nâng cao (chẳng hạn như xác thực receipt phía server, phát hiện gian lận, hoặc logic nghiệp vụ tùy chỉnh), bạn có thể cấu hình SDK để sử dụng chế độ hoàn tất giao dịch thủ công.

let configurationBuilder = AdaptyConfiguration
    .builder(withAPIKey: "YOUR_PUBLIC_SDK_KEY")
    .with(transactionsFinishBehavior: .manual) // .auto là mặc định

Xem thêm chi tiết về cách hoàn tất giao dịch trong hướng dẫn.

Xóa dữ liệu khi khôi phục từ backup

Khi clearDataOnBackup được đặt thành true, SDK sẽ phát hiện khi ứng dụng được khôi phục từ bản backup iCloud và xóa toàn bộ dữ liệu SDK được lưu trữ cục bộ, bao gồm thông tin hồ sơ người dùng đã cache, chi tiết sản phẩm và paywall. Sau đó SDK sẽ khởi tạo lại với trạng thái sạch. Giá trị mặc định là false.

let configurationBuilder = AdaptyConfiguration
    .builder(withAPIKey: "YOUR_PUBLIC_SDK_KEY")
    .with(clearDataOnBackup: true) // default – false

Khắc phục sự cố

Lỗi concurrency Swift 6 với Tuist

Khi build với Tuist, bạn có thể gặp lỗi biên dịch strict concurrency của Swift 6. Biểu hiện điển hình là lỗi không khớp thuộc tính @Sendable trong AdaptyUIBuilderLogic hoặc các lỗi Sendability tương tự giữa các module. Điều này xảy ra vì Tuist tạo ra các dự án Xcode từ các gói SPM nhưng không giữ nguyên cài đặt swift-tools-version: 6.0. Kết quả là, một số target của Adapty (Adapty, AdaptyUI, AdaptyUIBuilder) được biên dịch theo quy tắc Swift 5 trong khi các target khác dùng Swift 6, dẫn đến sự không khớp @Sendable giữa các module.

Cách khắc phục: Nâng cấp lên Adapty SDK 3.15.5 trở lên, phiên bản này giải quyết vấn đề bất kể sự pha trộn giữa các phiên bản ngôn ngữ Swift.

Giải pháp tạm thời: Nếu bạn chưa thể nâng cấp, hãy đặt Swift 6 một cách tường minh cho cả ba target của Adapty trong cấu hình Tuist của bạn:

targetSettings: [
  "Adapty": .init().swiftVersion("6"),
  "AdaptyUI": .init().swiftVersion("6"),
  "AdaptyUIBuilder": .init().swiftVersion("6"),
]