# 26. App Tracking Transparency (ATT)

meta:
  id: ios-production-26
  feature: ios-production
  priority: P1
  depends_on: []
  tags: [compliance, privacy, app-store, production]

objective:
- Implement App Tracking Transparency to comply with iOS privacy requirements for analytics and advertising

deliverables:
- ATT permission request
- Analytics gated behind ATT consent
- Tracking description in Info.plist
- Fallback for denied tracking

steps:
1. Add ATT framework:
   - Import AppTrackingTransparency
   - Add NSUserTrackingUsageDescription to Info.plist
   - Description: "Your data will be used to improve app experience and measure marketing effectiveness"
2. Implement permission request:
   - Request tracking authorization on first launch (after onboarding)
   - Show explanation before system dialog
   - Handle all authorization states:
     - .notDetermined → request permission
     - .restricted → disable tracking
     - .denied → disable tracking
     - .authorized → enable tracking
3. Gate analytics behind ATT:
   - Check tracking status before initializing analytics
   - If denied: use anonymous analytics only (no IDFA)
   - If authorized: full analytics with IDFA
   - Respect user's choice across app sessions
4. Update third-party SDKs:
   - Configure Firebase Analytics to respect ATT
   - Configure PostHog/Plausible to respect ATT
   - Disable ad network tracking if denied
5. Handle state changes:
   - Monitor for settings changes
   - Update tracking status if user changes in Settings
   - Re-initialize analytics accordingly
6. Add UI for tracking preferences:
   - Settings toggle for analytics (if user previously denied)
   - Explanation of what data is collected
   - Link to system Settings for ATT changes

tests:
- Unit: Test ATT status handling
- Integration: Test analytics initialization gating
- Device: Test permission flow on physical device

acceptance_criteria:
- ATT permission requested after onboarding
- System dialog shows with accurate description
- Analytics initialize only after authorized or denied
- If denied: no IDFA collection, minimal anonymous analytics
- If authorized: full analytics collection
- Third-party SDKs configured to respect ATT
- Settings UI allows users to change preference
- App complies with Apple's ATT guidelines
- No tracking before permission granted
- Unit tests covering all authorization states

validation:
- Fresh install → onboarding → ATT dialog appears
- Deny tracking → analytics uses anonymous mode
- Authorize tracking → full analytics active
- Change in Settings → app respects new choice
- Check Info.plist → NSUserTrackingUsageDescription present

notes:
- ATT is required if app collects IDFA or shares data for tracking
- If only using first-party analytics, ATT may not be required
- Be honest in description — Apple reviews these carefully
- Consider making analytics fully anonymous to avoid ATT entirely