Common Issues

This guide covers common issues and their solutions when integrating the Permutive iOS SDK.

Installation

Initialization

Tracking

Installation Issues

CocoaPods: Pod not found

Error: 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
Clear the cache:
pod cache clean --all pod install

SPM: Package resolution failed

Error: 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
Try removing and re-adding the package

Module not found after installation

Error: 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
For SPM: Reset package caches

Bitcode errors

Error: Bitcode-related build errors.Solution: Disable Bitcode in your target’s Build Settings:

Set Enable Bitcode to No

Bitcode is no longer required for App Store submission.

Duplicate symbols

Error: Duplicate symbol errors during linking.Solutions:

Ensure you’re not mixing CocoaPods and SPM for Permutive
Check for conflicting library versions
Clean derived data: rm -rf ~/Library/Developer/Xcode/DerivedData

Initialization Issues

Options returns nil

Problem: Options(apiKey:organisationId:workspaceId:) returns nil.Causes:

Empty or whitespace-only credentials
Invalid credential format

Solution: Verify your credentials:

let apiKey = "<your-api-key>".trimmingCharacters(in: .whitespacesAndNewlines)
let orgId = "<your-org-id>".trimmingCharacters(in: .whitespacesAndNewlines)
let workspaceId = "<your-workspace-id>".trimmingCharacters(in: .whitespacesAndNewlines)

guard !apiKey.isEmpty, !orgId.isEmpty, !workspaceId.isEmpty else {
    print("Credentials are empty")
    return
}

guard let options = Options(apiKey: apiKey, organisationId: orgId, workspaceId: workspaceId) else {
    print("Invalid credential format")
    return
}

Initialization fails silently

Problem: No error, but SDK doesn’t seem to work.Solution: Enable debug logging and check for errors:

options.logModes = LogMode.all

Permutive.shared.start(with: options) { error in
    if let error = error {
        print("Initialization failed: \(error)")
    } else {
        print("SDK initialized successfully")
    }
}

Network error during initialization

Problem: Initialization fails with network error.Solutions:

Check device network connectivity
Verify no firewall is blocking Permutive domains
Check if running on simulator with network issues

Retry initialization:

Permutive.shared.start(with: options) { error in
    if error != nil {
        // Retry after delay
        DispatchQueue.main.asyncAfter(deadline: .now() + 2) {
            Permutive.shared.start(with: options, completion: nil)
        }
    }
}

SDK not ready when tracking

Problem: Events tracked before initialization completes are lost.Solution: Wait for the completion callback:

Permutive.shared.start(with: options) { error in
    guard error == nil else { return }
    // Now safe to track
    self.startTracking()
}

Tracking Issues

Events rejected with schema error

Error:

Permutive: [error] Schema validation failed with reason(s): [#: extraneous key [invalid_key] is not permitted]

Causes:

Property names don’t match schema
Property types don’t match schema
Extra properties not in schema

Solutions:

Check your Permutive dashboard for the correct schema
Verify property names exactly (case-sensitive)
Remove any extra properties
Verify property types match (string, int, bool, etc.)

EventProperties init throws

Error: EventProperties constructor throws an exception.Causes:

Unsupported value types
Invalid nested objects

Solutions: Ensure all values are supported types:

// Supported types:
// String, Int, Float, Double, Bool, Date, EventProperties, and arrays of these

// ❌ Wrong - Custom object
let props = try EventProperties(["user": myUserObject])

// ✅ Correct - Primitive types
let props = try EventProperties([
    "user_id": user.id,           // String
    "user_name": user.name,       // String
    "age": user.age               // Int
])

Pageview event not firing

Problem: No Pageview event in logs.Solutions:

Ensure resume() is called:

override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    try? pageTracker?.resume()  // Must call this
}

Check PageTracker was created successfully
Verify SDK is initialized before creating PageTracker
Enable debug logging

PageTracker stops unexpectedly

Problem: PageTracker stops when navigating or creating new trackers.Cause: Only one PageTracker/MediaTracker can be active at a time.Solution: This is expected behavior. Creating a new tracker stops any existing one. Design your flow accordingly.

No log output

Problem: Console is silent, no Permutive logs appear.Solutions:

Confirm logModes is set before start():

options.logModes = LogMode.all  // Must set before start()
Permutive.shared.start(with: options) { ... }

Check Xcode console filter isn’t hiding messages
Verify SDK is actually being initialized

Cohort and Activation Issues

Empty cohorts

Problem: Permutive.shared.cohorts returns an empty set.Causes:

SDK just initialized (cohorts not yet synced)
No events tracked yet
User doesn’t qualify for any cohorts

Solutions:

Wait a few seconds after initialization
Track some events to generate data
Use TriggerProvider for reactive updates
Check your dashboard for cohort definitions

Activations different from cohorts

Problem: User is in a cohort but it doesn’t appear in activations.Cause: Not all cohorts are activated for all platforms.Solution: Check your Permutive dashboard configuration. Activations must be explicitly configured for each platform (GAM, Xandr, etc.).

Contextual cohorts not appearing

Problem: dfp_contextual or appnexus_adserver_contextual is empty.Solutions:

Verify contextual features are enabled (contact your CSM)
Update to SDK 2.0.0+
Ensure PageTracker has a valid, publicly accessible URL
Allow time for content analysis (1-2 seconds)
Check debug logs for classification errors

Identity Issues

setIdentityForIDFA fails

Error: setIdentityForIDFA throws an error.Cause: IDFA is all zeros (tracking denied/restricted).Solution:

if #available(iOS 14, *) {
    let status = ATTrackingManager.trackingAuthorizationStatus
    guard status == .authorized else {
        // Use alternative identity
        return
    }
}

let idfa = ASIdentifierManager.shared().advertisingIdentifier
guard idfa != UUID(uuidString: "00000000-0000-0000-0000-000000000000") else {
    // IDFA not available
    return
}

try Permutive.shared.setIdentityForIDFA(idfa)

Reserved tag error

Problem: Alias with certain tags is ignored.Cause: Reserved tags: appnexus, amp, gigya, sailthru, aaidSolution: Use custom tag names:

// ❌ Wrong
Alias(tag: "appnexus", identity: id)  // Reserved, will be ignored

// ✅ Correct
Alias(tag: "my_appnexus_id", identity: id)

Identity not merging across devices

Problem: Same user appears as different users on different devices.Solution: Use consistent identifiers that work across devices:

// Best: Hashed email (works across all devices)
Alias(tag: "email_sha256", identity: hashedEmail, priority: 0)

// Good: Your internal user ID
Alias(tag: "internal_id", identity: userId, priority: 1)

Ad Integration Issues

No targeting data in ad request

Problem: googleCustomTargeting returns empty or minimal data.Solutions:

Verify SDK is initialized before calling
Check that cohorts exist for the user
Wait for cohort data to sync after initialization
Enable debug logging to see activations

View ID missing from targeting

Problem: prmtvvid key not in targeting dictionary.Solution: Pass the active PageTracker:

// ❌ Wrong - no view ID
Permutive.shared.googleCustomTargeting(adTargetable: nil)

// ✅ Correct - includes view ID
Permutive.shared.googleCustomTargeting(adTargetable: pageTracker)

TriggerProvider Issues

Trigger callbacks not firing

Problem: No callbacks when cohort membership changes.Solutions:

Store a strong reference to TriggerAction:

class MyController {
    // Store as property, not local variable
    private var trigger: TriggerAction?

    func setup() {
        trigger = Permutive.shared.triggerProvider?.action(...)
    }
}

Verify cohort IDs match your dashboard exactly
Enable debug logging to see cohort updates

Trigger stops working

Problem: Trigger worked initially but stopped.Cause: TriggerAction reference was released.Solution: Keep TriggerAction as an instance property for the lifetime you need it.

Debug Logging

Enable comprehensive logging for troubleshooting:

guard let options = Options(
    apiKey: "<your-api-key>",
    organisationId: "<your-org-id>",
    workspaceId: "<your-workspace-id>"
) else { return }

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

Permutive.shared.start(with: options) { error in
    // Check console for detailed logs
}

Log Messages to Look For

Message	Meaning
`SDK ready`	Initialization successful
`Accepted: X / X`	Events sent successfully
`event rejection`	Schema validation failed
`Schema validation failed`	Property mismatch

Always disable debug logging in production builds to avoid performance overhead.

#if DEBUG
options.logModes = LogMode.all
#else
options.logModes = LogMode.none
#endif

Getting Help

If you can’t resolve an issue:

Enable debug logging and capture relevant logs
Check SDK version - ensure you’re on the latest
Contact support:
- Support

Include in your support request:

SDK version
iOS/tvOS version
Xcode version
Relevant logs
Steps to reproduce

Installation

Setup troubleshooting

Initialization

Configuration options

Verification

Verify your integration

Event Properties

Schema requirements

Get Started

Products

Deployment

Governance

Installation

Initialization

Tracking

Installation Issues

Initialization Issues

Tracking Issues

Cohort and Activation Issues

Identity Issues

Ad Integration Issues

TriggerProvider Issues

Debug Logging

Log Messages to Look For

Getting Help

Installation

Initialization

Verification

Event Properties

Installation

Initialization

Tracking

​Installation Issues

​Initialization Issues

​Tracking Issues

​Cohort and Activation Issues

​Identity Issues

​Ad Integration Issues

​TriggerProvider Issues

​Debug Logging

​Log Messages to Look For

​Getting Help

​Related Documentation

Installation

Initialization

Verification

Event Properties

Installation Issues

Initialization Issues

Tracking Issues

Cohort and Activation Issues

Identity Issues

Ad Integration Issues

TriggerProvider Issues

Debug Logging

Log Messages to Look For

Getting Help

Related Documentation