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