Ask the operating system for the user's age range instead of collecting birthdates: Google Play Age Signals on Android and Apple Declared Age Range on iOS. Helps apps meet age assurance rules with one call.
Capgo: push fixes to your Capacitor users in minutes, build signed iOS and Android apps without a Mac, and roll back in one click.
14-day unlimited free trial. No credit card required
🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use
@capgo/capacitor-age-rangein your Capacitor app:npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-age-range to my Capacitor app and wire it up." Agent setup guides · Hosted MCP
We build, improve and fix our plugins with heavy use of AI, so issues usually get fixed in under a day and pull requests get feedback the same day. A human still reviews, tests and merges 50+ pull requests daily.
- Most plugin issues get a fix pull request the same day, often within a couple of hours, and are usually resolved in one to two days.
- Every pull request goes through our AI review system, usually within minutes.
- Our AI pre-checks tests, code review, conventions and security, then a human reviews, tests and merges.
- A human, Martin, reviews, tests and merges 50+ pull requests every day.
- In the last 90 days, 95% of plugin issues were resolved.
Learn more about how we build with AI
- One call:
requestAgeRange()returns the user's age range through the platform API. - Android: uses the Google Play Age Signals library.
- iOS: uses Apple's
DeclaredAgeRangeframework. - Privacy friendly: the app receives an age range from the OS, not a birthdate.
- Platforms: iOS and Android. Not available on web (
requestAgeRange()throws).
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
The most complete doc is available here: https://capgo.app/docs/plugins/age-range/
| Plugin version | Capacitor compatibility | Maintained |
|---|---|---|
| v8.*.* | v8.*.* | ✅ |
| v7.*.* | v7.*.* | On demand |
| v6.*.* | v6.*.* | ❌ |
| v5.*.* | v5.*.* | ❌ |
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.
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-pluginsThen 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 15+ (plugin compiles and runs, returns
NOT_AVAILABLEon older versions) - iOS 26+ for actual age range functionality (DeclaredAgeRange framework)
- Xcode 26+
requestAgeRange() needs this capability signed into the iOS app. Edit two files, then enable it on the App ID.
Paste these two lines inside the existing <dict> (keep keys you already have, such as aps-environment):
<key>com.apple.developer.declared-age-range</key>
<true/>If that file does not exist, create ios/App/App/App.entitlements with this exact content:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>com.apple.developer.declared-age-range</key>
<true/>
</dict>
</plist>The entitlements file is ignored until this line is on the App target for both Debug and Release. Search the file for the two App-target buildSettings blocks that contain PRODUCT_BUNDLE_IDENTIFIER (not the project-level configs) and add:
CODE_SIGN_ENTITLEMENTS = App/App.entitlements;
It should sit next to the other signing keys, for example:
CODE_SIGN_ENTITLEMENTS = App/App.entitlements;
CODE_SIGN_STYLE = Automatic;
Xcode UI does the same two files: Target → Signing & Capabilities → + Capability → Declared Age Range.
- Open Identifiers → your App ID → enable Declared Age Range.
- Regenerate provisioning profiles, then archive again.
Without steps 1 to 3, in-app requestAgeRange() fails. This entitlement does not control App Store download of 18+ apps in Australia, Brazil, and Singapore, Apple performs that adult confirmation automatically from the listing age rating.
Verify before shipping:
npx @capgo/cli@latest build prescanThe check id is ios/entitlements-declared-age-range.
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 API 24+ (minSdk)
- Google Play Store installed and up to date
On Android, the plugin uses Google Play Age Signals API. The default dependency is com.google.android.play:age-signals:0.0.6 (set androidPlayAgeSignalsVersion in the app's variables.gradle to override). The plugin compiles against 0.0.4 or later. Play Age Signals 0.0.2 and 0.0.3 can no longer be forced on this release because those AARs lack the types used for mapping and access flows.
By default the plugin calls checkAgeSignals() only (androidAgeSignalsAccess: 'never'), which does not show Google's in-app sharing prompt.
For mandatory-sharing regions or when you want the Play Store sharing UI, pass androidAgeSignalsAccess: 'always' or 'whenMandatory'. The whenMandatory mode calls getApplicableAgeFeatures() via reflection when Play Age Signals 0.0.6+ is on the classpath; with 0.0.4 to 0.0.5, or when the call fails, it falls back to checkAgeSignals() only. Unknown androidAgeSignalsAccess values are logged and treated as never. See Request age signals.
No additional permissions or manifest changes are needed.
Not supported. The web implementation throws 'AgeRange does not have web implementation'.
Cross-platform age range detection plugin.
Uses Google Play Age Signals on Android and Apple DeclaredAgeRange on iOS.
requestAgeRange(options?: RequestAgeRangeOptions | undefined) => Promise<AgeRangeResult>Request the user's age range.
On Android: queries Google Play Age Signals API. By default no in-app prompt is shown;
set androidAgeSignalsAccess to request sharing access when needed.
On iOS: presents the system DeclaredAgeRange dialog (requires iOS 26.2+).
| Param | Type | Description |
|---|---|---|
options |
RequestAgeRangeOptions |
- Configuration for the age range request |
Returns: Promise<AgeRangeResult>
Since: 8.0.0
getPluginVersion() => Promise<{ version: string; }>Get the native Capacitor plugin version.
Returns: Promise<{ version: string; }>
Since: 8.0.0
Result of the age range request.
| Prop | Type | Description | Since |
|---|---|---|---|
status |
AgeRangeStatus |
The outcome status of the age range request. | 8.0.0 |
ageLower |
number |
Inclusive lower bound of the user's age range. Present when age data is available. | 8.0.0 |
ageUpper |
number |
Inclusive upper bound of the user's age range. May be absent if the user is in the highest age bracket (e.g. 18+). | 8.0.0 |
declarationSource |
DeclarationSource |
How the age was declared/determined. On iOS: 'SELF_DECLARED' or 'GUARDIAN_DECLARED'. On Android: derived from ageRangeSource (TIER_A self-declared, TIER_B guardian-managed, TIER_C/TIER_D verified). |
8.0.0 |
androidUserStatus |
AndroidUserStatus |
Android-only. Legacy mapping from Play Age Signals 0.0.2 userStatus(). Play Age Signals 0.0.4+ removed this field. The plugin derives approximate values from ageRangeSource and significantChangeStatus for backward compatibility. Prefer those fields. |
8.0.0 |
ageRangeSource |
AndroidAgeRangeSource |
Android-only. How Google classified the shared age range (Play Age Signals 0.0.4+). | 8.3.0 |
significantChangeStatus |
AndroidSignificantChangeStatus |
Android-only. Approval status for significant account changes in applicable jurisdictions. | 8.3.0 |
significantChangeApprovalDate |
string |
Android-only. Effective date of the most recently approved significant change. | 8.3.0 |
mostRecentApprovalDate |
string |
Android-only. Alias for significantChangeApprovalDate (Play 0.0.2 field name). |
8.0.0 |
androidAgeSignalsAccessStatus |
AndroidAgeSignalsAccessStatus |
Android-only. Result of requestAgeSignalsAccess() when androidAgeSignalsAccess is not never. |
8.3.0 |
installId |
string |
Android-only. Install identifier for supervised installs in Google Play. | 8.0.0 |
Options for the age range request.
| Prop | Type | Description | Default | Since |
|---|---|---|---|---|
ageGates |
number[] |
Age thresholds for the request. On iOS: these are passed to requestAgeRange(ageGates:) as the age boundaries presented in the system dialog. Common values: [13, 16, 18]. On Android: this parameter is ignored (Play Age Signals returns predefined ranges: 0-12, 13-15, 16-17, 18+). |
[13, 16, 18] |
8.0.0 |
androidAgeSignalsAccess |
AndroidAgeSignalsAccessMode |
Android-only. Whether to call requestAgeSignalsAccess() before checkAgeSignals(). - never (default): calls checkAgeSignals() only, matching pre-0.0.4 behavior with no in-app sharing prompt. - always: always requests access first (Google may show the sharing prompt when applicable). - whenMandatory: requests access only when getApplicableAgeFeatures() reports MANDATORY_SHARING (Play Age Signals 0.0.6+ at runtime; on 0.0.4 to 0.0.5 or failure falls back to checkAgeSignals() only). Unknown values are logged on Android and treated as never. |
'never' |
8.3.0 |
Top-level status of the age range request.
'SHARING' | 'DECLINED_SHARING' | 'NOT_AVAILABLE' | 'ERROR'
How the age range was declared or determined.
'SELF_DECLARED' | 'GUARDIAN_DECLARED' | 'VERIFIED' | 'UNKNOWN'
Android-specific Google Play user status values.
'VERIFIED' | 'SUPERVISED' | 'SUPERVISED_APPROVAL_PENDING' | 'SUPERVISED_APPROVAL_DENIED' | 'UNKNOWN' | 'EMPTY'
Android-only. Play Age Signals ageRangeSource tier (API 0.0.4+).
'UNSPECIFIED' | 'TIER_A' | 'TIER_B' | 'TIER_C' | 'TIER_D'
Android-only. Play Age Signals significantChangeStatus (API 0.0.4+).
'UNSPECIFIED' | 'APPROVED' | 'PENDING' | 'DECLINED'
Android-only. Play Age Signals access status from requestAgeSignalsAccess().
'UNSPECIFIED' | 'SHARED' | 'NOT_SHARED' | 'VERIFICATION_REQUIRED'
Android-only. Controls the Play Age Signals access request flow.
'never' | 'always' | 'whenMandatory'
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] });ageRangeSource |
significantChangeStatus |
→ status |
→ declarationSource |
→ deprecated androidUserStatus |
|---|---|---|---|---|
| TIER_D / TIER_C | (any) | SHARING | VERIFIED | VERIFIED |
| TIER_B | PENDING | SHARING | GUARDIAN_DECLARED | SUPERVISED_APPROVAL_PENDING |
| TIER_B | DECLINED | SHARING | GUARDIAN_DECLARED | SUPERVISED_APPROVAL_DENIED |
| TIER_B | other / null | SHARING | GUARDIAN_DECLARED | SUPERVISED |
| TIER_A | (any) | SHARING | SELF_DECLARED | UNKNOWN (self-declared, not verified) |
| null / UNSPECIFIED | - | DECLINED_SHARING | - | UNKNOWN |
When androidAgeSignalsAccess is not never, requestAgeSignalsAccess() may return NOT_SHARED (DECLINED_SHARING) or VERIFICATION_REQUIRED (NOT_AVAILABLE plus androidAgeSignalsAccessStatus).
| iOS Response | → status | → declarationSource |
|---|---|---|
| .sharing (selfDeclared) | SHARING | SELF_DECLARED |
| .sharing (guardianDeclared) | SHARING | GUARDIAN_DECLARED |
| .declinedSharing | DECLINED_SHARING | - |
