Getting Started

1. Install the package

   npm

   npm i @capgo/capacitor-app-tracking-transparency

   pnpm

   pnpm add @capgo/capacitor-app-tracking-transparency

   yarn

   yarn add @capgo/capacitor-app-tracking-transparency

   bun

   bun add @capgo/capacitor-app-tracking-transparency

2. Sync with native projects

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

iOS Setup

Add the NSUserTrackingUsageDescription key to your Info.plist file:

<key>NSUserTrackingUsageDescription</key>
<string>This identifier will be used to deliver personalized ads to you.</string>

The string should explain why you need tracking permission. This message will be displayed to users when requesting permission.

Usage

Import the plugin and use its methods to handle tracking authorization:

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

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

// Request tracking permission
const requestPermission = async () => {
  const { status } = await AppTrackingTransparency.requestPermission();
  console.log('User chose:', status);
};

API Reference

getStatus()

Gets the current tracking authorization status without prompting the user.

const { status } = await AppTrackingTransparency.getStatus();
// Returns: 'authorized' | 'denied' | 'notDetermined' | 'restricted'

requestPermission()

Requests user authorization to access app-related data for tracking. Displays the native iOS tracking permission dialog.

const { status } = await AppTrackingTransparency.requestPermission();
// Returns: 'authorized' | 'denied' | 'notDetermined' | 'restricted'

Note

This method will only show the dialog once. Subsequent calls return the stored authorization status without showing the dialog.

Complete Example

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

export class TrackingService {
  async requestTrackingIfNeeded(): Promise<boolean> {
    // Check current status first
    const { status } = await AppTrackingTransparency.getStatus();

    if (status === 'notDetermined') {
      // User hasn't been asked yet, show the dialog
      const result = await AppTrackingTransparency.requestPermission();
      return result.status === 'authorized';
    }

    return status === 'authorized';
  }

  async isTrackingAuthorized(): Promise<boolean> {
    const { status } = await AppTrackingTransparency.getStatus();
    return status === 'authorized';
  }
}

Status Values

Status	Description
authorized	User has authorized tracking
denied	User has denied tracking
notDetermined	User hasn’t been asked yet
restricted	Tracking is restricted (e.g., parental controls)

Platform Notes

iOS

• Requires iOS 14.0+
• Uses Apple’s ATTrackingManager framework
• The permission dialog is shown only once per app install

Android

• Returns authorized status automatically
• No permission dialog is shown (ATT is iOS-only)

Web

• Returns authorized status for development purposes

Best Practices

1. Request at the right time Don’t request permission on app launch. Wait until the user reaches a feature that benefits from tracking, and explain the value first.

2. Check before requesting Always check getStatus() before calling requestPermission() to avoid unnecessary API calls.

3. Handle all statuses

   const { status } = await AppTrackingTransparency.getStatus();
   switch (status) {
     case 'authorized':
       // Enable personalized features
       break;
     case 'denied':
     case 'restricted':
       // Use non-personalized alternatives
       break;
     case 'notDetermined':
       // Consider requesting permission
       break;
   }