Quick Start

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

Swift Package Manager
CocoaPods

In Xcode, go to File → Add Package Dependencies

Enter the package URL:

https://github.com/permutive-engineering/permutive-ios-spm

Select Permutive_iOS as the package product
Click Add Package

Add to your Podfile:

target 'YourApp' do
  platform :ios, '12.0'
  pod 'Permutive_iOS', '~> 2.2.0'
end

Then run:

pod install

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")
        }
    }
}

#import "AppDelegate.h"
@import Permutive_iOS;

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [self initializePermutive];
    return YES;
}

- (void)initializePermutive {
    PermutiveOptions *options = [[PermutiveOptions alloc]
        initWithApiKey:@"<your-api-key>"
        organisationId:@"<your-organisation-id>"
        workspaceId:@"<your-workspace-id>"];

    if (options == nil) {
        NSLog(@"Failed to create Permutive options");
        return;
    }

    [[Permutive shared] startWith:options
                          context:nil
                       completion:^(NSError *error) {
        if (error != nil) {
            NSLog(@"Permutive initialization failed: %@", error.localizedDescription);
            return;
        }
        NSLog(@"Permutive SDK ready");
    }];
}

@end

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

#import "ArticleViewController.h"
@import Permutive_iOS;

@interface ArticleViewController ()
@property (nonatomic, strong) NSObject<PermutivePageTrackerProtocol> *pageTracker;
@end

@implementation ArticleViewController

- (void)viewDidLoad {
    [super viewDidLoad];

    // Create event properties
    NSError *error = nil;
    PermutiveEventProperties *properties = [[PermutiveEventProperties alloc]
        init:@{@"category": @"news", @"author": @"Jane Smith"}
        error:&error];

    // Create page context
    PermutiveContext *context = [[PermutiveContext alloc]
        initWithTitle:@"Breaking News: Tech Advances"
        url:[NSURL URLWithString:@"https://example.com/articles/tech-advances"]
        referrer:nil];

    // Create the page tracker
    self.pageTracker = [[Permutive shared]
        createPageTrackerWithProperties:properties
        context:context
        error:&error];
}

- (void)viewDidAppear:(BOOL)animated {
    [super viewDidAppear:animated];
    [self.pageTracker resumeAndReturnError:nil];  // Starts tracking
}

- (void)viewDidDisappear:(BOOL)animated {
    [super viewDidDisappear:animated];
    [self.pageTracker pause];  // Pauses engagement timer
}

- (void)dealloc {
    [self.pageTracker stop];  // Stops tracking
}

@end

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
    // ...
}

PermutiveOptions *options = [[PermutiveOptions alloc]
    initWithApiKey:@"<your-api-key>"
    organisationId:@"<your-organisation-id>"
    workspaceId:@"<your-workspace-id>"];

options.logModes = PermutiveLogModeAll;

[[Permutive shared] startWith:options context:nil completion:^(NSError *error) {
    // ...
}];

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

Get Started

Products

Deployment

Governance

Prerequisites

Step 1: Install the SDK

Step 2: Initialize the SDK

Step 3: Track Your First Page View

Step 4: Verify the Integration

Next Steps

Installation Details

Initialization Options

Page Tracking

Identity Management

​Prerequisites

​Step 1: Install the SDK

​Step 2: Initialize the SDK

​Step 3: Track Your First Page View

​Step 4: Verify the Integration

​Next Steps

Installation Details

Initialization Options

Page Tracking

Identity Management

Prerequisites

Step 1: Install the SDK

Step 2: Initialize the SDK

Step 3: Track Your First Page View

Step 4: Verify the Integration

Next Steps