Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.permutive.com/llms.txt

Use this file to discover all available pages before exploring further.

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