> ## 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.
# iOS SDK
> Integrate Permutive into your iOS and tvOS applications for user segmentation, personalization, and ad targeting
export const SDKKeyConcepts = () =>
- **Cohorts**: All segments a user belongs to
- **Activations**: Cohorts configured for specific ad platforms
- **Behavioral**: Based on user history (e.g., "sports enthusiast")
- **Contextual**: Based on current content (e.g., viewing sports article right now)
Multiple identifiers (email, user ID, ad ID) linked to single user profile for cross-device tracking.
;
## Overview
The Permutive iOS SDK enables user segmentation, personalization, and ad targeting in your iOS and tvOS applications. Track user behavior, manage identities across devices, and deliver targeted advertising through integrations with major ad platforms.
**Current Version:** 2.2.0
**Platform Support:** The SDK supports iOS 12.0+ and tvOS 12.0+. Both platforms share the same API with minor differences noted in the documentation.
## Getting Started
New to the Permutive iOS SDK? Start here.
Get up and running with your first page view in minutes
CocoaPods and Swift Package Manager setup
SDK initialization patterns and configuration
Verify your integration is working correctly
## Core Concepts
Understand the fundamental concepts of the Permutive SDK.
Track users across devices and sessions
Structure and validate event data
Understanding user segmentation
Content-based real-time targeting
## Features
Detailed guides for specific SDK features.
Track pageviews and user engagement (recommended approach)
Track custom events
Track video content viewing
Track video advertisement engagement
React to cohort changes in real-time
## Integrations
Connect Permutive with ad platforms and other services.
Google Ad Manager, Xandr, and more
Apple advertising identifier tracking
## Common Tasks
**PageTracker is the recommended approach** for tracking user interactions as it integrates with Permutive's standard events and provides richer insights.
```swift Swift theme={"dark"}
import UIKit
import Permutive_iOS
class ArticleViewController: UIViewController {
private var pageTracker: PageTrackerProtocol?
override func viewDidLoad() {
super.viewDidLoad()
let properties = try? EventProperties([
"category": "sports",
"author": "John Doe"
])
let context = Context(
title: "Article Title",
url: URL(string: "https://example.com/article"),
referrer: nil
)
pageTracker = try? Permutive.shared.createPageTracker(
properties: properties,
context: context
)
}
override func viewDidAppear(_ animated: Bool) {
super.viewDidAppear(animated)
try? pageTracker?.resume()
}
override func viewDidDisappear(_ animated: Bool) {
super.viewDidDisappear(animated)
pageTracker?.pause()
}
deinit {
pageTracker?.stop()
}
}
```
```objectivec Objective-C theme={"dark"}
#import "ArticleViewController.h"
@import Permutive_iOS;
@interface ArticleViewController ()
@property (nonatomic, strong) NSObject *pageTracker;
@end
@implementation ArticleViewController
- (void)viewDidLoad {
[super viewDidLoad];
NSError *error = nil;
PermutiveEventProperties *properties = [[PermutiveEventProperties alloc]
init:@{@"category": @"sports", @"author": @"John Doe"}
error:&error];
PermutiveContext *context = [[PermutiveContext alloc]
initWithTitle:@"Article Title"
url:[NSURL URLWithString:@"https://example.com/article"]
referrer:nil];
self.pageTracker = [Permutive.shared
createPageTrackerWithProperties:properties
context:context
error:&error];
}
- (void)viewDidAppear:(BOOL)animated {
[super viewDidAppear:animated];
[self.pageTracker resumeAndReturnError:nil];
}
- (void)viewDidDisappear:(BOOL)animated {
[super viewDidDisappear:animated];
[self.pageTracker pause];
}
- (void)dealloc {
[self.pageTracker stop];
}
@end
```
```swift Swift theme={"dark"}
let aliases = [
Alias(tag: "email_sha256", identity: emailHash),
Alias(tag: "internal_id", identity: userId, priority: 1)
]
try? Permutive.shared.setIdentities(aliases: aliases)
```
```objectivec Objective-C theme={"dark"}
PermutiveAlias *emailAlias = [[PermutiveAlias alloc]
initWithTag:@"email_sha256" identity:emailHash];
PermutiveAlias *idAlias = [[PermutiveAlias alloc]
initWithTag:@"internal_id" identity:userId priority:1];
[Permutive.shared setIdentitiesWithAliases:@[emailAlias, idAlias] error:nil];
```
```swift Swift theme={"dark"}
var trigger: TriggerAction?
func watchCohort() {
trigger = Permutive.shared.triggerProvider?.action(
boolFor: ["premium_user"],
action: { query, isInCohort in
if isInCohort {
self.showPremiumFeatures()
}
}
)
}
// Release trigger when done
deinit {
trigger = nil
}
```
```objectivec Objective-C theme={"dark"}
// Hold strong reference
@property (nonatomic, strong) PermutiveTriggerAction *trigger;
- (void)watchCohort {
NSSet *cohorts = [NSSet setWithObject:@"premium_user"];
self.trigger = [Permutive.shared.triggerProvider
actionWithBoolFor:cohorts
action:^(NSString *cohort, BOOL result) {
if (result) {
[self showPremiumFeatures];
}
}];
}
```
```swift Swift theme={"dark"}
let adRequest = GAMRequest()
adRequest.customTargeting = Permutive.shared.googleCustomTargeting(
adTargetable: pageTracker
)
bannerView.load(adRequest)
```
```objectivec Objective-C theme={"dark"}
GAMRequest *adRequest = [GAMRequest request];
adRequest.customTargeting = [Permutive.shared
googleCustomTargetingWithAdTargetable:self.pageTracker];
[self.bannerView loadRequest:adRequest];
```
## Requirements
| Requirement | Version |
| ----------- | ------- |
| iOS | 12.0+ |
| tvOS | 12.0+ |
| Xcode | 13.0+ |
| Swift | 5.0+ |
Add the package URL in Xcode:
```
https://github.com/permutive-engineering/permutive-ios-spm
```
Select `Permutive_iOS` as the package product.
```ruby theme={"dark"}
target 'YourApp' do
platform :ios, '12.0'
pod 'Permutive_iOS', '~> 2.2.0'
end
```
## Key Concepts
## Additional Resources
API documentation and technical reference.
* **[API Reference](https://storage.googleapis.com/permutive-ios-refdocs/html/index.html)** - Complete API documentation
* **[Apple Privacy Information](/sdks/mobile/ios/integrations/idfa-provider#apple-privacy)** - App Store privacy requirements
**tvOS Differences:** The tvOS SDK shares the same API as iOS, with the following exceptions:
* IDFA/App Tracking Transparency is not available on tvOS
* UI patterns use focus-based navigation instead of touch
## FAQ
**PageTracker** is the recommended approach for most use cases. It automatically tracks Pageview events, measures engagement time, and enables contextual cohorts when URLs are provided.
**Direct event tracking** via `track(event:properties:)` is for specialized cases where you need to track custom events that don't fit the page model.
Enable logging in your initialization options:
```swift theme={"dark"}
let options = Options(
apiKey: "",
organisationId: ""
)
options.logModes = LogMode.all
```
Messages will appear in the Xcode console.
Use hashed emails (SHA-256), internal user IDs, or the vendor identifier (`identifierForVendor`). Never send plain text PII. See the [Identity Management](/sdks/mobile/ios/core-concepts/identity-management) guide for details.
Permutive recommends against using IDFA due to Apple's App Tracking Transparency requirements. Consider using `identifierForVendor` or hashed email addresses instead. See the [IDFA Provider](/sdks/mobile/ios/integrations/idfa-provider) guide if you do need IDFA.
## Getting Help
* **[Troubleshooting Guide](/sdks/mobile/ios/troubleshooting/common-errors)** - Solutions to common issues
* **Customer Success Manager (CSM)** - For enabling features and exploring use cases
* **[Technical Services](mailto:technical-services@permutive.com)** - For technical setup and configuration
* **[Support](mailto:support@permutive.com)** - For troubleshooting and help
## Privacy & Compliance
Permutive is designed with privacy in mind: GDPR compliant, CCPA compliant, no PII storage, user consent respected, and transparent data usage.