Banner Ad

Banner ads are compact non-sticky ads that can be seamlessly embedded within your existing application, displaying the ad content within that confined space. The BlueStack SDK Flutter Plugin supports multiple banner sizes and provides extensive customization options.

Integration

The SDK provides a BannerView widget, that must be used to display the ads. Each render of the widget loads a single ad, allowing you to display multiple ads at once. It has following properties,

Property	Type	Requirement	Desctiption
key	Key	Optional	Identifier for a banner
type	BannerAdType	Mandatory	Banner ad type
placementId	string	Mandatory	ID of impression placement provided in BlueStack console
shouldLoadWhenReady	boolean	Optional	If true, the ad will be automatically loaded as soon as all the properties are set
options	RequestOptions	Optional	To pass additional request options before loading an ad

BlueStack banner ad supports following types

Type	Value	Dimensions in dp (WxH)
Standard	banner	320x50
Large	largeBanner	320x100
Full	fullBanner	468x60
Medium Rectangle	mediumRectangle	300x250
Leaderboard	leaderboard	728x90
Dynamic	dynamicBanner	Screen width x 50 (Adjusted Banner)
Dynamic Leaderboard	dynamicLeaderboard	Screen width x 90 (Adjusted Banner for tablet)

Enum representing the BlueStack banner ad sizes.

enum BannerAdSize {
  banner,
  largeBanner,
  fullBanner,
  mediumRectangle,
  leaderboard,
  dynamicBanner,
  dynamicLeaderboard
}

Step 1. Import component

You need to import bluestack_sdk.dart in order to display BlueStack banner ads.

import 'package:bluestack_sdk_flutter/bluestack_sdk.dart';

Step 2. Create an banner ad

Self-loading banner ad

You can create a banner ad with shouldLoadWhenReady property set to true, which will be automatically loaded as soon as all the mandatory properties are set.

Here's an example of how to create and auto load a banner ad:

// In your widget tree
BannerView(
  type: BannerAdSize.banner,
  placementId: '/YOUR_APP_ID/banner',
  shouldLoadWhenReady: true,
  options: requestOptions,
)

Banner ad with GlobalKey for manual control

final bannerViewKey = GlobalKey<BannerViewState>();

// In your widget tree
BannerView(
  key: bannerViewKey,
  type: BannerAdSize.banner,
  placementId: '/YOUR_APP_ID/banner',
  shouldLoadWhenReady: false,
  options: requestOptions,
)

Step 3. Load Banner ad

BannerView has load method that takes instance of RequestOptions as an optional parameter. You can use this method to "manually" load a new ad.

info

Banner load call is not required when shouldLoadWhenReady prop is set to true

// Load a banner ad.
bannerViewKey.currentState?.load();

// Load a banner ad with options.
bannerViewKey.currentState?.load(options: requestOptions);

View the RequestOptions documentation for more details.

attention

You don't need to set RequestOptions in both options property and in load method. If preferences are set in both, the one set in the load method will be used.

Step 4. Register event listeners

BannerView widget also exposes properties for listening to events, allowing you to respond to ad lifecycle events.

Methods	Definition
onAdLoaded	Ad is successfully loaded and SDK is ready to display the ad.
onAdFailedToLoad	The ad failed to load or display.
onAdClicked	User has clicked the ad. Ad may open a link in browser.
onAdRefreshed	The banner ad has been refreshed.
onAdFailedToRefresh	The banner ad has been failed to refresh.

Here's an example of how to setup event listeners:

// Create a banner view
BannerView(
  type: BannerAdSize.banner,
  placementId: '/YOUR_APP_ID/banner',
  shouldLoadWhenReady: true,
  onAdLoaded: (size) {
    print('Banner ad loaded with size: $size');
  },
  onAdFailedToLoad: (error) {
    print('Banner ad failed to load: ${error.message}');
  },
  onAdClicked: () {
    print('Banner ad clicked');
  },
  onAdRefreshed: () {
    print('Banner ad refreshed');
  },
  onAdFailedToRefresh: (error) {
    print('Banner ad failed to refresh: ${error.message}');
  },
)

Show/Hide Banner ad

After loading the banner ad you can hide or show it using toggleVisibility method.

// Control banner visibility
bannerViewKey.currentState?.toggleVisibility(true);

Enable/Disable banner refresh

You can enable or disable the banner auto refresh using toggleRefresh method. Pass true in the method to enable refresh and false to disable it.

// Control banner refresh
bannerViewKey.currentState?.toggleRefresh(true);

Destroy banner ad

You can destroy/remove the banner using destroy method

// Destroy banner when done
bannerViewKey.currentState?.destroy();

Best Practices

1. Placement: Place banner ads where they won't interfere with the user experience
2. Size Selection: Choose the appropriate banner size for your layout
3. Auto-Refresh: Use auto-refresh properly to balance revenue and user experience
4. Error Handling: Always implement error handlers to gracefully handle ad loading failures
5. Memory Management: Call destroy() when the banner is no longer needed

Troubleshooting

Common issues and solutions:

1. Ad Not Loading

   • Check internet connectivity
   • Verify placement ID
   • Ensure SDK is properly initialized

2. Wrong Size Display

   • Verify the selected BannerAdSize
   • Check container constraints