react-native-store-age-declaration

A unified API for implementing age-appropriate experiences across iOS and Android platforms. This library provides easy access to platform-specific age verification and parental control APIs.

📚 Complete Documentation Index | 🚀 Quick Reference | 📖 API Docs | 🎯 Implementation Guide

Features

• ✅ Android Play Age Signals - Access Google Play's Age Range Declaration API
• ✅ iOS Declared Age Range - Access iOS 18+ Declared Age Range API
• 🔒 Type-safe - Full TypeScript support with comprehensive type definitions
• ⚡ Promise-based - Modern async/await API
• 🎯 Cross-platform - Unified API for both iOS and Android
• 📱 React Native - Built on React Native's Turbo Module architecture

Installation

npm install react-native-store-age-declaration

or with yarn:

yarn add react-native-store-age-declaration

Platform-Specific Setup

Android

The library automatically includes the Google Play Age Signals dependency. No additional setup required.

Minimum Requirements:

• minSdkVersion: 21
• compileSdkVersion: 33+

iOS

The library automatically includes iOS Declared Age Range support. No additional setup required.

Minimum Requirements:

• iOS 18.0+ (for Declared Age Range API)
• Xcode 16+

Note: The iOS Declared Age Range API is available starting with iOS 18. On older iOS versions, the method will return an error indicating the version requirement.

API Reference

getAndroidPlayAgeRangeStatus()

Retrieves the age range declaration status from Google Play Age Signals API. This method checks the user's age status as determined by Google Play's parental controls and family settings.

Platform: Android only

Returns: Promise<PlayAgeRangeStatusResult>

Return Type

interface PlayAgeRangeStatusResult {
  installId: string | null;  // Unique identifier for this app installation
  userStatus: string | null;  // Age status: 'UNDER_AGE', 'OVER_AGE', or 'UNKNOWN'
  error: string | null;       // Error message if the operation failed
}

User Status Values

| Status | Description | |--------|-------------| | UNDER_AGE | User is below the age threshold set by the app | | OVER_AGE | User is at or above the age threshold | | UNKNOWN | Age information is not available or could not be determined |

Example Usage

Basic Usage

import { getAndroidPlayAgeRangeStatus } from 'react-native-store-age-declaration';

async function checkUserAge() {
  const result = await getAndroidPlayAgeRangeStatus();
  
  if (result.error) {
    console.error('Error:', result.error);
    return;
  }
  
  console.log('Install ID:', result.installId);
  console.log('User Status:', result.userStatus);
}

React Component Example

import React, { useState, useEffect } from 'react';
import { View, Text, ActivityIndicator } from 'react-native';
import { getAndroidPlayAgeRangeStatus } from 'react-native-store-age-declaration';

function AgeGateComponent() {
  const [loading, setLoading] = useState(true);
  const [isAgeAppropriate, setIsAgeAppropriate] = useState(false);

  useEffect(() => {
    checkAge();
  }, []);

  async function checkAge() {
    try {
      const result = await getAndroidPlayAgeRangeStatus();
      
      if (!result.error && result.userStatus === 'OVER_AGE') {
        setIsAgeAppropriate(true);
      }
    } catch (error) {
      console.error('Age check failed:', error);
    } finally {
      setLoading(false);
    }
  }

  if (loading) {
    return <ActivityIndicator />;
  }

  return (
    <View>
      {isAgeAppropriate ? (
        <Text>Welcome! You can access all features.</Text>
      ) : (
        <Text>Some features are restricted based on age.</Text>
      )}
    </View>
  );
}

Conditional Content Rendering

import { getAndroidPlayAgeRangeStatus } from 'react-native-store-age-declaration';

async function shouldShowMatureContent(): Promise<boolean> {
  const result = await getAndroidPlayAgeRangeStatus();
  
  // Show mature content only if user is confirmed over age
  return result.userStatus === 'OVER_AGE';
}

// Usage in your app
async function loadContent() {
  const canShowMature = await shouldShowMatureContent();
  
  if (canShowMature) {
    // Load all content
    loadAllGames();
  } else {
    // Load age-appropriate content only
    loadKidFriendlyGames();
  }
}

requestIOSDeclaredAgeRange()

Requests age range declaration from iOS Declared Age Range API. This method prompts the user to share their age range information using iOS 18+'s system dialog.

Platform: iOS 18+ only

Parameters:

• firstThresholdAge (number): First age threshold (e.g., 13)
• secondThresholdAge (number): Second age threshold (e.g., 17)
• thirdThresholdAge (number): Third age threshold (e.g., 21)

Returns: Promise<DeclaredAgeRangeResult>

Return Type

interface DeclaredAgeRangeResult {
  status: string | null;         // 'sharing', 'declined', or specific age range
  parentControls: string | null;  // Parental control status
  lowerBound: number | null;      // Lower bound of age range
  upperBound: number | null;      // Upper bound of age range
}

Status Values

| Status | Description | |--------|-------------| | sharing | User agreed to share age information | | declined | User declined to share age information |

Example Usage

Basic Usage

import { requestIOSDeclaredAgeRange } from 'react-native-store-age-declaration';

async function checkIOSAge() {
  try {
    // Request age with thresholds: 13, 17, 21
    const result = await requestIOSDeclaredAgeRange(13, 17, 21);
    
    if (result.status === 'sharing') {
      console.log('Age range:', result.lowerBound, '-', result.upperBound);
      console.log('Parental controls:', result.parentControls);
      
      // Check if user is over 17
      if (result.lowerBound && result.lowerBound >= 17) {
        showAllContent();
      } else {
        showAgeAppropriateContent();
      }
    } else if (result.status === 'declined') {
      console.log('User declined to share age');
      showDefaultContent();
    }
  } catch (error) {
    console.error('Error:', error);
  }
}

Cross-Platform Example

import { Platform } from 'react-native';
import {
  getAndroidPlayAgeRangeStatus,
  requestIOSDeclaredAgeRange,
} from 'react-native-store-age-declaration';

async function checkAge() {
  if (Platform.OS === 'android') {
    const result = await getAndroidPlayAgeRangeStatus();
    return result.userStatus === 'OVER_AGE';
  } else if (Platform.OS === 'ios') {
    const result = await requestIOSDeclaredAgeRange(13, 17, 21);
    return result.status === 'sharing' && 
           result.lowerBound !== null && 
           result.lowerBound >= 18;
  }
  return false;
}

Error Handling

The library provides detailed error messages to help you debug issues:

const result = await getAndroidPlayAgeRangeStatus();

if (result.error) {
  if (result.error.includes('AGE_SIGNALS_INIT_ERROR')) {
    // Google Play Services might not be available
    console.log('Age signals service unavailable');
  } else {
    // Other errors
    console.log('Error:', result.error);
  }
}

Common Error Scenarios

Android

| Error | Possible Cause | Solution | |-------|---------------|----------| | AGE_SIGNALS_INIT_ERROR | Google Play Services unavailable | Check if device has Google Play Services | | Network errors | No internet connection | Retry when connection is restored | | UNKNOWN status | User hasn't set up Family Link | Use default age-neutral content |

iOS

| Error | Possible Cause | Solution | |-------|---------------|----------| | IOS_VERSION_ERROR | iOS version below 18.0 | Check iOS version before calling | | NO_VIEW_CONTROLLER | Unable to present UI | Ensure app is in foreground | | User declined | User chose not to share | Use default age-appropriate content |

Best Practices

1. Graceful Fallbacks

Always handle cases where age information is unavailable:

const result = await getAndroidPlayAgeRangeStatus();

if (result.error || result.userStatus === 'UNKNOWN') {
  // Default to safe, age-appropriate content
  showSafeContent();
} else if (result.userStatus === 'OVER_AGE') {
  showAllContent();
} else {
  showKidsContent();
}

2. Cache Results

Age status rarely changes during an app session. Cache the result:

let cachedAgeStatus: PlayAgeRangeStatusResult | null = null;

async function getAgeStatus() {
  if (!cachedAgeStatus) {
    cachedAgeStatus = await getAndroidPlayAgeRangeStatus();
  }
  return cachedAgeStatus;
}

3. Platform-Specific Code

Use platform checks to call the appropriate API:

import { Platform } from 'react-native';
import {
  getAndroidPlayAgeRangeStatus,
  requestIOSDeclaredAgeRange,
} from 'react-native-store-age-declaration';

async function checkAgeStatus() {
  if (Platform.OS === 'android') {
    const result = await getAndroidPlayAgeRangeStatus();
    return result.userStatus === 'OVER_AGE';
  } else if (Platform.OS === 'ios') {
    const result = await requestIOSDeclaredAgeRange(13, 17, 21);
    return result.status === 'sharing' && result.lowerBound >= 18;
  }
  return false;
}

4. Privacy Compliance

• Only use age signals for age-appropriate content filtering
• Don't use installId for tracking purposes without user consent
• Follow COPPA, GDPR, and other privacy regulations
• Provide clear privacy disclosures in your app

Understanding Google Play Age Signals

Google Play Age Signals helps developers provide age-appropriate experiences by accessing age information from:

• Family Link accounts - Parental controls set up by parents
• Play Store age declarations - User-provided age information
• Account settings - Google account age data

The API respects user privacy and only provides:

• Whether the user is above/below your app's age threshold
• A unique installation ID (not linked to personal information)

Troubleshooting

Age status always returns UNKNOWN

Possible causes:

1. User doesn't have Family Link set up
2. User hasn't declared age in Play Store
3. Device doesn't have Google Play Services
4. App not installed from Google Play Store

Solution: Implement fallback logic for UNKNOWN status

Error: AGE_SIGNALS_INIT_ERROR

Cause: Google Play Services unavailable or outdated

Solution:

// Check if device supports age signals
const result = await getAndroidPlayAgeRangeStatus();
if (result.error?.includes('INIT_ERROR')) {
  // Fall back to manual age verification
  showManualAgeGate();
}

Requirements

Android

• React Native >= 0.71
• Android API Level >= 21 (Android 5.0)
• Google Play Services installed on device
• App distributed through Google Play Store (for full functionality)

iOS

• React Native >= 0.71
• iOS 18.0+ (for Declared Age Range API)
• Xcode 16+

TypeScript Support

This library is written in TypeScript and includes complete type definitions. All types are exported for your convenience:

import type { 
  PlayAgeRangeStatusResult,
  DeclaredAgeRangeResult,
} from 'react-native-store-age-declaration';

Documentation

• 📚 API Reference - Complete API documentation with detailed method descriptions and type definitions
• 🚀 Implementation Guide - Step-by-step guide with real-world examples and best practices
• 🔍 Code Examples - Working example app demonstrating library usage

Links & Resources

• Google Play Age Signals Documentation
• Apple Declared Age Range Documentation
• COPPA Compliance Guide
• React Native Documentation

Contributing

We welcome contributions! Please see:

• Development workflow
• Sending a pull request
• Code of conduct

Support

• 🐛 Report a Bug
• 💬 Ask a Question
• 📧 Contact: Create an issue

License

MIT

Made with create-react-native-library