capacitor-plugin-apptrackingios

capacitor-plugin-apptrackingios

A Capacitor plugin for handling App Tracking Transparency on iOS.

Install

npm install capacitor-plugin-apptrackingios
npx cap sync

iOS Setup

Configure Info.plist

Add the NSUserTrackingUsageDescription key to your app's Info.plist file with a description of why you're requesting tracking authorization:

<key>NSUserTrackingUsageDescription</key>
<string>We use tracking data to provide personalized ads and improve your experience.</string>

API

• getStatus()
• requestPermission()
• Type Aliases

App Tracking Transparency plugin for Capacitor

getStatus()

getStatus() => any

Get the current tracking authorization status.

On iOS 14+, this returns the current App Tracking Transparency authorization status. On iOS versions below 14, this will always return 'authorized'. On web platforms, this will always return 'authorized'.

Returns: any

Since: 1.0.0

requestPermission()

requestPermission() => any

Request tracking authorization from the user.

On iOS 14+, this will prompt the user with the App Tracking Transparency permission dialog. On iOS versions below 14, this will always return 'authorized' without showing a prompt. On web platforms, this will always return 'authorized' without showing a prompt.

Note: This plugin includes a workaround for a bug in iOS 17.4+ where the tracking authorization status may incorrectly return 'denied' when it should be 'notDetermined'.

Returns: any

Since: 1.0.0

Type Aliases

TrackingStatus

Possible tracking authorization status values

'notDetermined' | 'restricted' | 'denied' | 'authorized'

Usage

import { AppTrackingPlugin } from 'capacitor-plugin-apptrackingios';

// Check current status
const checkStatus = async () => {
  const { status } = await AppTrackingPlugin.getStatus();
  console.log('Current tracking status:', status);
  return status;
};

// Request permission
const requestPermission = async () => {
  const { status } = await AppTrackingPlugin.requestPermission();
  console.log('Tracking permission status:', status);
  return status;
};

// Example usage in a component
const initializeTracking = async () => {
  const currentStatus = await checkStatus();
  
  if (currentStatus === 'notDetermined') {
    // Only request if not determined yet
    const newStatus = await requestPermission();
    // Handle the user's choice
    if (newStatus === 'authorized') {
      // User allowed tracking
      console.log('User allowed tracking');
    } else {
      // User denied tracking
      console.log('User denied tracking');
    }
  }
};

iOS 17.4+ Bug Handling

This plugin includes a workaround for a bug in iOS 17.4+ where the tracking authorization status may incorrectly return 'denied' when it should be 'notDetermined'. The plugin automatically detects this condition and handles it appropriately.

License

MIT