react-native-age-declaration

A React Native library to access platform age verification APIs:

• iOS: Apple's Declared Age Range API (iOS 16.0+)
• Android: Google Play's Age Signals API (Android 15+)

This library provides a unified interface for both platforms, making it easy to verify user age ranges in your React Native applications.

🚀 Features

• ✅ Cross-platform: Works on both iOS and Android
• ✅ Type-safe: Written in TypeScript with full type definitions
• ✅ Expo compatible: Works with both Expo and bare React Native projects
• ✅ Simple API: Easy-to-use interface with promises
• ✅ Zero dependencies: No additional npm packages required
• ✅ Production ready: Built with standard React Native modules (no experimental dependencies)

📱 Platform Requirements

iOS

• iOS 26.0 or later
• Xcode 16.0 or later (with iOS 26 SDK)
• Uses Apple's DeclaredAgeRange framework and AgeRangeService API
• Requires the entitlement: com.apple.developer.declared-age-range

Android

• Android 15+ (API level 35+)
• Google Play Services
• The API requires the device to have Google Play installed

📦 Installation

npm install react-native-age-declaration
# or
yarn add react-native-age-declaration

iOS Setup

1. Install pods:

cd ios && pod install

2. Add the age range entitlement to your app.config.js or app.json:

// app.config.js
export default {
  expo: {
    ios: {
      entitlements: {
        'com.apple.developer.declared-age-range': true
      }
    }
  }
}

Or for bare React Native, add to your Info.plist:

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

Android Setup

For Expo projects

The package should work automatically after installation.

For bare React Native projects

1. Add the package to your android/app/build.gradle:

dependencies {
    implementation project(':react-native-age-declaration')
}

2. Add the package to MainApplication.java:

import com.agedeclaration.AgeDeclarationPackage;

@Override
protected List<ReactPackage> getPackages() {
  return Arrays.asList(
      new MainReactPackage(),
      new AgeDeclarationPackage() // Add this line
  );
}

3. Add to android/settings.gradle:

include ':react-native-age-declaration'
project(':react-native-age-declaration').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-age-declaration/android')

🔧 Usage

Basic Example

import AgeDeclaration from 'react-native-age-declaration';

async function checkUserAge() {
  try {
    // 1. Check if the API is supported on this device
    const supported = await AgeDeclaration.isSupported();

    if (!supported) {
      console.log('Age verification not supported on this device');
      return;
    }

    // 2. Set age thresholds (must be done before requesting)
    await AgeDeclaration.setAgeThresholds([13, 15, 18]);

    // 3. Request age range from the platform
    const result = await AgeDeclaration.requestAgeRange();

    // 4. Handle the result
    switch (result.status) {
      case 'verified':
        console.log('User meets age requirements ✅');
        break;
      case 'not_verified':
        console.log('User does not meet age requirements ❌');
        break;
      case 'unknown':
        console.log('Age verification status unknown');
        break;
      case 'not_available_yet':
        console.log('API not available on this device/OS version');
        break;
    }
  } catch (error) {
    console.error('Age verification error:', error);
  }
}

React Hook Example

import { useState, useEffect } from 'react';
import AgeDeclaration from 'react-native-age-declaration';

function useAgeVerification(thresholds: number[]) {
  const [isSupported, setIsSupported] = useState(false);
  const [isVerified, setIsVerified] = useState<boolean | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);

  useEffect(() => {
    async function verify() {
      try {
        // Check support
        const supported = await AgeDeclaration.isSupported();
        setIsSupported(supported);

        if (!supported) {
          setLoading(false);
          return;
        }

        // Set thresholds
        await AgeDeclaration.setAgeThresholds(thresholds);

        // Request age range
        const result = await AgeDeclaration.requestAgeRange();
        setIsVerified(result.status === 'verified');
      } catch (err) {
        setError(err as Error);
      } finally {
        setLoading(false);
      }
    }

    verify();
  }, [thresholds]);

  return { isSupported, isVerified, loading, error };
}

// Usage in component
function MyComponent() {
  const { isSupported, isVerified, loading } = useAgeVerification([13, 18]);

  if (loading) return <Text>Checking age...</Text>;
  if (!isSupported) return <Text>Age verification not available</Text>;
  if (isVerified) return <Text>Access granted</Text>;
  return <Text>Age verification required</Text>;
}

📚 API Reference

setAgeThresholds(thresholds: number[]): Promise<SetThresholdsResult>

Sets the age range thresholds for the application.

Parameters:

• thresholds: Array of age thresholds (1-18, ascending order, 2-year separation)

Returns: Promise that resolves when thresholds are set

Requirements:

• First threshold is mandatory
• Values must be 1-18 (inclusive)
• Must be in ascending order
• Minimum 2-year separation between values

Example:

await AgeDeclaration.setAgeThresholds([13, 15, 18]);

requestAgeRange(): Promise<AgeRangeResult>

Requests age range information from the platform.

Returns: Promise that resolves with age verification result

Important:

• Must call setAgeThresholds() first
• iOS: Requires iOS 26.0+ with DeclaredAgeRange framework
• Android: Requires Android 15+ with Google Play Services

Example:

const result = await AgeDeclaration.requestAgeRange();
console.log(result.status); // 'verified' | 'not_verified' | 'unknown' | 'not_available_yet'

isSupported(): Promise<boolean>

Checks if age range API is supported on this device.

Returns: Promise that resolves to true if supported

Example:

const supported = await AgeDeclaration.isSupported();

🎯 Types

AgeRangeResult

interface AgeRangeResult {
  status: 'verified' | 'not_verified' | 'unknown' | 'not_available_yet' | 'error';
  message?: string;
  thresholds?: number[];
  ageRange?: string;        // iOS only
  lowerBound?: number;      // iOS only
  upperBound?: number;      // iOS only
}

SetThresholdsResult

interface SetThresholdsResult {
  success: boolean;
}

⚠️ Important Notes

iOS

• Requires iOS 26.0 or later with the DeclaredAgeRange framework
• On devices running iOS versions below 26.0, the library will return status: 'not_available_yet'
• You must add the com.apple.developer.declared-age-range entitlement
• Age thresholds can only be set once at startup; changing them will re-prompt the user
• The API presents a system dialog to the user to request age range information

Android

• Requires Google Play Services to be installed and up-to-date
• Only works on Android 15+ (API level 35+)
• The device must have Google Play installed (won't work on devices without Play)

Best Practices

1. Set thresholds at app startup: Call setAgeThresholds() early in your app lifecycle
2. Check support first: Always call isSupported() before attempting verification
3. Handle all status cases: The API can return different statuses, handle each appropriately
4. Don't change thresholds: Once set, keep thresholds consistent to avoid re-prompting users

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT

🐛 Issues

If you encounter any issues, please report them at: https://github.com/dandrykevych/react-native-age-declaration/issues

📝 Changelog

1.0.0 (2025-12-22)

• Initial release
• iOS support for Declared Age Range API
• Android support for Age Signals API
• TypeScript support
• Expo compatible

🙏 Acknowledgments

• Apple's Declared Age Range API documentation
• Google Play's Age Signals API documentation

Made with ❤️ for the React Native community