Identity Management

Identity management allows you to track users across different sessions, devices, and platforms by associating multiple identifiers (aliases) with a single user profile.

Single Identity

Multiple Identities

IDFA Provider

Overview

In the iOS SDK, you can set aliases using the setIdentities(aliases:) method. The SDK uses a singleton pattern via Permutive.shared.

Key Concepts

Alias

Identity Resolution

Priority System

Setting Identity

Single Alias
Multiple Aliases

For apps with a single identifier type:

do {
    let alias = Alias(tag: "internal_id", identity: userId)
    try Permutive.shared.setIdentities(aliases: [alias])
} catch {
    print("Failed to set identity: \(error)")
}

NSError *error = nil;
PermutiveAlias *alias = [[PermutiveAlias alloc]
    initWithTag:@"internal_id"
    identity:userId];

[Permutive.shared setIdentitiesWithAliases:@[alias] error:&error];

For apps tracking multiple identifier types (email, user ID, etc.):

do {
    let aliases = [
        // Highest priority: hashed email
        Alias(tag: "email_sha256", identity: emailHash),
        // Medium priority: internal user ID
        Alias(tag: "internal_id", identity: userId, priority: 1),
        // Lower priority: with expiry date
        Alias(
            tag: "session_id",
            identity: sessionId,
            priority: 2,
            expiry: Date().addingTimeInterval(86400 * 30) // 30 days
        )
    ]
    try Permutive.shared.setIdentities(aliases: aliases)
} catch {
    print("Failed to set identities: \(error)")
}

NSError *error = nil;

// Highest priority: hashed email
PermutiveAlias *emailAlias = [[PermutiveAlias alloc]
    initWithTag:@"email_sha256"
    identity:emailHash];

// Medium priority: internal user ID
PermutiveAlias *idAlias = [[PermutiveAlias alloc]
    initWithTag:@"internal_id"
    identity:userId
    priority:1];

// Lower priority: with expiry
NSDate *expiry = [NSDate dateWithTimeIntervalSinceNow:86400 * 30];
PermutiveAlias *sessionAlias = [[PermutiveAlias alloc]
    initWithTag:@"session_id"
    identity:sessionId
    priority:2
    expiry:expiry];

[Permutive.shared setIdentitiesWithAliases:@[emailAlias, idAlias, sessionAlias]
                                     error:&error];

Security Best Practices

Always hash personally identifiable information like email addresses before sending to Permutive.

Correct - Hashed
Incorrect - Plain Text

import CryptoKit

func hashEmail(_ email: String) -> String {
    let normalized = email.trimmingCharacters(in: .whitespaces).lowercased()
    let data = Data(normalized.utf8)
    let hash = SHA256.hash(data: data)
    return hash.compactMap { String(format: "%02x", $0) }.joined()
}

// Usage
let emailHash = hashEmail("user@example.com")
let alias = Alias(tag: "email_sha256", identity: emailHash)
try? Permutive.shared.setIdentities(aliases: [alias])

// DON'T DO THIS - sending PII
let alias = Alias(tag: "email", identity: "user@example.com")  // WRONG!

Standard Tag Names

Identifier Type	Recommended Tag	Notes
SHA-256 hashed email	`email_sha256`	Most common
Internal user ID	`internal_id` or `user_id`	Your system’s ID
Vendor identifier	`idfv`	`UIDevice.identifierForVendor`
Customer ID	`customer_id`	E-commerce systems
Subscriber ID	`subscriber_id`	Subscription services

Reserved Tags

Some alias tags are reserved by the SDK and cannot be used:

appnexus
amp
gigya
sailthru
aaid

Aliases with these tags will be ignored.

IDFA Identity

Permutive recommends against using IDFA due to Apple’s App Tracking Transparency requirements. Consider using identifierForVendor or hashed email addresses instead.

From v2.6.0, the IDFA, IDFV, and IP address can be collected automatically when enabled in your workspace config — no manual code required. See the v2.6 Migration Guide. If you opt into automatic collection, you generally don’t need the manual setIdentityForIDFA flow below.

If you do need to set IDFA manually, use the dedicated setIdentityForIDFA method:

import AdSupport
import AppTrackingTransparency
import Permutive_iOS

func setIDFAIdentity() {
    if #available(iOS 14, *) {
        ATTrackingManager.requestTrackingAuthorization { status in
            guard status == .authorized else { return }

            let idfa = ASIdentifierManager.shared().advertisingIdentifier
            do {
                try Permutive.shared.setIdentityForIDFA(idfa)
            } catch {
                // IDFA may be all zeros (tracking denied)
                print("Failed to set IDFA: \(error)")
            }
        }
    }
}

IDFA Provider Guide

Complete IDFA integration documentation

Retrieving User ID

Get the current Permutive user ID:

let userId = Permutive.shared.currentUserId
print("Permutive User ID: \(userId)")

NSString *userId = [Permutive.shared currentUserId];
NSLog(@"Permutive User ID: %@", userId);

Tracking User ID Changes

Use TriggerAction to react when the user ID changes:

var userIdTrigger: TriggerAction?

func watchUserIdChanges() {
    userIdTrigger = Permutive.shared.triggerProvider?.actionUpdateForUserIdentity { userId in
        print("User ID changed to: \(userId)")
    }
}

// Release when done
deinit {
    userIdTrigger = nil
}

@property (nonatomic, strong) PermutiveTriggerAction *userIdTrigger;

- (void)watchUserIdChanges {
    self.userIdTrigger = [Permutive.shared.triggerProvider
        actionUpdateForUserIdentity:^(NSString *userId) {
            NSLog(@"User ID changed to: %@", userId);
        }];
}

Common Patterns

func onLoginSuccess(userId: String, email: String) {
    let emailHash = hashEmail(email)

    do {
        let aliases = [
            Alias(tag: "email_sha256", identity: emailHash),
            Alias(tag: "internal_id", identity: userId, priority: 1)
        ]
        try Permutive.shared.setIdentities(aliases: aliases)
    } catch {
        print("Failed to set identity: \(error)")
    }
}

- (void)onLoginSuccessWithUserId:(NSString *)userId email:(NSString *)email {
    NSString *emailHash = [self hashEmail:email];

    NSError *error = nil;
    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:&error];
}

Using Vendor Identifier

import UIKit
import Permutive_iOS

func setVendorIdentity() {
    guard let idfv = UIDevice.current.identifierForVendor?.uuidString else {
        return
    }

    let alias = Alias(tag: "idfv", identity: idfv, priority: 2)
    try? Permutive.shared.setIdentities(aliases: [alias])
}

Guest to Logged-In Transition

class UserManager {
    // User starts as guest (anonymous)
    func onAppLaunch() {
        // SDK automatically creates anonymous ID
        // Optionally set vendor identifier
        setVendorIdentity()
    }

    // User logs in or signs up
    func onUserAuthenticated(userId: String, email: String) {
        let emailHash = hashEmail(email)

        // Permutive merges guest data with authenticated profile
        try? Permutive.shared.setIdentities(aliases: [
            Alias(tag: "email_sha256", identity: emailHash),
            Alias(tag: "internal_id", identity: userId, priority: 1)
        ])
    }
}

Expiry

Aliases can expire automatically, useful for GDPR compliance, session identifiers, and temporary access tokens.

// Never expire (default)
Alias(tag: "email_sha256", identity: emailHash)

// Expire in 30 days
let thirtyDaysFromNow = Date().addingTimeInterval(86400 * 30)
Alias(tag: "session_id", identity: sessionId, expiry: thirtyDaysFromNow)

// Expire at distant future (effectively never)
Alias(tag: "permanent_id", identity: id, expiry: Date.distantFuture)

tvOS Considerations

tvOS Note: Identity management works identically on tvOS. App Tracking Transparency and IDFA are available on tvOS from version 14.5 onwards.

Troubleshooting

Identity not resolving

Problem: Setting identity doesn’t merge user data across devices.Solutions:

Check network connectivity
Verify the alias has been used in other sessions/devices
Enable debug logging: options.logModes = LogMode.all
Look for identity-related logs in the console

User identity split

Problem: Same user appears as two different users.Solution: Use consistent alias tags and values. When a user logs in on multiple devices, use the same alias (e.g., hashed email).

Reserved tag error

Problem: Alias with certain tags is ignored.Solution: Avoid reserved tags: appnexus, amp, gigya, sailthru, aaid. Use custom tags instead.

Best Practices

Do
Don't

Hash PII (especially email addresses) before setting as identity
Use meaningful tag names that describe the identifier type
Set priorities based on reliability and persistence
Use expiry dates for temporary or less reliable identifiers
Set identity as early as possible in the user journey
Use identifierForVendor as a fallback identifier

IDFA Provider

Apple advertising identifier integration

Cohorts & Activations

Understanding user segments

Triggers Provider

React to cohort changes

Issues

Solutions to common issues

Get Started

Products

Deployment

Governance

Identity Management

Single Identity

Multiple Identities

IDFA Provider

Overview

Key Concepts

Setting Identity

Security Best Practices

Standard Tag Names

Reserved Tags

IDFA Identity

IDFA Provider Guide

Retrieving User ID

Tracking User ID Changes

Common Patterns

Expiry

tvOS Considerations

Troubleshooting

Best Practices

IDFA Provider

Cohorts & Activations

Triggers Provider

Issues

Single Identity

Multiple Identities

IDFA Provider

​Overview

​Key Concepts

​Setting Identity

​Security Best Practices

​Standard Tag Names

​Reserved Tags

​IDFA Identity

IDFA Provider Guide

​Retrieving User ID

​Tracking User ID Changes

​Common Patterns

​Expiry

​tvOS Considerations

​Troubleshooting

​Best Practices

​Related Documentation

IDFA Provider

Cohorts & Activations

Triggers Provider

Issues

Overview

Key Concepts

Setting Identity

Security Best Practices

Standard Tag Names

Reserved Tags

IDFA Identity

Retrieving User ID

Tracking User ID Changes

Common Patterns

Expiry

tvOS Considerations

Troubleshooting

Best Practices

Related Documentation