Banner Ad

Integration

Step 1. Instantiate Banner Ad

You can instantiate a BannerAd right after the SDK finishes initialization. The constructor you pick determines how the banner is positioned on screen.

public class BlueStackAdsController : MonoBehaviour
{
    private BannerAd _bannerAd;

    void Start()
    {
        BlueStackAds.SetDebugMode(true);
        BlueStackAds.Initialize("app_id", HandleInitCompleteAction);
    }

    private void HandleInitCompleteAction(InitializationStatus status)
    {
        // Top/Bottom anchored — respects the device safe area by default.
        _bannerAd = new BannerAd(placementId, AdPosition.Bottom);
    }
}

Constructor options

Constructor	Description
BannerAd(string placementId, AdPosition adPosition, bool useSafeArea = true)	Sticky Top/Bottom banner. Pass useSafeArea: false to ignore the device safe area (notch / home indicator / status bar).
BannerAd(string placementId, Vector2 adPosition)	Banner positioned at an explicit screen-space coordinate. The point is the banner's top-left corner in Unity pixels (bottom-left origin) — the banner extends right and downward from it. Custom-positioned banners always ignore the safe area.
BannerAd(string placementId, Transform anchor, Camera camera = null)	Banner follows a GameObject anchor — the SDK adds an AdPlacementHandler component to the anchor that re-positions the banner each frame. The anchor's screen-space position is treated as the banner's top-left corner.

// Sticky Top banner, ignoring the device safe area
_bannerAd = new BannerAd(placementId, AdPosition.Top, useSafeArea: false);

// Explicit screen-space position, (x, y) is the banner's top-left corner.
_bannerAd = new BannerAd(placementId, new Vector2(x, y));

// Anchored to a GameObject, the anchor's screen position is the banner's top-left corner.
_bannerAd = new BannerAd(placementId, anchorTransform, trackingCamera);

Sticky banner positions

Position	value	Definition
Top	0	Banner is anchored to the top of the screen
Bottom	1	Banner is anchored to the bottom of the screen

remarque

For both the Vector2 and Transform constructors (and their SetPosition counterparts) the position represents the banner's top-left corner, matching the native iOS / Android frame placement convention. The banner extends right and downward from that point.

Step 2. Register event listeners

BannerAd exposes the following events through its lifecycle.

Event	Payload	Definition
OnAdLoaded	PreferredBannerSize	Ad finished loading. Payload carries the SDK-preferred Width/Height (in iOS points / Android dp).
OnAdFailedToLoad	BlueStackError	The ad failed to load.
OnAdDisplayed	EventArgs	Banner became visible on screen.
OnAdHidden	EventArgs	Banner was hidden via Hide(). The banner can be re-shown with Show().
OnAdClicked	EventArgs	The user clicked the banner.
OnAdRefreshed	EventArgs	The banner auto-refresh delivered a new creative.
OnAdFailedToRefresh	BlueStackError	An auto-refresh attempt failed.
OnAdResized	PreferredBannerSize	The banner's preferred size changed after the initial load (e.g. a refresh delivered a different size).

_bannerAd.OnAdLoaded += (sender, size) =>
{
    Debug.Log($"OnAdLoaded — preferred size {size.Width}x{size.Height}");
};

_bannerAd.OnAdFailedToLoad += (sender, error) =>
{
    Debug.LogError("OnAdFailedToLoad: " + error.Message);
};

_bannerAd.OnAdDisplayed += (sender, args) =>
{
    Debug.Log("OnAdDisplayed");
};

_bannerAd.OnAdHidden += (sender, args) =>
{
    Debug.Log("OnAdHidden");
};

_bannerAd.OnAdClicked += (sender, args) =>
{
    Debug.Log("OnAdClicked");
};

_bannerAd.OnAdRefreshed += (sender, args) =>
{
    Debug.Log("OnAdRefreshed");
};

_bannerAd.OnAdFailedToRefresh += (sender, error) =>
{
    Debug.LogError("OnAdFailedToRefresh: " + error.Message);
};

_bannerAd.OnAdResized += (sender, size) =>
{
    Debug.Log($"OnAdResized — new size {size.Width}x{size.Height}");
};

attention

Make sure you only register event listeners once.

Step 3. Load Banner ad

The AdSize is supplied to the BannerAd constructor (see Step 1) and is fixed for the life of the BannerAd. Supported sizes:

Ad Size	Definition
Banner	320x50
DynamicBanner	dynamic width × 50 — stretches to the screen width
LargeBanner	320x100
FullBanner	468x60
Leaderboard	728x90
DynamicLeaderboard	dynamic width × 90 — stretches to the screen width
MediumRectangle	300x250

BannerAd exposes two Load overloads; one parameterless, and one that accepts a RequestOptions instance for audience targeting.

• Without targeting

_bannerAd.Load();

• With targeting

var requestOptions = new RequestOptions(
    age: 25,
    gender: Gender.Male,
    location: new Location(35.757866, 10.810547, Location.GPS_PROVIDER),
    consentFlag: 1,
    language: "en",
    keyword: "brand=myBrand;category=sport",
    contentUrl: "https://console.bluestack.app");

_bannerAd.Load(requestOptions);

RequestOptions is immutable and reusable across Load calls. See Targeting Audiences for the full field reference and consent-flag semantics.

Step 4. Show Banner ad

After the banner has loaded, request it to be displayed.

_bannerAd.OnAdLoaded += (sender, size) =>
{
    _bannerAd?.Show();
};

Hide / Show Banner ad

A banner can be hidden without releasing native resources and shown again later.

_bannerAd.Hide();
// later
_bannerAd.Show();

Change banner position at runtime

// Switch to a sticky position
_bannerAd.SetPosition(AdPosition.Top);

// Or use an explicit screen-space coordinate, (x, y) is the banner's top-left corner.
_bannerAd.SetPosition(new Vector2(x, y));

// Or follow a GameObject anchor, the anchor's screen position is the banner's top-left corner.
_bannerAd.SetPosition(anchorTransform, trackingCamera);

Anchor a Banner ad

When you use the BannerAd(string placementId, Transform anchor, Camera camera = null) constructor or call SetPosition(Transform anchor, Camera camera = null), the SDK adds an AdPlacementHandler to the anchor. It makes the banner to follow the anchor as it animates, scrolls, or moves. For all other constructors BannerAd.PlacementHandler is null.

Access it through BannerAd.PlacementHandler (null-check it first).

var handler = _bannerAd.PlacementHandler;
if (handler != null)
{
    // Throttle the per-frame tracking. Seconds; 0 = every frame; clamped to [0, 5].
    handler.UpdateInterval = 0.1f; // 10 Hz

    // Push the banner to the anchor's current position right now,
    handler.ForceUpdatePosition();
}

attention

The AdPlacementHandler lives on the anchor GameObject and couples the banner to that object's lifecycle:

• Disabling the anchor GameObject hides the banner; re-enabling it shows the banner again.
• Destroying the anchor GameObject destroys the banner.

To stop tracking without this side effect, call SetPosition with a sticky AdPosition or a Vector2 to detaches the handler.

Mask (clip) a Banner ad

You can clip a banner to a UI RectTransform. The banner is shown only inside the mask's screen-space bounds; as the mask animates or resizes, the SDK keeps the clipped region in sync.

// Apply a mask
_bannerAd.SetMask(maskRectTransform);

// Remove the mask
_bannerAd.RemoveMask();

Tuning the clip (MaskHandler)

When SetMask is called, SetMask adds an AdMaskHandler MonoBehaviour to the mask GameObject (which must have a RectTransform). It computes the mask’s screen-space bounds and, when they change, updates the banner clip region so that the clipping remains in sync as the mask animates, resizes, or scrolls. Before SetMask and after RemoveMask BannerAd.MaskHandler is null.

Access it through BannerAd.MaskHandler (null-check it first).

var handler = _bannerAd.MaskHandler;
if (handler != null)
{
    // Throttle the per-frame update. Seconds; 0 = every frame; clamped to [0, 5].
    handler.UpdateInterval = 0.1f; // 10 Hz

    // Recompute and push the clip region right now,
    handler.ForceUpdate();
}

remarque

• SetMask can be called before or after Load. If called before, the mask is cached and applied when the banner becomes visible.

• Custom-positioned banners always ignore the device safe area regardless of the mask state.

• MaskHandler removes the clip region when the mask GameObject is destroyed.

Destroy banner ad

Destroy the banner before creating a new one. After Destroy() the instance can no longer be used.

_bannerAd.Destroy();