cordova-plugin-play-age-signals

Cordova plugin to integrate the Google Play Age Signals API into web-based (HTML/JS/CSS) apps or games.

Official Documentation: Use Play Age Signals API

Installation

Install directly from the NPM:

cordova plugin add cordova-plugin-play-age-signals

Basic Usage

Ensure the API is called only after the Cordova deviceready event fires.

document.addEventListener('deviceready', onDeviceReady, false);

function onDeviceReady() {
    if (window.cordova && window.cordova.plugins && window.cordova.plugins.PlayAgeSignals) {
        window.cordova.plugins.PlayAgeSignals.checkAgeSignals(
            function(result) {
                handleAgeSignals(result);
            },
            function(error) {
                console.error("Age Signals API Error:", error);
            }
        );
    }
}

API Reference

The plugin returns a JSON object. Values default to null if the user is outside legally mandated jurisdictions or has not shared their age.

• userStatus (String | null): Verification status (e.g., VERIFIED, DECLARED, SUPERVISED, SUPERVISED_APPROVAL_PENDING, SUPERVISED_APPROVAL_DENIED, UNKNOWN).
• ageLower (Number | null): Lower bound of the user's age range.
• ageUpper (Number | null): Upper bound of the user's age range.
• installId (String | null): Unique install ID generated by Google Play for supervised users.
• mostRecentApprovalDate (String | null): Timestamp of the last significant change approved by a parent/guardian.

Application-Side Handling (Action Required)

The plugin only retrieves data. Developers must implement UI and logic restrictions based on the returned signals to comply with regulations (e.g., Digital ECA, COPPA, Texas SB2420).

1. Complete Access Denial

If a parent refuses permission for a child to use the app, the user must be blocked.

• Condition: userStatus returns SUPERVISED_APPROVAL_DENIED.
• Action: Display an access denied screen and hide all main application features.

2. Content or Feature Restriction

Laws prohibit unsupervised minors from accessing features like public chat, in-app purchases, or mature content.

• Condition: Age range (ageLower and ageUpper) is between 0 and 12, or userStatus is SUPERVISED_APPROVAL_PENDING.
• Action: Disable chat buttons, hide store/top-up menus, or activate a safe mode content filter.

3. Disable Tracking and Targeted Ads (Privacy & Ads Compliance)

Child privacy laws strictly prohibit personal analytic tracking and targeted advertising.

• Condition: Age range indicates the user is a child.
• Action: Modify analytics SDK initialization (e.g., Google Analytics, Firebase) to avoid collecting Advertising IDs, and configure Ad SDKs (e.g., AdMob) to serve only non-personalized ads.

Example Implementation

function handleAgeSignals(result) {
    if (result.userStatus === 'SUPERVISED_APPROVAL_DENIED') {
        blockAppAccess("Access denied by parent or guardian.");
        return;
    }

    if (result.userStatus === 'SUPERVISED' || result.userStatus === 'SUPERVISED_APPROVAL_PENDING') {
        if (result.ageUpper !== null && result.ageUpper <= 12) {
            disableTargetedAdvertising();
            disableInAppPurchases();
            hidePublicChatBox();
            enableKidsSafeMode();
        } else if (result.ageLower >= 13 && (result.ageUpper === null || result.ageUpper <= 17)) {
            enableTeenMode();
            requireParentalPinForPurchases();
        }
    } else if (result.userStatus === 'VERIFIED') {
        enableFullAppExperience();
    } else {
        // Fallback for unrestricted regions (null / UNKNOWN)
        enableFullAppExperience();
    }
}

Testing Guidelines

VPN routing is insufficient for testing. Google Play retrieves region and age data directly from the authenticated Google Account. To receive production payloads (e.g., SUPERVISED status or age ranges) instead of null, testing must be conducted using a Google Account legitimately registered in a regulated jurisdiction (such as Texas, USA).

License

MIT