This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 57).
Expo 年龄范围
一个在 Android 上使用 Play Age Signals API、在 iOS 上使用 Declared Age Range 框架来提供年龄范围信息访问的库。
expo-age-range 提供访问用户年龄范围信息的功能。在 Android 上,它使用 Google 的 Play 年龄信号 API,在 iOS 上使用 Apple 的已声明年龄范围框架。
此库允许你向应用用户请求年龄范围信息,以帮助你遵守适龄内容法规(例如 美国得克萨斯州)并在应用中提供适合年龄的体验。
Google 和 Apple 提供的底层原生 API 仍在积极开发中。虽然此库是稳定的,但为了适应这些 API,可能需要进行更多破坏性更改。
限制
我们建议在真实设备上测试此功能,因为模拟器运行环境可能无法按预期工作。
安装
If you are installing this in an existing React Native app, make sure to install expo in your project.
在 app 配置中进行配置
设置 iOS 项目
要在 iOS 上使用年龄范围 API,你需要使用 Xcode 26.0 或更高版本构建项目,但我们建议使用最新版本的 Xcode,以便访问最新的 API。
需要使用 com.apple.developer.declared-age-range entitlement。将其添加到你的应用配置文件中:
Are you using this library in an existing React Native app?
对于现有的 React Native 项目,将该 entitlement 添加到项目的 ios/[app]/[app].entitlements 文件中:
<key>com.apple.developer.declared-age-range</key> <true/>
用法
在 Android 上,Play 年龄信号仅会在用户同意分享年龄范围时报告年龄范围。请先调用 requestAgeSignalsAccessAsync,并仅在其解析为 'SHARED' 时继续。在 iOS 上,同意提示是 requestAgeRangeAsync 的一部分,因此该调用会解析为 null,下面的示例会继续执行。
在 Android 上测试年龄信号
Google Play 只会向已启用年龄信号的账号报告年龄信号,因此你的测试账号可能没有所需的年龄范围。请使用 setFakeAgeSignals,通过 Google Play 的 FakeAgeSignalsManager 模拟年龄信号。
只有可调试构建才能模拟信号,因为伪造的信号会让应用中的任何代码绕过年龄限制。如果在不可调试的构建中传入除 null 以外的任何值,则会抛出 ERR_AGE_RANGE_FAKE_SIGNALS_NOT_DEBUGGABLE。
你的请求无需更改,只有报告的内容会改变:
// Report a supervised 13 to 15 year old with a change waiting for approval. AgeRange.setFakeAgeSignals({ ageSignalsStatus: 'SHARED', lowerBound: 13, upperBound: 15, ageRangeSource: 'TIER_B', significantChangeStatus: 'PENDING', }); const status = await AgeRange.requestAgeSignalsAccessAsync(); const { lowerBound } = await AgeRange.requestAgeRangeAsync({ threshold1: 18 }); // Report the real signals again. AgeRange.setFakeAgeSignals(null);
要模拟失败,请传入错误代码,而不是信号:
AgeRange.setFakeAgeSignals({ errorCode: -4 });
其他资源
- Play 年龄信号 API:Android 的年龄信号文档
- 已声明年龄范围框架:iOS 的已声明年龄范围文档。
API
import * as AgeRange from 'expo-age-range';
Methods
Returns the set of regulatory features that the OS reports as required for the current user.
Use this to discover which age-assurance obligations apply.
Resolves with null on iOS earlier than 26.4 and on Android and web — treat
null as "unknown" rather than "no features required".
Promise<AgeRangeRegulatoryFeature[] | null>Asks the OS whether age-assurance regulation applies to the current user. Apple uses this to signal that the account region is covered by a law such as Utah's or Louisiana's age-assurance requirements, so apps can avoid gating users in jurisdictions where the rules do not apply.
- Resolves with
trueonly when Apple confirms regulation applies. - Resolves with
falsewhen the OS confirms regulation does not apply. - Resolves with
nullon iOS earlier than 26.2, and on Android and web. Treatnullas "unknown" rather than a definitivefalse. - Rejects when the request fails — see AgeRangeService.Error
for more information. Treat rejection as "unknown" and fall through to
requestAgeRangeAsyncor your own gating logic.
Recommended pattern: call this first and only prompt the user for their age
range when the result is not false. When it is false, the user is outside
a regulated jurisdiction and you can skip the age gate entirely.
Promise<boolean | null>Example
try { const eligible = await isEligibleForAgeFeaturesAsync(); if (eligible === false) { // Regulation does not apply — no age gate needed. return; } } catch { // Treat errors as "unknown" and fall through to the prompt below or your own gating logic. } const ageRange = await requestAgeRangeAsync({ threshold1: 18 });
Prompts the user to share their age range with the app. Responses may be cached by the OS for future requests.
Promise<AgeRangeResponse>A promise that resolves with user's age range response, or rejects with an error.
The user needs to be signed in on the device to get a valid response.
When not supported (earlier than iOS 26 and web), the call returns lowerBound: 18, which is equivalent to the response of an adult user.
On Android, call requestAgeSignalsAccessAsync first and
only call this function when it resolves with 'SHARED'. Play Age Signals reports every field as
null otherwise.
Asks the user to consent to sharing their age signals, showing the Play Age Signals in-app age sharing consent
screen. Play Age Signals requires this before requestAgeRangeAsync:
age signals are only reported while the status is 'SHARED'.
- Resolves with
'SHARED'when the user agrees to share their age signals. Only then doesrequestAgeRangeAsyncreport an age range. - Resolves with
'NOT_SHARED'when the user does not agree.requestAgeRangeAsyncreports every field asnulluntil the user consents. - Resolves with
'VERIFICATION_REQUIRED'when the user's age is unknown and they are in a region where age verification is mandatory. Ask the user to visit the Play Store to resolve their status. - Resolves with
nullwhen Play Age Signals reports no status, and on iOS and web. On iOS the consent prompt is part ofrequestAgeRangeAsyncitself, so there is nothing separate to call. - Rejects when the request fails.
Promise<AgeSignalsStatus | null>Fakes the age signals that requestAgeRangeAsync and
requestAgeSignalsAccessAsync report, using Play Age Signals
FakeAgeSignalsManager.
Pass null to go back to the real signals.
Only debuggable builds can fake signals. Passing anything other than null in a build that is not debuggable
throws.
voidExample
// A supervised 13 to 15 year old with a change waiting for approval. setFakeAgeSignals({ ageSignalsStatus: 'SHARED', lowerBound: 13, upperBound: 15, ageRangeSource: 'TIER_B', significantChangeStatus: 'PENDING', });
Displays a system-provided interface for people to acknowledge a significant app update.
Only on iOS 26.4+, this presents an update acknowledgement dialog and resolves once the user confirms it, or rejects with an error. On unsupported platforms this resolves immediately without showing any UI.
Call getRequiredRegulatoryFeaturesAsync first to
determine whether the user actually needs to acknowledge a significant change — only invoke
this function when the returned features include 'significantAppChangeRequiresAdultNotification'.
Doing so avoids prompting users who are not subject to the regulation.
Promise<void>Types
Literal type: string
A regulatory feature that your app may need to support for the current user.
Mirrors AgeRangeService.RegulatoryFeature.
Acceptable values are: 'declaredAgeRangeRequired' | 'significantAppChangeRequiresAdultNotification' | 'significantAppChangeRequiresParentalConsent'
Response containing the user's age range information.
Contains age boundaries and platform-specific metadata.
Literal type: string
The sharing status of age signals, returned by requestAgeSignalsAccessAsync.
Acceptable values are: 'SHARED' | 'NOT_SHARED' | 'VERIFICATION_REQUIRED'
Fake age signals for setFakeAgeSignals: either a response or
an error, never both.
The response fields match AgeRangeResponse, with ageSignalsStatus for
requestAgeSignalsAccessAsync. Omitted fields are
reported as null.
Type: object shaped as below:
Or object shaped as below:
错误代码
可在原生模块抛出的任何错误的 code 属性中获取。对于 Android 特定的错误代码,请参阅使用 Play 年龄信号 API 文档中的“错误代码参考”。