home / skills / thebushidocollective / han / privacy-manifests

privacy-manifests skill

safe

/plugins/tools/cocoapods/skills/privacy-manifests

This skill helps you implement iOS 17 privacy manifests for CocoaPods libraries, declaring required reasons and integrating PrivacyInfo.xcprivacy for App Store

npx playbooks add skill thebushidocollective/han --skill privacy-manifests

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

11.8 KB

---
name: cocoapods-privacy-manifests
user-invocable: false
description: Use when implementing iOS 17+ privacy manifests for CocoaPods libraries. Covers PrivacyInfo.xcprivacy file creation, required reasons API declarations, and proper resource bundle integration for App Store compliance.
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Grep
  - Glob
---

# CocoaPods - Privacy Manifests

Implement iOS 17+ privacy manifests for App Store compliance and user transparency.

## What Are Privacy Manifests?

Privacy manifests (`PrivacyInfo.xcprivacy`) are XML property list files that declare:

- Data collection and usage practices
- Required Reasons API usage
- Tracking domains
- Privacy-sensitive APIs

### Why Privacy Manifests?

Starting with iOS 17 and Xcode 15, Apple requires privacy manifests for:

- Apps using privacy-sensitive APIs
- Third-party SDKs and frameworks
- Any code accessing user data

## Privacy Manifest File Format

### Basic Structure

```xml
<?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>NSPrivacyTrackingDomains</key>
    <array/>
    <key>NSPrivacyCollectedDataTypes</key>
    <array/>
    <key>NSPrivacyAccessedAPITypes</key>
    <array/>
</dict>
</plist>
```

## Including in Podspec

### Resource Bundle (Recommended)

```ruby
Pod::Spec.new do |spec|
  spec.name = 'MyLibrary'
  spec.version = '1.0.0'

  spec.source_files = 'Source/**/*.swift'

  # Include privacy manifest in resource bundle
  spec.resource_bundles = {
    'MyLibrary' => [
      'Resources/**/*.xcprivacy',
      'Resources/**/*.{png,jpg,xcassets}'
    ]
  }
end
```

### Direct Resources (Alternative)

```ruby
spec.resources = 'Resources/PrivacyInfo.xcprivacy'

# Or with glob pattern
spec.resources = 'Resources/**/*.xcprivacy'
```

### File Location

```
MyLibrary/
├── MyLibrary.podspec
├── Source/
│   └── MyLibrary/
└── Resources/
    ├── PrivacyInfo.xcprivacy  # Privacy manifest
    └── Assets.xcassets
```

## Required Reasons APIs

### Common APIs Requiring Reasons

Apple requires declarations for these privacy-sensitive APIs:

#### File Timestamp APIs

```xml
<key>NSPrivacyAccessedAPITypes</key>
<array>
    <dict>
        <key>NSPrivacyAccessedAPIType</key>
        <string>NSPrivacyAccessedAPICategoryFileTimestamp</string>
        <key>NSPrivacyAccessedAPITypeReasons</key>
        <array>
            <string>C617.1</string>
        </array>
    </dict>
</array>
```

**Reason Codes:**

- `C617.1`: Display timestamps to user
- `0A2A.1`: Access timestamps of files in app container
- `3B52.1`: Access timestamps for app functionality
- `DDA9.1`: Timestamp access for debugging

#### User Defaults APIs

```xml
<dict>
    <key>NSPrivacyAccessedAPIType</key>
    <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
    <key>NSPrivacyAccessedAPITypeReasons</key>
    <array>
        <string>CA92.1</string>
    </array>
</dict>
```

**Reason Codes:**

- `CA92.1`: Access user defaults in same app group
- `1C8F.1`: Access user defaults for app functionality
- `C56D.1`: SDK-specific configuration preferences
- `AC6B.1`: Third-party SDK functionality

#### System Boot Time APIs

```xml
<dict>
    <key>NSPrivacyAccessedAPIType</key>
    <string>NSPrivacyAccessedAPICategorySystemBootTime</string>
    <key>NSPrivacyAccessedAPITypeReasons</key>
    <array>
        <string>35F9.1</string>
    </array>
</dict>
```

**Reason Codes:**

- `35F9.1`: Measure time elapsed for app functionality
- `8FFB.1`: Calculate absolute timestamp
- `3D61.1`: Measure time for performance testing

#### Disk Space APIs

```xml
<dict>
    <key>NSPrivacyAccessedAPIType</key>
    <string>NSPrivacyAccessedAPICategoryDiskSpace</string>
    <key>NSPrivacyAccessedAPITypeReasons</key>
    <array>
        <string>85F4.1</string>
    </array>
</dict>
```

**Reason Codes:**

- `85F4.1`: Display disk space to user
- `E174.1`: Check disk space before file operations
- `7D9E.1`: Health/fitness app disk space
- `B728.1`: User-initiated file management

## Data Collection

### Declaring Collected Data

```xml
<key>NSPrivacyCollectedDataTypes</key>
<array>
    <dict>
        <key>NSPrivacyCollectedDataType</key>
        <string>NSPrivacyCollectedDataTypeEmailAddress</string>
        <key>NSPrivacyCollectedDataTypeLinked</key>
        <true/>
        <key>NSPrivacyCollectedDataTypeTracking</key>
        <false/>
        <key>NSPrivacyCollectedDataTypePurposes</key>
        <array>
            <string>NSPrivacyCollectedDataTypePurposeAppFunctionality</string>
        </array>
    </dict>
</array>
```

### Common Data Types

- `NSPrivacyCollectedDataTypeEmailAddress`
- `NSPrivacyCollectedDataTypeName`
- `NSPrivacyCollectedDataTypePhoneNumber`
- `NSPrivacyCollectedDataTypeDeviceID`
- `NSPrivacyCollectedDataTypeUserID`
- `NSPrivacyCollectedDataTypePreciseLocation`
- `NSPrivacyCollectedDataTypeCoarseLocation`
- `NSPrivacyCollectedDataTypeSearchHistory`
- `NSPrivacyCollectedDataTypeBrowsingHistory`

### Collection Purposes

- `NSPrivacyCollectedDataTypePurposeThirdPartyAdvertising`
- `NSPrivacyCollectedDataTypePurposeAppFunctionality`
- `NSPrivacyCollectedDataTypePurposeAnalytics`
- `NSPrivacyCollectedDataTypePurposeProductPersonalization`
- `NSPrivacyCollectedDataTypePurposeOther`

## Tracking Configuration

### No Tracking

```xml
<key>NSPrivacyTracking</key>
<false/>
<key>NSPrivacyTrackingDomains</key>
<array/>
```

### With Tracking

```xml
<key>NSPrivacyTracking</key>
<true/>
<key>NSPrivacyTrackingDomains</key>
<array>
    <string>analytics.example.com</string>
    <string>tracking.example.com</string>
</array>
```

## Complete Example

### Networking SDK Privacy Manifest

```xml
<?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>
    <!-- No tracking -->
    <key>NSPrivacyTracking</key>
    <false/>
    <key>NSPrivacyTrackingDomains</key>
    <array/>

    <!-- Data collection -->
    <key>NSPrivacyCollectedDataTypes</key>
    <array>
        <dict>
            <key>NSPrivacyCollectedDataType</key>
            <string>NSPrivacyCollectedDataTypeUserID</string>
            <key>NSPrivacyCollectedDataTypeLinked</key>
            <true/>
            <key>NSPrivacyCollectedDataTypeTracking</key>
            <false/>
            <key>NSPrivacyCollectedDataTypePurposes</key>
            <array>
                <string>NSPrivacyCollectedDataTypePurposeAppFunctionality</string>
            </array>
        </dict>
    </array>

    <!-- Required Reasons APIs -->
    <key>NSPrivacyAccessedAPITypes</key>
    <array>
        <!-- User Defaults for caching -->
        <dict>
            <key>NSPrivacyAccessedAPIType</key>
            <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
            <key>NSPrivacyAccessedAPITypeReasons</key>
            <array>
                <string>CA92.1</string>
            </array>
        </dict>

        <!-- File timestamps for cache validation -->
        <dict>
            <key>NSPrivacyAccessedAPIType</key>
            <string>NSPrivacyAccessedAPICategoryFileTimestamp</string>
            <key>NSPrivacyAccessedAPITypeReasons</key>
            <array>
                <string>3B52.1</string>
            </array>
        </dict>
    </array>
</dict>
</plist>
```

### Analytics SDK Privacy Manifest

```xml
<?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>
    <!-- Tracking enabled -->
    <key>NSPrivacyTracking</key>
    <true/>
    <key>NSPrivacyTrackingDomains</key>
    <array>
        <string>analytics.myservice.com</string>
    </array>

    <!-- Data collection -->
    <key>NSPrivacyCollectedDataTypes</key>
    <array>
        <dict>
            <key>NSPrivacyCollectedDataType</key>
            <string>NSPrivacyCollectedDataTypeDeviceID</string>
            <key>NSPrivacyCollectedDataTypeLinked</key>
            <true/>
            <key>NSPrivacyCollectedDataTypeTracking</key>
            <true/>
            <key>NSPrivacyCollectedDataTypePurposes</key>
            <array>
                <string>NSPrivacyCollectedDataTypePurposeAnalytics</string>
            </array>
        </dict>
    </array>

    <!-- Required Reasons APIs -->
    <key>NSPrivacyAccessedAPITypes</key>
    <array>
        <dict>
            <key>NSPrivacyAccessedAPIType</key>
            <string>NSPrivacyAccessedAPICategorySystemBootTime</string>
            <key>NSPrivacyAccessedAPITypeReasons</key>
            <array>
                <string>35F9.1</string>
            </array>
        </dict>
    </array>
</dict>
</plist>
```

## CocoaPods Integration

### Podspec Configuration

```ruby
Pod::Spec.new do |spec|
  spec.name = 'MyAnalyticsSDK'
  spec.version = '1.0.0'

  spec.ios.deployment_target = '13.0'

  spec.source_files = 'Source/**/*.swift'

  # Include privacy manifest
  spec.resource_bundles = {
    'MyAnalyticsSDK' => [
      'Resources/PrivacyInfo.xcprivacy'
    ]
  }

  # Platform-specific privacy manifests
  spec.ios.resource_bundles = {
    'MyAnalyticsSDK_iOS' => ['Resources/iOS/PrivacyInfo.xcprivacy']
  }

  spec.osx.resource_bundles = {
    'MyAnalyticsSDK_macOS' => ['Resources/macOS/PrivacyInfo.xcprivacy']
  }
end
```

## Validation

### Check Privacy Manifest

```bash
# Lint with privacy manifest
pod lib lint

# Validate privacy manifest is included
pod lib lint --verbose | grep -i privacy
```

### Xcode Validation

1. Build your library in Xcode
2. Open **Report Navigator**
3. Check for privacy warnings
4. Verify privacy manifest in bundle

### App Store Validation

```bash
# Generate .xcarchive
xcodebuild archive -workspace MyApp.xcworkspace -scheme MyApp

# Validate before submission
xcodebuild -exportArchive -archivePath MyApp.xcarchive -exportPath MyApp.ipa -exportOptionsPlist ExportOptions.plist
```

## Best Practices

### Minimal Disclosure

```xml
<!-- Only declare what you actually use -->
<key>NSPrivacyCollectedDataTypes</key>
<array>
    <!-- Only include if you actually collect this data -->
</array>
```

### Accurate Reasons

```xml
<!-- Use correct reason codes -->
<key>NSPrivacyAccessedAPITypeReasons</key>
<array>
    <string>CA92.1</string>  <!-- Must match actual usage -->
</array>
```

### Regular Updates

```ruby
# Update privacy manifest when adding new APIs
spec.version = '1.1.0'  # Bump version

# Update PrivacyInfo.xcprivacy with new declarations
```

## Anti-Patterns

### Don't

❌ Omit privacy manifest for iOS 17+ apps

```ruby
# Missing privacy manifest - App Store rejection risk
spec.resource_bundles = {
  'MyLibrary' => ['Resources/**/*.png']
  # No PrivacyInfo.xcprivacy
}
```

❌ Use incorrect reason codes

```xml
<string>WRONG.1</string>  <!-- Invalid code -->
```

❌ Declare tracking without domains

```xml
<key>NSPrivacyTracking</key>
<true/>
<key>NSPrivacyTrackingDomains</key>
<array/>  <!-- Empty - inconsistent -->
```

### Do

✅ Include privacy manifest for all iOS SDKs

```ruby
spec.resource_bundles = {
  'MyLibrary' => ['Resources/PrivacyInfo.xcprivacy']
}
```

✅ Use accurate reason codes

```xml
<string>CA92.1</string>  <!-- Valid, matches usage -->
```

✅ Be truthful about tracking

```xml
<key>NSPrivacyTracking</key>
<true/>
<key>NSPrivacyTrackingDomains</key>
<array>
    <string>analytics.example.com</string>
</array>
```

## Resources

- [Apple Privacy Manifest Documentation](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files)
- [Required Reasons API Reference](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files/describing_use_of_required_reason_api)
- [App Privacy Details](https://developer.apple.com/app-store/app-privacy-details/)

## Related Skills

- cocoapods-podspec-fundamentals
- cocoapods-subspecs-organization
- cocoapods-publishing-workflow

Overview

This skill helps library authors implement iOS 17+ privacy manifests for CocoaPods libraries to satisfy App Store requirements and increase user transparency. It guides creation of PrivacyInfo.xcprivacy, declares Required Reasons APIs and collected data types, and shows how to package manifests into podspec resource bundles for proper integration. The content focuses on practical compliance steps and real-world examples for networking, analytics, and utility SDKs.

How this skill works

The skill inspects the privacy-sensitive APIs used by your library and maps them to the appropriate NSPrivacyAccessedAPITypes and reason codes. It provides ready-to-use XML snippets for PrivacyInfo.xcprivacy, examples for declaring collected data types and tracking domains, and podspec snippets to include the manifest in resource bundles or as resources. It also outlines validation steps using pod lib lint, Xcode build reports, and archive/export checks before submission to the App Store.

When to use it

You publish an iOS SDK or CocoaPod that accesses user or device data and targets iOS 17+.
You add privacy-sensitive APIs (file timestamps, user defaults, disk space, boot time) to your library.
You need to include privacy manifests in your podspec for App Store compliance.
You maintain an analytics or networking SDK that may track domains or collect device identifiers.
You want to reduce App Store review rejections by pre-declaring reasons and data collection.

Best practices

Include only the data types and API reasons you actually use—minimal, accurate declarations reduce rejection risk.
Package PrivacyInfo.xcprivacy inside a resource bundle in the podspec to ensure Xcode picks it up reliably.
Use the official reason codes that match your API usage and update them when adding or removing features.
Declare tracking true only if you list tracking domains; do not leave tracking enabled with an empty domain list.
Run pod lib lint and verify Xcode build reports to catch privacy warnings early.

Example use cases

Networking SDK: declare UserID collection and file timestamp reasons for cache validation; no tracking domains.
Analytics SDK: declare DeviceID as tracking, list analytics endpoints, and include system boot time reason for timestamping events.
Utility SDK: declare UserDefaults access reason codes for configuration and include PrivacyInfo.xcprivacy in resource_bundles.
Multi-platform Podspec: provide platform-specific PrivacyInfo.xcprivacy files via ios.resource_bundles and osx.resource_bundles for correct packaging.

FAQ

Do I always need a privacy manifest for a CocoaPod?

If your code or bundled SDK accesses privacy-sensitive APIs or user data on iOS 17+, include a privacy manifest. Omitting it risks App Store rejection.

Where should PrivacyInfo.xcprivacy live in my pod?

Place it under Resources/ (or platform subfolders) and include it in spec.resource_bundles or spec.resources so it is packaged into the framework bundle.