Skip to main content
The SDK must be initialized before tracking events or accessing cohort data. Initialization is asynchronous and should happen early in your app lifecycle.

​
Basic Initialization

import Permutive_iOS

func initializePermutive() {
    guard let options = Options(
        apiKey: "<your-api-key>",
        organisationId: "<your-organisation-id>",
        workspaceId: "<your-workspace-id>"
    ) else {
        print("Failed to create Permutive options")
        return
    }

    Permutive.shared.start(with: options) { error in
        if let error = error {
            print("Permutive initialization failed: \(error.localizedDescription)")
            return
        }
        print("Permutive SDK ready")
    }
}

​
Configuration Options

The Options class accepts several configuration parameters:

​
Required Parameters

ParameterTypeDescription
apiKeyStringYour Permutive API key
organisationIdStringYour Permutive organisation ID
workspaceIdStringYour Permutive workspace ID

​
Optional Configuration

guard let options = Options(
    apiKey: "<your-api-key>",
    organisationId: "<your-organisation-id>",
    workspaceId: "<your-workspace-id>"
) else { return }

// Enable debug logging
options.logModes = LogMode.all

// Start with options
Permutive.shared.start(with: options) { error in
    // Handle completion
}

​
Log Modes

Control what the SDK logs to the console:
ModeDescription
LogMode.noneNo logging (default for production)
LogMode.allAll messages (recommended for development)
LogMode.infoInformational messages only
LogMode.errorError messages only

​
Where to Initialize

​
UIKit - AppDelegate

import UIKit
import Permutive_iOS

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        initializePermutive()
        return true
    }

    private func initializePermutive() {
        guard let options = Options(
            apiKey: "<your-api-key>",
            organisationId: "<your-organisation-id>",
            workspaceId: "<your-workspace-id>"
        ) else { return }

        Permutive.shared.start(with: options) { error in
            if let error = error {
                print("Permutive error: \(error)")
            }
        }
    }
}

​
SwiftUI - App Struct

import SwiftUI
import Permutive_iOS

@main
struct MyApp: App {
    init() {
        initializePermutive()
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }

    private func initializePermutive() {
        guard let options = Options(
            apiKey: "<your-api-key>",
            organisationId: "<your-organisation-id>",
            workspaceId: "<your-workspace-id>"
        ) else { return }

        Permutive.shared.start(with: options) { error in
            if let error = error {
                print("Permutive error: \(error)")
            }
        }
    }
}
The Permutive SDK assumes consent has been obtained before initialization. If your app requires user consent for tracking, complete your consent flow before calling start(with:).
The SDK does not call Apple’s App Tracking Transparency (ATT) framework. If you need ATT consent: 
import AppTrackingTransparency

func requestConsentThenInitialize() {
    if #available(iOS 14, *) {
        ATTrackingManager.requestTrackingAuthorization { status in
            switch status {
            case .authorized:
                self.initializePermutive()
            case .denied, .restricted:
                // Handle accordingly - you may still initialize
                // Permutive without IDFA tracking
                self.initializePermutive()
            case .notDetermined:
                break
            @unknown default:
                break
            }
        }
    } else {
        initializePermutive()
    }
}
IDFA is not required. Permutive works effectively without IDFA. Consider using identifierForVendor or hashed email addresses instead. See IDFA Provider for details.

​
Initialization with Context

You can provide initial context during initialization: 
let context = Context(
    title: "App Launch",
    url: URL(string: "https://example.com/app"),
    referrer: nil
)

Permutive.shared.start(with: options, context: context) { error in
    // Handle completion
}

​
Checking Initialization Status

The SDK provides properties to check its current state: 
// Get the current user ID (available after initialization)
let userId = Permutive.shared.currentUserId

// Check current cohorts
let cohorts = Permutive.shared.cohorts

​
Error Handling

Handle initialization errors appropriately: 
Permutive.shared.start(with: options) { error in
    if let error = error {
        // Log the error for debugging
        print("Permutive initialization failed: \(error.localizedDescription)")

        // Optionally report to your error tracking service
        // ErrorTracker.report(error)

        // The app can continue without Permutive
        // SDK calls will be no-ops or return empty data
        return
    }

    // SDK is ready - proceed with tracking
    print("Permutive ready, user ID: \(Permutive.shared.currentUserId)")
}

​
tvOS Considerations

tvOS Note: The initialization process is identical on tvOS. The SDK automatically handles platform differences. IDFA and App Tracking Transparency are not available on tvOS.

​
Best Practices

  • Initialize as early as possible in the app lifecycle
  • Handle initialization errors gracefully
  • Complete consent flows before initialization
  • Enable debug logging during development
  • Store credentials securely (consider using a configuration file or build settings)

​
Troubleshooting

Problem: No error, but SDK doesn’t seem to work.Solutions:
  • Enable debug logging: options.logModes = LogMode.all
  • Check credentials are correct
  • Verify network connectivity
Problem: Initialization fails with credential error.Solutions:
  • Verify API key, organization ID, and workspace ID from your dashboard
  • Check for extra whitespace or newlines in credential strings
  • Ensure credentials match the correct environment (staging vs production)
Problem: Events tracked before initialization completes are lost.Solution: Wait for the completion callback before tracking:
Permutive.shared.start(with: options) { error in
    guard error == nil else { return }
    // Now safe to track
    self.startTracking()
}

​
Next Steps

Verification

Verify your integration is working

Page Tracking

Track page views and engagement