OverviewAndroidiOSUnityReact NativeFlutter (BETA)CLIAPIMCPNetworksAd FormatsDemand PartnersDashboardChangelog

Ad units

Ad units represent specific locations in your app where ads are displayed.

Ad units

Create an ad unit

You can create ad units from the Ad Units page in the sidebar or directly from an App page. Creating from an app page pre-selects the app for you.

To create an ad unit:

  1. Click + Add ad unit
  2. Enter a name for your ad unit
  3. Select which app this ad unit belongs to (if not already selected)
  4. Choose an ad unit type
  5. Configure format-specific settings
  6. Click Save

Ad unit types

TypeSizeDescription
Banner320x50Standard banner ads with auto-refresh
MREC300x250Medium rectangle ads for content feeds
InterstitialFull-screenFull-screen ads for natural transitions
RewardedFull-screenVideo ads that reward users for watching (e.g., extra lives, in-game currency)
NativeFlexibleAds that match your app’s look and feel
App OpenFull-screenAds shown when users open or return to your app

Ad format settings

1. Banner, MREC:

Banner, MREC Refresh rate - how often the banner ad refreshes, measured in seconds (default: 30). Common values are 30, 60, or 90 seconds; the minimum is 1 second. To stop refreshing entirely, use the Disable auto-refresh checkbox — entering 0 is not accepted.

2. Rewarded:

Rewarded

  • Reward amount - the number of items the user receives after watching the ad. For example, 10 coins or 1 extra life.

  • Reward currency - the name of the reward. For example, coins, gems, or extra lives.

  • Reward callback URL - a server-to-server callback URL that CloudX calls when a user completes a rewarded ad. Use this to verify rewards on your backend before granting them to the user. See Rewarded callbacks for supported macros.

Ad position signal

The Ad position setting controls the position signal CloudX sends to bidders for an ad unit. It helps bidders understand where the ad appears on screen and can improve how they value the opportunity.

Keep Default (recommended) unless the format default does not match where the ad actually appears. Default (recommended) uses these format-specific defaults:

  • Banner sends 1 (above the fold).
  • MREC omits the position signal.
  • Fullscreen formats send 7 (full screen).

The value is sent in banner.pos or video.pos, depending on the media type in the bid request.

ValuePosition
0Unknown
1Above the fold
2Locked or fixed position
3Below the fold
4Header
5Footer
6Sidebar
7Full screen

To set an override:

  1. Open Ad Units
  2. Create an ad unit or select one to edit
  3. Choose the value that matches the ad’s actual on-screen position
  4. Click Save or Save changes

Selecting Default (recommended) on an existing ad unit clears its saved override. The setting is shown only for supported ad formats; changing to an unsupported format also clears the override.

Frequency caps

Use frequency caps to limit how many impressions the same user can see from a specific ad unit within a chosen time window.

CloudX currently supports these windows for ad-unit caps:

  • hour
  • day
  • session

Configure an ad-unit cap

  1. Open Ad Units
  2. Select the ad unit you want to update
  3. In the Frequency cap section, enable the cap
  4. Set Max impressions
  5. Select a Time window
  6. Click Save changes

Example:

  • 2 / hour means the same user can see at most 2 impressions from that ad unit in a single hour

How enforcement works

Frequency caps are checked before the auction, but counted on impression.

That means:

  • a request does not burn cap just because an auction ran
  • the counter increments only after an ad is actually shown
  • once the user is over cap, capped inventory returns no fill

Notes

  • Session caps require the SDK to send a session ID with the ad request.
  • Ad-unit caps are evaluated independently from segment caps. If both are configured, the request must pass both checks to serve.
  • The Dashboard also supports segment caps and a default cap for unsegmented traffic from the Segments area.

Rewarded callbacks

CloudX sends an HTTP GET request to your callback URL each time a user completes a rewarded ad. Use this to verify the reward on your server before crediting the user.

In the Reward callback URL field, paste a URL that includes any of the macros below. CloudX replaces each macro with the actual value before making the request.

Example:

https://your-server.com/rewards?event_id={EVENT_ID}&token={EVENT_TOKEN}&amount={AMOUNT}&currency={CURRENCY}&data={CUSTOM_DATA}&revenue={REVENUE}

Supported macros

MacroDescriptionURL-encoded
{EVENT_ID}Unique identifier for this reward event.No
{EVENT_TOKEN}Verification token: SHA1(EVENT_ID + event_key), where event_key is the secret configured on the ad unit. Recompute the hash server-side from the received {EVENT_ID} and your key, and reject the callback unless it matches — this proves the call was generated by CloudX rather than forged. To also guard against replays, store processed {EVENT_ID}s and reject duplicates.No
{AMOUNT}Reward amount configured on the ad unit (numeric). Always present, defaults to 0.No
{CURRENCY}Reward currency name configured on the ad unit.Yes
{CUSTOM_DATA}Arbitrary string passed by the SDK. Use this to attach context such as game level or user state to the callback.Yes
{REVENUE}Per-impression revenue value (numeric). Defaults to 0 if not available.No

Macros marked URL-encoded are percent-encoded so they are safe to use as query parameter values. If a macro’s value is not set, it is replaced with an empty string — the placeholder is never sent literally.

Retry behavior

CloudX retries the callback up to 2 times if your server times out. Non-timeout errors (4xx, 5xx) are not retried. Make sure your endpoint responds within a few seconds.

After creating an ad unit

Once your ad unit is created:

  1. Reference it in your SDK code using the ad unit ID, which you can copy from the ad unit’s page
  2. Create line items to define which demand sources serve ads and at what price
  3. Configure network mappings to connect your ad unit to demand partners