capacitor-age-range

Cross-platform age range detection for Capacitor apps. Uses Google Play Age Signals on Android and Apple DeclaredAgeRange on iOS.

Why Capacitor Age Range?

A unified, free, and lightweight age range plugin:

• Cross-platform - Single API for both Android and iOS
• Privacy-preserving - No birth dates collected, only age ranges
• Regulatory compliance - Meet COPPA, KOSA, and regional age-appropriate design requirements
• Automatic mapping - Platform-specific responses mapped to a unified format
• Modern package management - Supports both Swift Package Manager (SPM) and CocoaPods
• Zero dependencies - Minimal footprint beyond platform SDKs

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/age-range/

Compatibility

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

Install

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

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-age-range` 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 @capgo/capacitor-age-range
npx cap sync

iOS Setup

Requirements

• iOS 15+ (plugin compiles and runs, returns NOT_AVAILABLE on older versions)
• iOS 26+ for actual age range functionality (DeclaredAgeRange framework)
• Xcode 26+

Entitlement

Add the com.apple.developer.declared-age-range entitlement to your app:

1. In Xcode, select your target → Signing & Capabilities
2. Click + Capability → search for Declared Age Range
3. Enable it

Or add manually to your *.entitlements file:

<key>com.apple.developer.declared-age-range</key>
<true/>

How it works

On iOS, requestAgeRange() presents a system dialog where the user (or their guardian via Family Sharing) declares their age range. The ageGates option controls the age boundaries shown in the dialog (default: [13, 16, 18]).

Android Setup

Requirements

• Android API 24+ (minSdk)
• Google Play Store installed and up to date

How it works

On Android, the plugin queries Google Play Age Signals API in the background — no user prompt is shown. The Play Store determines the user's age verification status from their Google account.

No additional permissions or manifest changes are needed.

Web

Not supported. The web implementation throws 'AgeRange does not have web implementation'.

API

requestAgeRange(options?: RequestAgeRangeOptions | undefined) => Promise<AgeRangeResult>

getPluginVersion() => Promise<{ version: string; }>

Usage

import { AgeRange } from '@capgo/capacitor-age-range';

// Request age range with default gates (13, 16, 18)
const result = await AgeRange.requestAgeRange();

switch (result.status) {
  case 'SHARING':
    console.log('Age range:', result.ageLower, '-', result.ageUpper);
    console.log('Source:', result.declarationSource);
    break;
  case 'DECLINED_SHARING':
    console.log('User declined to share age');
    break;
  case 'NOT_AVAILABLE':
    console.log('Age range API not available');
    break;
  case 'ERROR':
    console.log('Error occurred');
    break;
}

// Custom age gates (iOS only)
const result2 = await AgeRange.requestAgeRange({ ageGates: [13, 18] });

Platform Response Mapping

Android (Google Play Age Signals)

iOS (DeclaredAgeRange)