axiom-privacy-ux

name	axiom-privacy-ux
description	Use when implementing privacy manifests, requesting permissions, App Tracking Transparency UX, or preparing Privacy Nutrition Labels - covers just-in-time permission requests, tracking domain management, and Required Reason APIs from WWDC 2023
license	MIT
metadata	{"version":"1.0.0"}

Privacy UX Patterns

Comprehensive guide to privacy-first app design. Apple Design Award Social Impact winners handle data ethically, and privacy-first design is a key differentiator.

Overview

Privacy manifests (PrivacyInfo.xcprivacy) are Apple's framework for transparency about data collection and tracking. Combined with App Tracking Transparency and just-in-time permission requests, they help users make informed choices about their data.

This skill covers creating privacy manifests, requesting system permissions with excellent UX, implementing App Tracking Transparency, managing tracking domains, using Required Reason APIs, and preparing accurate Privacy Nutrition Labels.

When to Use This Skill

• Creating privacy manifests (PrivacyInfo.xcprivacy)
• Requesting system permissions (Camera, Location, etc.)
• Implementing App Tracking Transparency (ATT)
• Preparing Privacy Nutrition Labels for App Store Connect
• Managing tracking domains to avoid accidental tracking
• Using Required Reason APIs (NSFileSystemFreeSize, UserDefaults, etc.)
• Explaining data usage to users transparently
• Debugging privacy-related App Store rejections

System Requirements

• iOS 14.5+ for App Tracking Transparency
• iOS 17+ for automatic tracking domain blocking
• Xcode 15+ for privacy reports and manifest editing
• Spring 2024+ for App Review enforcement

---

Part 1: Privacy Manifests (WWDC 2023/10060)

Creating a Privacy Manifest

Xcode Navigator:

1. File → New → File
2. Choose "App Privacy File"
3. Name: PrivacyInfo.xcprivacy
4. Add to app target (or SDK framework)

File structure (Property List):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>NSPrivacyTracking</key>
    <false/>
    <key>NSPrivacyCollectedDataTypes</key>
    <array>
        <!-- Data types collected -->
    </array>
    <key>NSPrivacyAccessedAPITypes</key>
    <array>
        <!-- Required Reason APIs used -->
    </array>
</dict>
</plist>

NSPrivacyTracking Declaration

Does your app track users?

Tracking = combining user/device data from your app with data from other apps/websites to create a profile for targeted advertising or data broker purposes.

<key>NSPrivacyTracking</key>
<true/>  <!-- or false -->

If true, you must also declare tracking domains:

<key>NSPrivacyTrackingDomains</key>
<array>
    <string>tracking.example.com</string>
    <string>analytics.example.com</string>
</array>

iOS 17 behavior: Network requests to tracking domains automatically blocked if user hasn't granted ATT permission.

NSPrivacyCollectedDataTypes

Declare all data your app collects:

<key>NSPrivacyCollectedDataTypes</key>
<array>
    <dict>
        <key>NSPrivacyCollectedDataType</key>
        <string>NSPrivacyCollectedDataTypeName</string>

        <key>NSPrivacyCollectedDataTypeLinked</key>
        <true/>  <!-- Linked to user identity? -->

        <key>NSPrivacyCollectedDataTypeTracking</key>
        <false/>  <!-- Used for tracking? -->

        <key>NSPrivacyCollectedDataTypePurposes</key>
        <array>
            <string>NSPrivacyCollectedDataTypePurposeAppFunctionality</string>
            <string>NSPrivacyCollectedDataTypePurposeAnalytics</string>
        </array>
    </dict>
</array>

Common data types:

• NSPrivacyCollectedDataTypeName - User's name
• NSPrivacyCollectedDataTypeEmailAddress
• NSPrivacyCollectedDataTypePhoneNumber
• NSPrivacyCollectedDataTypePhysicalAddress
• NSPrivacyCollectedDataTypePreciseLocation
• NSPrivacyCollectedDataTypeCoarseLocation
• NSPrivacyCollectedDataTypePhotosorVideos
• NSPrivacyCollectedDataTypeContacts
• NSPrivacyCollectedDataTypeUserID

Common purposes:

• NSPrivacyCollectedDataTypePurposeAppFunctionality
• NSPrivacyCollectedDataTypePurposeAnalytics
• NSPrivacyCollectedDataTypePurposeProductPersonalization
• NSPrivacyCollectedDataTypePurposeDeveloperAdvertising
• NSPrivacyCollectedDataTypePurposeThirdPartyAdvertising

NSPrivacyAccessedAPITypes

Declare Required Reason APIs (see Part 5):

<key>NSPrivacyAccessedAPITypes</key>
<array>
    <dict>
        <key>NSPrivacyAccessedAPIType</key>
        <string>NSPrivacyAccessedAPICategoryFileTimestamp</string>

        <key>NSPrivacyAccessedAPITypeReasons</key>
        <array>
            <string>C617.1</string>  <!-- Approved reason code -->
        </array>
    </dict>
</array>

---

Part 2: Permission Request UX

Just-in-Time vs Up-Front

❌ Don't: Request all permissions at launch

// BAD - overwhelming and confusing
func application(_ application: UIApplication,
                didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    requestCameraPermission()
    requestLocationPermission()
    requestNotificationPermission()
    requestPhotoLibraryPermission()
    return true
}

✅ Do: Request just-in-time when user triggers feature

// GOOD - clear causality
@objc func takePhotoButtonTapped() {
    // Show pre-permission education first
    showCameraEducation {
        // Then request permission
        AVCaptureDevice.requestAccess(for: .video) { granted in
            if granted {
                self.openCamera()
            } else {
                self.showPermissionDeniedAlert()
            }
        }
    }
}

Pre-Permission Education Screens

Explain why you need permission before showing system dialog:

func showCameraEducation(completion: @escaping () -> Void) {
    let alert = UIAlertController(
        title: "Take Photos",
        message: "FoodSnap needs camera access to let you photograph your meals and get nutrition information.",
        preferredStyle: .alert
    )

    alert.addAction(UIAlertAction(title: "Continue", style: .default) { _ in
        completion()  // Now request actual permission
    })

    alert.addAction(UIAlertAction(title: "Not Now", style: .cancel))

    present(alert, animated: true)
}

Why this works:

• User understands value proposition
• System dialog rejection rate drops 60-80%
• Better App Store ratings (fewer "why does it need that?" reviews)

Permission Denied Handling

Never dead-end the user:

func handleCameraPermission() {
    switch AVCaptureDevice.authorizationStatus(for: .video) {
    case .authorized:
        openCamera()

    case .notDetermined:
        showCameraEducation {
            AVCaptureDevice.requestAccess(for: .video) { granted in
                if granted {
                    self.openCamera()
                } else {
                    self.showSettingsPrompt()
                }
            }
        }

    case .denied, .restricted:
        showSettingsPrompt()  // Offer to open Settings

    @unknown default:
        break
    }
}

func showSettingsPrompt() {
    let alert = UIAlertController(
        title: "Camera Access Required",
        message: "Please enable camera access in Settings to use this feature.",
        preferredStyle: .alert
    )

    alert.addAction(UIAlertAction(title: "Open Settings", style: .default) { _ in
        if let url = URL(string: UIApplication.openSettingsURLString) {
            UIApplication.shared.open(url)
        }
    })

    alert.addAction(UIAlertAction(title: "Cancel", style: .cancel))

    present(alert, animated: true)
}

Settings Deep Links

Open specific settings screens:

// General app settings
UIApplication.shared.open(URL(string: UIApplication.openSettingsURLString)!)

// Notification settings (iOS 15.4+)
UIApplication.shared.open(URL(string: UIApplication.openNotificationSettingsURLString)!)

---

Part 3: App Tracking Transparency

When ATT Is Required

You must request ATT permission if you:

• Track users across apps/websites owned by other companies
• Share user data with data brokers
• Use third-party SDKs that track (Facebook SDK, Google Analytics, etc.)

You don't need ATT if you only:

• Use first-party analytics (no sharing with other companies)
• Personalize ads based only on data from your own app
• Use fraud detection/security measures

ATTrackingManager.requestTrackingAuthorization

import AppTrackingTransparency
import AdSupport

func requestTrackingPermission() {
    // Check availability (iOS 14.5+)
    guard #available(iOS 14.5, *) else { return }

    // Wait until app is active
    // Showing alert too early causes auto-denial
    DispatchQueue.main.asyncAfter(deadline: .now() + 1.0) {
        ATTrackingManager.requestTrackingAuthorization { status in
            switch status {
            case .authorized:
                // User granted permission
                // You can now access IDFA and track
                let idfa = ASIdentifierManager.shared().advertisingIdentifier
                self.initializeTrackingSDKs(idfa: idfa)

            case .denied:
                // User denied permission
                // Do NOT track
                self.initializeNonTrackingSDKs()

            case .notDetermined:
                // User closed dialog without choosing
                // Treat as denied
                self.initializeNonTrackingSDKs()

            case .restricted:
                // Device doesn't allow tracking (parental controls)
                self.initializeNonTrackingSDKs()

            @unknown default:
                self.initializeNonTrackingSDKs()
            }
        }
    }
}

Custom ATT Prompt Message

Info.plist:

<key>NSUserTrackingUsageDescription</key>
<string>This allows us to show you personalized ads and improve your experience</string>

Best practices:

• Be honest and specific
• Explain user benefit (not company benefit)
• Keep it concise (1-2 sentences)

❌ Bad examples:

• "We value your privacy" (vague)
• "This is required for the app to work" (dishonest)
• "To monetize our app" (user doesn't care)

✅ Good examples:

• "This helps us show you relevant ads for products you might like"
• "Personalized ads help keep this app free"

Pre-Tracking Prompt Design

Show your own dialog before ATT system prompt:

func showPreTrackingPrompt() {
    let alert = UIAlertController(
        title: "Support Free Features",
        message: "We use tracking to show you personalized ads, which helps keep advanced features free. You can always change this in Settings.",
        preferredStyle: .alert
    )

    alert.addAction(UIAlertAction(title: "Continue", style: .default) { _ in
        self.requestTrackingPermission()
    })

    alert.addAction(UIAlertAction(title: "Not Now", style: .cancel))

    present(alert, animated: true)
}

Why this works: Education increases opt-in rates by 20-40%.

Graceful Degradation

Always provide value without tracking:

func initializeAnalytics() {
    let status = ATTrackingManager.trackingAuthorizationStatus

    if status == .authorized {
        // Full featured analytics
        Analytics.setUserProperty(userID, forName: "user_id")
        Analytics.enableCrossAppTracking()
    } else {
        // Limited, privacy-preserving analytics
        Analytics.setUserProperty("anonymous", forName: "user_id")
        Analytics.disableCrossAppTracking()
        Analytics.enableOnDeviceConversionTracking()
    }
}

---

Part 4: Tracking Domain Management

Declaring Tracking Domains

In PrivacyInfo.xcprivacy:

<key>NSPrivacyTracking</key>
<true/>

<key>NSPrivacyTrackingDomains</key>
<array>
    <string>tracking.example.com</string>
    <string>ads.example.com</string>
</array>

iOS 17 behavior: If user denies ATT, network requests to these domains are automatically blocked.

Domain Separation Strategy

Problem: Single domain used for both tracking and non-tracking

Solution: Separate functionality into different hosts

Before:
- api.example.com (mixed tracking + app functionality)

After:
- api.example.com (app functionality only)
- tracking.example.com (tracking only)

Update manifest:

<key>NSPrivacyTrackingDomains</key>
<array>
    <string>tracking.example.com</string>  <!-- Declared, will be blocked -->
</array>

Result: App functionality continues working; tracking blocked if denied.

Points of Interest Instrument (Xcode 15+)

Detecting unexpected tracking connections:

1. Xcode → Product → Profile
2. Choose "Points of Interest" instrument
3. Run app
4. Look for "Privacy" track showing network connections
5. Review flagged domains

What it shows: Connections to domains that may be tracking users across apps/websites.

Action: Declare these domains in NSPrivacyTrackingDomains or stop connecting to them.

---

Part 5: Required Reason APIs

What Are Required Reason APIs?

APIs that could be misused for fingerprinting (identifying devices without permission).

Fingerprinting is never allowed, even with ATT permission.

Required Reason APIs have approved use cases. You must declare which approved reason applies to your usage.

Common Required Reason APIs

API Category	Examples	Approved Reason Codes
File timestamp	creationDate, modificationDate	C617.1 - DDA9.1
System boot time	systemUptime, processInfo.systemUptime	35F9.1, 8FFB.1
Disk space	NSFileSystemFreeSize, volumeAvailableCapacity	E174.1, 7D9E.1
Active keyboards	activeInputModes	54BD.1, 3EC4.1
User defaults	UserDefaults	CA92.1, 1C8F.1, C56D.1

Example: Disk Space API

API: NSFileSystemFreeSize / URLResourceKey.volumeAvailableCapacityKey

Approved reasons:

• E174.1: Check if there's enough space before writing files
• 7D9E.1: Display storage information to user
• B728.1: Include disk space in optional analytics (only if user opted in)

Declaration in manifest:

<key>NSPrivacyAccessedAPITypes</key>
<array>
    <dict>
        <key>NSPrivacyAccessedAPIType</key>
        <string>NSPrivacyAccessedAPICategoryDiskSpace</string>

        <key>NSPrivacyAccessedAPITypeReasons</key>
        <array>
            <string>E174.1</string>  <!-- Check space before writing -->
        </array>
    </dict>
</array>

Code:

func checkDiskSpace() -> Bool {
    do {
        let values = try FileManager.default.attributesOfFileSystem(forPath: NSHomeDirectory())

        if let freeSpace = values[.systemFreeSize] as? NSNumber {
            let requiredSpace: Int64 = 100 * 1024 * 1024  // 100 MB
            return freeSpace.int64Value > requiredSpace
        }
    } catch {
        print("Error checking disk space: \(error)")
    }

    return false
}

// Usage
if checkDiskSpace() {
    saveFile()  // Approved reason E174.1: Check before writing
} else {
    showInsufficientSpaceAlert()
}

Example: UserDefaults API

Approved reasons:

• CA92.1: Access info stored by app (settings, preferences)
• 1C8F.1: Access info stored by App Group
• C56D.1: Access info stored by App Clips
• AC6B.1: Third-party SDK accessing its own defaults

Declaration:

<dict>
    <key>NSPrivacyAccessedAPIType</key>
    <string>NSPrivacyAccessedAPICategoryUserDefaults</string>

    <key>NSPrivacyAccessedAPITypeReasons</key>
    <array>
        <string>CA92.1</string>
    </array>
</dict>

Feedback for Missing Reasons

If your use case isn't covered, use Apple's feedback form: https://developer.apple.com/documentation/bundleresources/privacy_manifest_files/describing_use_of_required_reason_api

---

Part 6: Privacy Nutrition Labels

Data Types and Categories

Identifiers:

• User ID
• Device ID

Contact Info:

• Name
• Email address
• Phone number
• Physical address

Location:

• Precise location
• Coarse location

User Content:

• Photos or videos
• Audio data
• Gameplay content
• Customer support messages

Browsing History Search History Financial Info Health & Fitness Contacts Sensitive Info (racial/ethnic data, political opinions, religious beliefs)

Data Use Purposes

• App functionality - Necessary for core features
• Analytics - Understanding app usage
• Product personalization - Customizing experience
• Developer advertising - Ads for your own products
• Third-party advertising - Ads from other companies

Linked vs Not Linked

Linked to user:

• Data connected to user identity (name, email, user ID)
• Example: User profile information

Not linked to user:

• Data not connected to identity (anonymous analytics)
• Example: Aggregate crash reports

Tracking Disclosure

Data is used for tracking if:

• Combined with data from other apps/websites
• Shared with data brokers
• Used for targeted advertising based on cross-app behavior

Example declaration:

Data Type: Email Address
Purpose: App Functionality
Linked to User: Yes
Used for Tracking: No

---

Part 7: Xcode Privacy Report

Generating Report

1. Archive app: Product → Archive
2. Xcode Organizer → Select archive
3. Right-click → "Generate Privacy Report"
4. PDF created showing aggregated privacy data

What's included:

• All privacy manifests (app + third-party SDKs)
• Collected data types
• Tracking declaration
• Required Reason APIs

Reviewing Report

Check for:

• Unexpected data collection (SDK collecting data you didn't know about)
• Missing Required Reason declarations
• Tracking domain discrepancies
• Third-party SDKs without privacy manifests

Use for: Completing Privacy Nutrition Labels in App Store Connect

---

Part 8: Permission Types

Camera

import AVFoundation

AVCaptureDevice.requestAccess(for: .video) { granted in
    // Handle response
}

// Info.plist
<key>NSCameraUsageDescription</key>
<string>Take photos of your meals to track nutrition</string>

Microphone

AVAudioSession.sharedInstance().requestRecordPermission { granted in
    // Handle response
}

<key>NSMicrophoneUsageDescription</key>
<string>Record voice memos</string>

Location

import CoreLocation

class LocationManager: NSObject, CLLocationManagerDelegate {
    let manager = CLLocationManager()

    func requestPermission() {
        manager.delegate = self

        // Choose one:
        manager.requestWhenInUseAuthorization()  // Only when app is open
        // OR
        manager.requestAlwaysAuthorization()     // Background location
    }
}

// Info.plist (iOS 14+)
<key>NSLocationWhenInUseUsageDescription</key>
<string>Show nearby restaurants</string>

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Track your runs even when the app is in the background</string>

Photos

import Photos

PHPhotoLibrary.requestAuthorization(for: .readWrite) { status in
    switch status {
    case .authorized, .limited:  // .limited = selected photos only
        // Access granted
    case .denied, .restricted:
        // Access denied
    @unknown default:
        break
    }
}

<key>NSPhotoLibraryUsageDescription</key>
<string>Save and share your workout photos</string>

Contacts

import Contacts

CNContactStore().requestAccess(for: .contacts) { granted, error in
    // Handle response
}

<key>NSContactsUsageDescription</key>
<string>Invite friends to join you</string>

Notifications

import UserNotifications

UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .sound, .badge]) { granted, error in
    // Handle response
}

// No Info.plist entry required

---

Part 9: Privacy-First Design Patterns

Data Minimization

Principle: Only collect data you actually need

// ❌ Bad - collecting unnecessary data
struct UserProfile {
    let name: String
    let email: String
    let phone: String           // Do you really need this?
    let dateOfBirth: Date       // Or this?
    let socialSecurityNumber: String  // Definitely not
}

// ✅ Good - minimal data collection
struct UserProfile {
    let name: String
    let email: String
    // That's it
}

On-Device Processing

Principle: Process data locally when possible

// ✅ Good - on-device ML
import Vision

func analyzePhoto(_ image: UIImage) {
    let request = VNClassifyImageRequest { request, error in
        // Results stay on device
        let classifications = request.results as? [VNClassificationObservation]
        self.displayResults(classifications)
    }

    let handler = VNImageRequestHandler(cgImage: image.cgImage!)
    try? handler.perform([request])
    // No network request, no data leaving device
}

Explaining Value Exchange

Principle: Be transparent about why you need data

// ✅ Good - clear value proposition
"We use your location to show nearby restaurants and save your favorite places. Your location is never shared with third parties."

Transparent Data Practices

Principle: Make privacy information easily accessible

// Add Privacy Policy link in Settings screen
struct SettingsView: View {
    var body: some View {
        List {
            Section("About") {
                Link("Privacy Policy", destination: URL(string: "https://example.com/privacy")!)
                Link("Data We Collect", destination: URL(string: "https://example.com/data")!)
            }
        }
    }
}

---

Common Mistakes

Requesting permissions at launch

// ❌ Wrong
func application(_ application: UIApplication,
                didFinishLaunchingWithOptions...) -> Bool {
    requestAllPermissions()  // User has no context
    return true
}

// ✅ Correct
@objc func cameraButtonTapped() {
    requestCameraPermission()  // Just-in-time
}

No explanation before permission dialog

// ❌ Wrong
AVCaptureDevice.requestAccess(for: .video) { granted in }

// ✅ Correct
showCameraEducation {
    AVCaptureDevice.requestAccess(for: .video) { granted in }
}

Not handling denial gracefully

// ❌ Wrong - dead end
if !granted {
    return  // User stuck
}

// ✅ Correct - offer alternative
if !granted {
    showSettingsPrompt()  // Path forward
}

Missing tracking domains

// ❌ Wrong - privacy manifest declares tracking but no domains
<key>NSPrivacyTracking</key>
<true/>
<!-- Missing NSPrivacyTrackingDomains -->

// ✅ Correct
<key>NSPrivacyTrackingDomains</key>
<array>
    <string>tracking.example.com</string>
</array>

Incomplete Required Reason declarations

// ❌ Wrong - using UserDefaults without declaring it
UserDefaults.standard.set(value, forKey: "setting")
// Privacy manifest has no NSPrivacyAccessedAPITypes entry

// ✅ Correct - declared in manifest with approved reason

---

Timeline

Date	Milestone
WWDC 2023	Privacy manifests announced
Fall 2023	Informational emails begin
Spring 2024	App Review enforcement begins
May 1, 2024	Privacy manifests required for apps with privacy-impacting SDKs

---

Resources

WWDC: 2023-10060, 2023-10053

Docs: /bundleresources/privacy_manifest_files, /bundleresources/describing-use-of-required-reason-api, /app-store/app-privacy-details, /app-store/user-privacy-and-data-use

Skills: axiom-app-intents-ref, axiom-cloudkit-ref, axiom-storage