> ## 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.

# Quick Start

> Get up and running with the Permutive iOS SDK in minutes

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

<Tabs>
  <Tab title="Swift Package Manager">
    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**
  </Tab>

  <Tab title="CocoaPods">
    Add to your `Podfile`:

    ```ruby theme={"dark"}
    target 'YourApp' do
      platform :ios, '12.0'
      pod 'Permutive_iOS', '~> 2.2.0'
    end
    ```

    Then run:

    ```bash theme={"dark"}
    pod install
    ```
  </Tab>
</Tabs>

## Step 2: Initialize the SDK

Initialize Permutive early in your app lifecycle, typically in your `AppDelegate` or `SceneDelegate`.

<CodeGroup>
  ```swift Swift theme={"dark"}
  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")
          }
      }
  }
  ```

  ```objectivec Objective-C theme={"dark"}
  #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
  ```
</CodeGroup>

## Step 3: Track Your First Page View

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

<CodeGroup>
  ```swift Swift theme={"dark"}
  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
      }
  }
  ```

  ```objectivec Objective-C theme={"dark"}
  #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
  ```
</CodeGroup>

## Step 4: Verify the Integration

Enable debug logging to confirm events are being sent:

<CodeGroup>
  ```swift Swift theme={"dark"}
  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
      // ...
  }
  ```

  ```objectivec Objective-C theme={"dark"}
  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) {
      // ...
  }];
  ```
</CodeGroup>

Run your app and check the Xcode console for:

```
Permutive: [info] SDK ready
Permutive: [info] Accepted: 1 / 1
```

<Tip>
  The "Accepted: 1 / 1" message confirms your event was successfully sent to Permutive servers.
</Tip>

## Next Steps

<CardGroup cols={2}>
  <Card title="Installation Details" icon="download" href="/sdks/mobile/ios/getting-started/installation">
    CocoaPods and SPM configuration options
  </Card>

  <Card title="Initialization Options" icon="gear" href="/sdks/mobile/ios/getting-started/initialization">
    Advanced SDK configuration
  </Card>

  <Card title="Page Tracking" icon="file" href="/sdks/mobile/ios/features/page-tracking">
    Complete PageTracker guide
  </Card>

  <Card title="Identity Management" icon="user" href="/sdks/mobile/ios/core-concepts/identity-management">
    Track users across sessions
  </Card>
</CardGroup>