Skip to main content
This guide walks you through installing the SDK, initializing it, and tracking your first page view.

​
Prerequisites

  • Xcode 13.0 or later
  • iOS 12.0+ or tvOS 12.0+ deployment target
  • Your Permutive API Key, Organization ID, and Workspace ID (from your dashboard)

​
Step 1: Install the SDK

  1. In Xcode, go to File → Add Package Dependencies
  2. Enter the package URL: 
    https://github.com/permutive-engineering/permutive-ios-spm
  3. Select Permutive_iOS as the package product
  4. Click Add Package

​
Step 2: Initialize the SDK

Initialize Permutive early in your app lifecycle, typically in your AppDelegate or SceneDelegate. 
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 {
            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")
        }
    }
}

​
Step 3: Track Your First Page View

Use PageTracker to track page views. This is the recommended approach for most tracking scenarios. 
import UIKit
import Permutive_iOS

class ArticleViewController: UIViewController {
    private var pageTracker: PageTrackerProtocol?

    override func viewDidLoad() {
        super.viewDidLoad()

        // Create event properties
        let properties = try? EventProperties([
            "category": "news",
            "author": "Jane Smith"
        ])

        // Create page context
        let context = Context(
            title: "Breaking News: Tech Advances",
            url: URL(string: "https://example.com/articles/tech-advances"),
            referrer: nil
        )

        // Create the page tracker
        pageTracker = try? Permutive.shared.createPageTracker(
            properties: properties,
            context: context
        )
    }

    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        try? pageTracker?.resume()  // Starts tracking, fires Pageview event
    }

    override func viewDidDisappear(_ animated: Bool) {
        super.viewDidDisappear(animated)
        pageTracker?.pause()  // Pauses engagement timer
    }

    deinit {
        pageTracker?.stop()  // Stops tracking, fires PageViewComplete event
    }
}

​
Step 4: Verify the Integration

Enable debug logging to confirm events are being sent: 
guard let options = Options(
    apiKey: "<your-api-key>",
    organisationId: "<your-organisation-id>",
    workspaceId: "<your-workspace-id>"
) else { return }

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

Permutive.shared.start(with: options) { error in
    // ...
}
Run your app and check the Xcode console for: 
Permutive: [info] SDK ready
Permutive: [info] Accepted: 1 / 1
The “Accepted: 1 / 1” message confirms your event was successfully sent to Permutive servers.

​
Next Steps

Installation Details

CocoaPods and SPM configuration options

Initialization Options

Advanced SDK configuration

Page Tracking

Complete PageTracker guide

Identity Management

Track users across sessions