Frequency Cap Check

SimulaAds.checkFrequencyCap() reports whether the user has already hit their frequency cap for an ad unit — a read-only backend check that records no impression. Use it to detect ahead of time that an ad would not fill, and skip the ad-gated surface entirely, instead of sending the user into a flow that ends in no-fill.

import { SimulaAds } from '@simula/ads-react-native';

const capped = await SimulaAds.checkFrequencyCap('SIM-RWD-XXXXXXXX');
if (!capped) {
  setSelectorOpen(true); // still eligible — open the selector
}

Parameters

Parameter	Type	Description
adUnitId	string	required — the ad unit to check
primaryUserID	string	Optional. Falls back to the SDK's current user ID, then to the backend's IP/device/session signals

Return Value

Resolves to true when the cap has been reached — the next ad request would not fill, so skip the surface.

Resolves to false when the user is still eligible, before SimulaAds.initialize(), or on any network failure: the check fails open, so a transport hiccup can never hide an ad surface that would otherwise have served.

Eligibility, not a fill guarantee

A pass on the cap check means the user is eligible to be served — it doesn't reserve an ad, and fill is still decided by available demand at request time. In practice, frequency capping is the leading cause of no-fill on Simula, so an uncapped user is a strong predictor of fill.

Example: Gating the CharacterSelector

Rewarded ads are frequency-capped per user. Check the cap before opening the CharacterSelector so a user who can't be served another ad today never sees a dead-end flow:

<Button
  title="Earn free credits"
  onPress={async () => {
    const capped = await SimulaAds.checkFrequencyCap('SIM-RWD-XXXXXXXX');
    if (!capped) setSelectorOpen(true);
  }}
/>

Because the check fails open, it can never hide the button from an eligible user.