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

# Installation

> Add the Permutive SDK to your iOS or tvOS project

The Permutive iOS SDK can be installed via Swift Package Manager or CocoaPods.

## Requirements

| Requirement | Version                     |
| ----------- | --------------------------- |
| iOS         | 12.0+                       |
| tvOS        | 12.0+                       |
| Xcode       | 13.0+                       |
| Swift       | 5.0+                        |
| CocoaPods   | 1.9.1+ (if using CocoaPods) |

## Swift Package Manager

Swift Package Manager is the recommended installation method for new projects.

<Steps>
  <Step title="Open Package Dependencies">
    In Xcode, go to **File → Add Package Dependencies**
  </Step>

  <Step title="Enter Package URL">
    In the search field, enter:

    ```
    https://github.com/permutive-engineering/permutive-ios-spm
    ```
  </Step>

  <Step title="Select Version">
    Choose a dependency rule:

    * **Up to Next Major Version**: `2.2.0` (recommended)
    * **Exact Version**: `2.2.0`
  </Step>

  <Step title="Add Package Product">
    Select **Permutive\_iOS** and add it to your target
  </Step>
</Steps>

### Package.swift (for packages)

If you're adding Permutive to a Swift package, add it to your `Package.swift`:

```swift theme={"dark"}
dependencies: [
    .package(url: "https://github.com/permutive-engineering/permutive-ios-spm", from: "2.2.0")
],
targets: [
    .target(
        name: "YourTarget",
        dependencies: [
            .product(name: "Permutive_iOS", package: "permutive-ios-spm")
        ]
    )
]
```

## CocoaPods

### Basic Installation

Add the Permutive pod to your `Podfile`:

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

Then install:

```bash theme={"dark"}
pod install
```

### tvOS Installation

For tvOS targets, specify the tvOS platform:

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

### Multi-Platform Podfile

For apps supporting both iOS and tvOS:

```ruby theme={"dark"}
# Shared dependencies
def shared_pods
  pod 'Permutive_iOS', '~> 2.2.0'
end

target 'YourApp-iOS' do
  platform :ios, '12.0'
  shared_pods
end

target 'YourApp-tvOS' do
  platform :tvos, '12.0'
  shared_pods
end
```

### Updating the SDK

To update to the latest version:

```bash theme={"dark"}
pod update Permutive_iOS
```

## Importing the SDK

After installation, import Permutive in your Swift or Objective-C files:

<CodeGroup>
  ```swift Swift theme={"dark"}
  import Permutive_iOS
  ```

  ```objectivec Objective-C theme={"dark"}
  @import Permutive_iOS;
  ```
</CodeGroup>

## Verifying Installation

After installing, verify the SDK is accessible:

<CodeGroup>
  ```swift Swift theme={"dark"}
  import Permutive_iOS

  // This should compile without errors
  let _ = Permutive.shared
  ```

  ```objectivec Objective-C theme={"dark"}
  @import Permutive_iOS;

  // This should compile without errors
  [Permutive shared];
  ```
</CodeGroup>

Build your project (⌘B) to confirm there are no import errors.

## Mac Catalyst Support

The SDK supports Mac Catalyst. When using Swift Package Manager, add the package as normal - it works for both iOS and Mac Catalyst targets.

For CocoaPods, the standard iOS pod works with Catalyst projects.

## Troubleshooting

<AccordionGroup>
  <Accordion title="CocoaPods: Pod not found">
    **Problem:** `Unable to find a specification for 'Permutive_iOS'`

    **Solutions:**

    * Update your CocoaPods repo: `pod repo update`
    * Ensure CocoaPods is version 1.9.1 or later: `pod --version`
    * Try clearing the cache: `pod cache clean --all`
  </Accordion>

  <Accordion title="SPM: Package resolution failed">
    **Problem:** Xcode cannot resolve the package.

    **Solutions:**

    * Check your network connection
    * Reset package caches: **File → Packages → Reset Package Caches**
    * Verify the URL is correct: `https://github.com/permutive-engineering/permutive-ios-spm`
  </Accordion>

  <Accordion title="Module not found after installation">
    **Problem:** `No such module 'Permutive_iOS'`

    **Solutions:**

    * Clean build folder: **Product → Clean Build Folder** (⇧⌘K)
    * For CocoaPods: Ensure you opened the `.xcworkspace` file, not `.xcodeproj`
    * Restart Xcode
  </Accordion>

  <Accordion title="Bitcode errors">
    **Problem:** Bitcode-related build errors.

    **Solution:** Bitcode is no longer required for App Store submission. Disable it in your target's Build Settings: set **Enable Bitcode** to **No**.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Initialization" icon="gear" href="/sdks/mobile/ios/getting-started/initialization">
    Configure and start the SDK
  </Card>

  <Card title="Quick Start" icon="rocket" href="/sdks/mobile/ios/getting-started/quick-start">
    Complete setup walkthrough
  </Card>
</CardGroup>