Capacitor App Tracking Transparency Plugin

Capacitor plugin for the App Tracking Transparency framework.

Features

The Capacitor App Tracking Transparency plugin is one of the most complete tracking authorization solutions for Capacitor apps. Here are some of the key features:

• 🔒 Authorization status: Read the current tracking authorization status.
• 🙋 Permission request: Present the system tracking authorization prompt.
• 🆔 Advertising identifier: Read the advertising identifier (IDFA) when authorized.
• 🤝 Compatibility: Works alongside the Permissions plugin.
• 📦 CocoaPods & SPM: Supports CocoaPods and Swift Package Manager for iOS.
• 🔁 Up-to-date: Always supports the latest Capacitor version.

Missing a feature? Just open an issue and we'll take a look!

Use Cases

The App Tracking Transparency plugin is typically used whenever an iOS app collects data for tracking purposes, for example:

• Personalized ads: Request tracking permission before serving personalized ads to the user.
• Ad attribution: Read the advertising identifier (IDFA) to attribute app installs to ad campaigns once the user has authorized tracking.
• Conditional tracking: Check the current tracking authorization status and only enable tracking-related features when the status is authorized.
• App Review compliance: Present the system tracking authorization prompt as required by Apple for any app that tracks users.

Compatibility

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

npx skills add capawesome-team/skills --skill capacitor-plugins

Then use the following prompt:

 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-app-tracking-transparency` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capawesome/capacitor-app-tracking-transparency
npx cap sync

This plugin is only available on iOS. On Android and Web, all methods reject as unimplemented.

iOS

Privacy Descriptions

The NSUserTrackingUsageDescription key must be added to the Info.plist file of your app. Otherwise, the requestPermission(...) method will reject with an error.

<key>NSUserTrackingUsageDescription</key>
<string>Your data will be used to deliver personalized ads to you.</string>

The purpose string must clearly explain why your app is requesting permission to track the user. See the Apple documentation for more information.

Configuration

No configuration required for this plugin.

Usage

The following examples show how to check the tracking authorization status, request tracking permission, and read the advertising identifier.

Check the tracking authorization status

Read the current tracking authorization status, for example to decide whether tracking-related features should be enabled. Only available on iOS:

import { AppTrackingTransparency } from '@capawesome/capacitor-app-tracking-transparency';

const getStatus = async () => {
  const { status } = await AppTrackingTransparency.getStatus();
  return status;
};

Request tracking permission

Present the system tracking authorization prompt. The prompt is only shown once per install while the status is notDetermined; afterwards, the method resolves with the existing status. Only available on iOS:

import { AppTrackingTransparency } from '@capawesome/capacitor-app-tracking-transparency';

const requestPermission = async () => {
  const { status } = await AppTrackingTransparency.requestPermission();
  return status;
};

Read the advertising identifier

Read the advertising identifier (IDFA) of the device. It is only available if the tracking authorization status is authorized; otherwise, null is returned. Only available on iOS:

import { AppTrackingTransparency } from '@capawesome/capacitor-app-tracking-transparency';

const getAdvertisingIdentifier = async () => {
  const { advertisingIdentifier } =
    await AppTrackingTransparency.getAdvertisingIdentifier();
  return advertisingIdentifier;
};

API

• getAdvertisingIdentifier()
• getStatus()
• requestPermission()
• Interfaces
• Type Aliases

getAdvertisingIdentifier()

getAdvertisingIdentifier() => Promise<GetAdvertisingIdentifierResult>

Get the advertising identifier (IDFA) of the device.

The advertising identifier is only available if the tracking authorization status is authorized. Otherwise, null is returned.

Note: The iOS Simulator always returns null, even if the tracking authorization status is authorized. Use a real device to test this method.

Only available on iOS.

Returns: Promise<GetAdvertisingIdentifierResult>

Since: 0.1.0

getStatus()

getStatus() => Promise<GetStatusResult>

Get the current tracking authorization status.

Only available on iOS.

Returns: Promise<GetStatusResult>

Since: 0.1.0

requestPermission()

requestPermission() => Promise<RequestPermissionResult>

Request permission to track the user.

This will present the system tracking authorization prompt if the status has not been determined yet. The prompt is only shown once per install.

The NSUserTrackingUsageDescription key must be added to the Info.plist file of your app.

Only available on iOS.

Returns: Promise<RequestPermissionResult>

Since: 0.1.0

Interfaces

GetAdvertisingIdentifierResult

GetStatusResult

RequestPermissionResult

Type Aliases

TrackingStatus

The tracking authorization status.

• authorized: The user authorized access to app-related data for tracking.
• denied: The user denied access to app-related data for tracking.
• notDetermined: The user has not yet received a tracking authorization request.
• restricted: Tracking authorization is restricted and cannot be changed by the user.

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

App Review Guidance

Apple requires that any app that tracks users requests permission via the App Tracking Transparency framework. Keep the following guidelines in mind to avoid App Review rejections:

• Prompt timing: Call requestPermission(...) only when the user is in a context where tracking makes sense. The system prompt is only shown once per install while the status is notDetermined. Calling the method again afterwards resolves with the existing status without showing the prompt.
• Purpose string: The NSUserTrackingUsageDescription purpose string must accurately describe how the collected data is used. Vague or misleading descriptions are a common reason for rejection.
• Advertising identifier: The advertising identifier (IDFA) is only available while the status is authorized. In all other cases, getAdvertisingIdentifier(...) returns null.
• Simulator: The iOS Simulator never provides an advertising identifier, so getAdvertisingIdentifier(...) always returns null there, even if the status is authorized. Use a real device to test the advertising identifier.

FAQ

How is this plugin different from other similar plugins?

It wraps Apple's App Tracking Transparency framework in a small, fully typed API: read the current authorization status, present the system prompt, and read the advertising identifier (IDFA) once the user has authorized tracking. It also ships focused App Review guidance on prompt timing, purpose strings, and simulator behavior — the details that most often decide whether a tracking-enabled app is approved. It supports CocoaPods and Swift Package Manager and is actively maintained against the latest Capacitor version.

Does this plugin work on Android or Web?

No, the App Tracking Transparency framework is an iOS-only concept. The plugin is only available on iOS; on Android and Web, all methods reject as unimplemented.

Why does the requestPermission method reject with an error?

The most common reason is a missing NSUserTrackingUsageDescription key in your app's Info.plist file. This key is required for the system tracking authorization prompt and its purpose string must clearly explain why your app is requesting permission to track the user. See the Installation section for details.

Why is the tracking authorization prompt not shown?

The system prompt is only shown once per install while the tracking authorization status is notDetermined. If the user has already responded to the prompt, calling requestPermission() again resolves with the existing status without showing the prompt. To test the prompt again, reinstall the app.

Why does getAdvertisingIdentifier return null?

The advertising identifier (IDFA) is only available if the tracking authorization status is authorized; in all other cases, null is returned. Additionally, the iOS Simulator never provides an advertising identifier, even if the status is authorized, so use a real device to test this method.

Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

Related Plugins

• Permissions: Check and request device permissions with a unified API.
• Privacy Screen: Hide sensitive app content in the app switcher and block screenshots.

Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Changelog

See CHANGELOG.md.

License

See LICENSE.