@herdwatch/cordova-plugin-app-tracking

Requests and reports iOS App Tracking Transparency authorisation.

iOS only. On any other platform, and on iOS below 14, every call resolves with STATUS_NOT_SUPPORTED rather than rejecting — a caller can treat "no prompt exists here" the same way it treats a decision.

Why this instead of an existing plugin

cordova-plugin-idfa and cordova-plugin-tracking-transparency both do this already, and both have been dormant for years (November 2023 and February 2022 respectively), with neither validated against cordova-ios 8. This is roughly fifty lines of Objective-C around one system API, so adopting a stale dependency would mean taking on maintenance of someone else's legacy for code we would end up owning anyway. The approach here is ported from cordova-plugin-idfa rather than invented.

What it deliberately does not do

It never reads the advertising identifier (IDFA). Callers want the authorisation status so they can tell an ad SDK whether tracking is permitted — the SDK reads the identifier itself. Keeping the IDFA off the bridge means one less piece of personal data passing through JavaScript.

Install

cordova plugin add @herdwatch/cordova-plugin-app-tracking

Usage

const { appTracking } = cordova.plugins;

const status = await appTracking.getStatus();
if (status === appTracking.STATUS_NOT_DETERMINED) {
  const chosen = await appTracking.requestPermission();
  // chosen === appTracking.STATUS_AUTHORIZED when the user allowed tracking
}

Constant	Value	Meaning
STATUS_NOT_DETERMINED	0	The prompt has not been answered yet — the only state that prompts
STATUS_RESTRICTED	1	Blocked by device policy; the prompt cannot be shown
STATUS_DENIED	2	The user declined
STATUS_AUTHORIZED	3	The user allowed tracking
STATUS_NOT_SUPPORTED	100	Not iOS, or iOS below 14 — this plugin's own value, not Apple's

requestPermission() only shows the system prompt while the status is STATUS_NOT_DETERMINED. Once the user has decided, iOS returns the stored status immediately and the decision can only be changed in Settings, so there is exactly one chance per install to ask.

The usage-description string

iOS terminates the app if NSUserTrackingUsageDescription is missing when the prompt is requested, so the plugin ships a generic string. Override it with the host app's own wording in config.xml:

<edit-config file="*-Info.plist" mode="merge" target="NSUserTrackingUsageDescription">
  <string>Your wording here.</string>
</edit-config>

Before shipping a build that calls this

Requesting authorisation is the point at which an app starts tracking, which has consequences outside this plugin:

• App Store privacy label. NSPrivacyTracking in the app's privacy manifest has to become true, and the App Store listing then shows a "Data Used to Track You" section. That is a public, visible change to the product page.
• Consent law. In the EU and UK, the ATT prompt satisfies Apple, not the GDPR. A separate lawful basis is needed, and the two-button system dialog is generally not accepted as GDPR consent on its own. Get this signed off before enabling the prompt, not after.