Banner Ad

For a working implementation of this ad format, see the bluestack-demo-unity demo app.

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.

Position	value	Definition
Custom	-1	Banner is positioned at an explicit screen-space coordinate
Top	0	Banner is anchored to the top of the screen
Bottom	1	Banner is anchored to the bottom of the 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 (Unity pixels, bottom-left origin). 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 from anchor.position.

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

// Explicit screen-space position
_bannerAd = new BannerAd(placementId, new Vector2(x, y));

// Anchored to a GameObject — banner follows the anchor in screen space
_bannerAd = new BannerAd(placementId, anchorTransform, trackingCamera);

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}");
};

caution

Make sure you only register event listeners once.

Step 3. Load Banner ad

BannerAd.Load takes an AdSize. An overload also accepts a Preference instance for targeting. Supported sizes:

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

• Without Preference

_bannerAd.Load(AdSize.Banner);

• With Preference

public class BlueStackAdsController : MonoBehaviour
{
   ...
   private void RequestBannerAd()
   {
       Preference _preference = new Preference();
       Location myLocation = new Location(Location.NONE_PROVIDER)
       {
           Latitude = 35.757866,
           Longitude = 10.810547
       };
       _preference.SetAge(25);
       _preference.SetLanguage("en");
       _preference.SetGender(Gender.Male);
       _preference.SetKeyword("brand=myBrand;category=sport");
       _preference.SetLocation(myLocation, 1);
       _preference.SetContentUrl("https://console.bluestack.app");

       _bannerAd.Load(AdSize.Banner, _preference);
   }
   ...
}

Note: The SetLocation method takes the following parameters:

• The Location instance.
• The CONSENT_FLAG value (corresponds to a int: 0, 1, 2 or 3).
  • 0 = Do not send location.
  • 1 = Managed location according to consent value.
  • 2 and 3 = Allow the SDK to manage location directly in accordance with the consent value (TCF v1 / TCF v2). Check with the Azerion team — behavior depends on your implementation.

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
_bannerAd.SetPosition(new Vector2(x, y));

// Or follow a GameObject anchor
_bannerAd.SetPosition(anchorTransform, trackingCamera);

Mask (clip) a Banner ad

In v6.0.0 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);

// (optional) The SDK attached an AdMaskHandler component to the mask GameObject.
// You can throttle the per-frame update if needed (default is every frame; clamped to [0, 5] seconds).
_bannerAd.MaskHandler.UpdateInterval = 0.1f; // 10 Hz

// Remove the mask
_bannerAd.RemoveMask();

note

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.

Destroy banner ad

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

_bannerAd.Destroy();