Age-Based Consent

Overview

Age-Based Consent for the HTML5 SDK enables automatic consent enforcement based on a user’s age range. Administrators configure age range groups in the OneTrust admin console and associate them with specific purposes or purpose groups. The SDK uses this configuration, along with the age range provided by your application, to enforce consent behavior at runtime.

When a user falls within a restricted age range:

• Consent for associated purposes is automatically denied.
• The corresponding purpose toggles in the Preference Center are currently hidden.

This ensures that age-based restrictions are consistently applied without requiring additional application logic.

How it works

At a high level:

• Your CTV application provides the user’s age range.
• The SDK sends the age range to the OneTrust server.
• The server determines consent restrictions based on the configuration settings in the admin console.
• The SDK enforces those restrictions in the UI and APIs.

What’s Changing

SDK Updates

• Registration method for providing the user’s age range.
• ProfileAgeRange data model with lower and upper bounds.
• Automatic consent restriction based on age overlap.
• Server logging of age range changes through the AGEGATE_RANGE interaction.

Server (CMP API) updates

• Accepts and stores user age range data.
• Enforces restrictions by setting consentToggleStatus = -1 for restricted purposes.
• Maintains enforcement across devices for the same user profile.

Implementation

1. Define the ProfileAgeRange data model

Use lowerBound and upperBound to represent the user’s age range. Each property is optional, but at least one bound must be provided.

Use a null or omitted upperBound for an open-ended range such as 18+. Use a null or omitted lowerBound for a range that starts at the youngest supported age.

type ProfileAgeRange = {
  lowerBound?: number | null;
  upperBound?: number | null;
} | undefined;

Sample code

{ lowerBound: 13, upperBound: 17 }   // 13–17 years old
{ lowerBound: 18, upperBound: null } // 18+ (open-ended)
{ lowerBound: null, upperBound: 12 } // 0–12 years old

2. Set up the age range provider

Register the age range provider before calling startSDK. The SDK invokes the provider during initialization so it can retrieve the user’s age range before applying consent restrictions.

// Register the age range provider before startSDK
OneTrust.setupProfileAgeRangeManager((profileId, callback) => {
  // Fetch the age range from your user profile system.
  // This can be synchronous or asynchronous.
  const user = getUserProfile(profileId);

  if (!user || !user.age) {
    callback(null); // Age unknown
    return;
  }

  // User is between 13 and 17
  callback({ lowerBound: 13, upperBound: 17 });

  // Or: user is 18 or older (open-ended)
  // callback({ lowerBound: 18, upperBound: null });

  // Or: age is not available
  // callback(null);
});

// Then call startSDK
OneTrust.startSDK(headers, function(status, response, error) {
  if (status !== 200 || error) {
    console.error('SDK initialization failed:', error);
    return;
  }

  console.log('SDK initialized successfully');
});

Sample reference:

function initializeOneTrust() {
  // Step 1: Register the age range provider
  OneTrust.setupProfileAgeRangeManager((profileId, callback) => {
    console.log('Age range requested for profile:', profileId);

    // Example: Fetch from your user service
    fetchUserAgeRange(profileId)
      .then(ageRange => {
        if (ageRange) {
          callback({
            lowerBound: ageRange.min,
            upperBound: ageRange.max
          });
        } else {
          callback(null);
        }
      })
      .catch(() => {
        callback(null); // Handle errors gracefully
      });
  });

  // Step 2: Initialize the SDK
  OneTrust.startSDK(oneTrustHeaders, function(status, response, error) {
    if (status === 200 && !error) {
      OneTrust.setupUI('self');
    }
  });
}

Public APIs

setupProfileAgeRangeManager

Registers a callback function that the SDK invokes to request the user’s age range.

OneTrust.setupProfileAgeRangeManager(provider);

Parameters

The SDK automatically calls the provider:

• During startSDK initialization.
• When profile switching occurs in multi-profile scenarios.

Sample code

OneTrust.setupProfileAgeRangeManager((profileId, callback) => {
  // Return the age range for the given profile
  const ageRange = getAgeRangeForProfile(profileId);
  callback(ageRange);
});

getPurposeConsentStatus

Returns the consent status for one or more purpose groups.

// Get all purposes
const allStatuses = OneTrust.getPurposeConsentStatus();

// Get a specific purpose
const status = OneTrust.getPurposeConsentStatus('C0005');

// Get multiple purposes
const statuses = OneTrust.getPurposeConsentStatus(['C0001', 'C0005']);

The method returns an array of objects containing id and status.

Age Gate impact

• The method returns 0 automatically for any purpose linked to a restricted age range. No additional code is required.

updatePurposeConsent

Updates the consent value for a purpose group programmatically.

OneTrust.updatePurposeConsent('C0005', true);

With Age-Based Consent

• The SDK prevents enabling consent for age-restricted purposes.
• Calls that attempt to set a restricted purpose to true are ignored, and the consent value remains denied.

Without Age-Based Consent

In older SDKs without Age-Based Consent logic:

• The update may succeed locally.
• The CMP API overrides the value to 0 (denied) during the next synchronization.

Behavior changes

Preference Center

Restricted users

If the user’s age range overlaps with a configured restricted age group:

• The consent toggle for associated purposes is hidden (consentToggleStatus: -1).
• Consent is automatically set to 0 (denied).
• The user cannot provide consent for those purposes.

Non-restricted users

If the user’s age range does not overlap with any restricted age group:

• All consent toggles remain visible and interactive.
• Standard consent behavior applies.

Age range overlap logic

A user is considered restricted if their age range intersects with a restricted age group. Partial overlap also results in restriction.

Logic:

restricted =
  (user.lowerBound <= group.upperBound) &&
  (user.upperBound >= group.lowerBound);

Examples

The following examples use a restricted age group of 0–15.

Cross-device behavior (Authenticated consent)

For environments with Cross-Device Consent or Authenticated Consent enabled, age-based restrictions are enforced server-side and persist across devices.

Once a user’s age range is logged for a profile from any device:

• The CMP API server stores the age range.
• All subsequent consent responses for that profile enforce the same restrictions.
• Enforcement applies across devices, sessions, and SDK versions.

SDKs with Age-Based Consent Support (Recommended)

This configuration provides complete enforcement:

• The server returns consentToggleStatus: -1 for restricted purposes.
• The SDK hides restricted toggles in the UI.
• The SDK prevents consent from being enabled through public APIs such as updatePurposeConsent.
• Enforcement occurs at both the UI level, where the toggle is hidden, and the API level, where updates are blocked.

SDKs without Age-Based Consent Support (Older SDK Versions)

For SDKs that support CMP API but do not include Age-Based Consent logic:

• The server continues to send consentToggleStatus: -1 for restricted purposes.
• The SDK correctly hides toggles in the Preference Center.
• updatePurposeConsent may still allow local updates for restricted purposes. However, these updates are not authoritative as the CMP API server will override consent to 0 (denied) during the next synchronization.

End-to-end flow

1. Admin configures restricted age groups in the OneTrust admin console and links purpose groups or purposes to them.
2. The application registers the age range provider using setupProfileAgeRangeManager.
3. The application calls startSDK.
4. The SDK calls the provider to request the user’s age range.
5. If an age range is provided:
   • The SDK stores it locally.
   • The SDK logs the age range to the CMP API server through an AGEGATE_RANGE consent interaction.
   • The server stores the age range for the profile and enforces restrictions in subsequent responses.
   • The SDK hides toggles for restricted purposes in the Preference Center.
6. If null is returned because the age is unknown:
   • The SDK does not send an age range to the server.
   • The server checks whether an age range already exists for the profile from a prior interaction or another device.
   • If an age range is found, the server continues to enforce age-based restrictions.
   • If no age range exists, no restrictions are applied.
7. When the user’s age changes because of a profile update or account switch:
   • Re-initialize the SDK or switch profiles.
   • The SDK invokes the provider again and compares the result with the stored range.
   • If the range changed, the SDK updates local storage and logs the change to the server.
   • The Preference Center reflects the updated restriction state.

Troubleshooting

If restricted toggles are still visible, verify the following:

• The age range provider is registered before startSDK.
• The callback returns a valid age range.
• The restricted age group is configured in the OneTrust admin UI.
• The relevant purpose or purpose group is linked to the restricted age group.

Migration guide

From Legacy Age Gate

If you are migrating from the legacy Age Gate prompt to Age-Based Consent:

1. Implement setupProfileAgeRangeManager with the user’s age data.
2. Call it before startSDK.
3. The SDK automatically handles consent restrictions based on the provided age range.

Code sample

Before: Legacy Age Gate

// No age-based consent
OneTrust.startSDK(headers, callback);

After: Age-Based Consent

// Register the age range provider first
OneTrust.setupProfileAgeRangeManager((profileId, callback) => {
  const userAge = getUserAge(profileId);

  if (userAge) {
    callback({
      lowerBound: userAge,
      upperBound: userAge
    });
  } else {
    callback(null);
  }
});

// Then initialize the SDK
OneTrust.startSDK(headers, callback);