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

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

• Core Adapty: Module SDK cốt lõi, bắt buộc phải có để Adapty hoạt động đúng trong ứng dụng.
• AdaptyUI: Module tùy chọn, cần thiết nếu bạn sử dụng Adapty Paywall Builder — công cụ no-code thân thiện giúp tạo paywall đa nền tảng dễ dà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 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ị chọn phiên bản ổn định mới nhất) và 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ỉ khi bạn dự định sử dụng Paywall Builder)
   Lưu ý:

   • Để bật chế độ Kids, hãy chọn Adapty_KidsMode thay vì Adapty.
   • Không chọn các package khác trong danh sách – bạn sẽ không cầ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) dưới mục Package Dependencies.

Kích hoạt module Adapty của 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:

• 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 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 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

Logging

Thiết lập hệ thống logging

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

 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 log của Adapty đến hệ thống của mình hoặc lưu vào file, hãy 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à cấp độ 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, nhưng bạn có thể áp dụng thêm các chính sách bảo mật dữ liệu để tuân thủ hướng dẫn của cửa hàng hoặc quy định của 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 thu thập và chia sẻ IDFA.

Dùng tham số này để tuân thủ App Store Review Guidelines 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ề thu thập IDFA, tham khảo phần Tích hợp Analytics.

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

Tắt thu thập và chia sẻ địa chỉ IP

Khi kích hoạt module Adapty, đặt ipAddressCollectionDisabled thành true để tắt 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ư của 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 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 bắt buộc trong ứng dụng của bạn.

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

Cấu hình media cache 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 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

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 (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 để hoàn tất giao dịch thủ công.

let configurationBuilder = AdaptyConfiguration
    .builder(withAPIKey: "YOUR_PUBLIC_SDK_KEY")
    .with(transactionsFinishBehavior: .manual) // .auto is the default

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ừ 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 được 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

Xử lý sự cố

Lỗi Swift 6 concurrency với Tuist

Khi build với Tuist, bạn có thể gặp lỗi biên dịch Swift 6 strict concurrency. Triệu chứng điển hình bao gồm lỗi không khớp thuộc tính @Sendable trong AdaptyUIBuilderLogic hoặc các lỗi Sendability cross-module tương tự.

Nguyên nhân là Tuist tạo project Xcode từ các SPM package nhưng không giữ lại cài đặt swift-tools-version: 6.0. Kết quả là một số target Adapty (Adapty, AdaptyUI, AdaptyUIBuilder) biên dịch với quy tắc Swift 5 trong khi các target khác dùng Swift 6, tạo ra lỗi @Sendable cross-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ể phiên bản ngôn ngữ Swift hỗn hợp.

Cách tạm thời: Nếu bạn không thể nâng cấp, hãy đặt rõ Swift 6 cho cả ba target Adapty trong cấu hình Tuist:

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