Integrating Banners

Read through the process of requesting and displaying Fyber Banners for users in your app here. Before following this, you should have already completed Getting started with the Fyber Unity Plugin.

Requesting a Banner
Customizing Banner Sizes
Handling Errors
Showing a Banner
Handling Banner Callbacks
Controlling a Banner Visibility
Destroying a Banner

Requesting a Banner

Before displaying a banner it’s necessary to request it. To do so:

  1. Make sure you’ve initialized the SDK previously as described in Getting started with Fyber SDK.
  2. Set up a delegate to listen to Banners requests using this snippet:

     void OnEnable()
     {
         // Ad availability
         FyberCallback.AdAvailable += OnAdAvailable;
     }
    
     void OnDisable()
     {
         // Ad availability
         FyberCallback.AdAvailable -= OnAdAvailable;
     }
    
     //[...]
    
     Ad bannerAd;
    
     //[...]
    
     private void OnAdAvailable(Ad ad)
     {
         switch(ad.AdFormat)
         {
                 case AdFormat.BANNER:
                     bannerAd = ad;
                     break;
                 //handle other ad formats if needed
         }
     }
    
  3. Use the following code snippet to request a Banner:

     BannerRequester.Create()
         // optional method chaining
         //.AddParameter("key", "value")
         //.AddParameters(dictionary)
         //.WithPlacementId(placementId)
         //.WithNetworkSize(networkBannerSize)
         // you don't need to add a callback if you are using delegates
         //.WithCallback(requestCallback)
         // request the ad
         .Request();
    

Customizing Banner Sizes

Every network has their own banner sizes. Those sizes are represented as objects of the class NetworkBannerSize.

These objects are exposed publicly within the mediation adapters, so they can be accessed directly. They map all the possible sizes from the mediated networks to a size a BannerAd can understand.

These sizes can be attached to the BannerRequester before performing the request, like this:

BannerRequester.Create()
    .WithNetworkSize(<Network Banner Size>)
    .Request();

The sizes will be provided in classes that belong to the mediation adapters. Those classes are named in the following way:

//<MediationNetworkName>NetworkBannerSizes

//e.g for AdMob
AdMobNetworkBannerSizes

//e.g. for Facebook
FaceboookNetworkBannerSizes

If you wish to customize multiple ad networks, you can do it by chaining several WithNetworkSize() calls, like this:

BannerRequester.Create()
	// customizing AdMob size
    .WithNetworkSize(AdMobNetworkBannerSizes.LARGE_BANNER)
    // and now Facebook
    .WithNetworkSize(FaceboookNetworkBannerSizes.BANNER_50)
    .Request();

If no size is provided, then the default one is used, which depends on the network being integrated.

If multiple sizes for the same ad network are provided, only the latest one will be used:

BannerRequester.Create()
	// customizing AdMob size
    .WithNetworkSize(AdMobNetworkBannerSizes.LARGE_BANNER)
    .WithNetworkSize(AdMobNetworkBannerSizes.SMART_BANNER)
    // the request will be performed with SMART_BANNER
    .Request();

If a non supported size is provided, an error will be triggered.

Supported sizes can be found in each ad netowrk page here.

Handling Errors

You won’t always get a successful response. To handle these scenarios you’ll have to set up these delegate methods:

void OnEnable()
{
    FyberCallback.AdNotAvailable += OnAdNotAvailable;   
    FyberCallback.RequestFail += OnRequestFail;
}

void Disable()
{
    FyberCallback.AdNotAvailable -= OnAdNotAvailable;   
    FyberCallback.RequestFail -= OnRequestFail;
}

private void OnAdNotAvailable(AdFormat adFormat)
{
    switch(adFormat)
    {
		case AdFormat.BANNER:
			bannerAd = null;
			break;
        //handle other ad formats if needed
    }
}

private void OnRequestFail(RequestError error)
{
	// process error
    UnityEngine.Debug.Log("OnRequestError: " + error.Description);
}

error can have one of these values:

RequestError Description
DEVICE_NOT_SUPPORTED Only devices running Android API level 10 and above are supported.
CONNECTION_ERROR Internet connection error.
UNKNOWN_ERROR An unknown error occurred.
SDK_NOT_STARTED You need to start the SDK.
NULL_CONTEXT_REFERENCE Context reference cannot be null.
SECURITY_TOKEN_NOT_PROVIDED The security token was not provided when starting the SDK.
ERROR_REQUESTING_ADS An error happened while trying to retrieve ads
UNABLE_TO_REQUEST_ADS The SDK is unable to request right now because it is either already performing a request or showing an ad.

Showing a Banner

Once you’ve received a Banner Ad you show it via:

Ad bannerAd;

//[...]

public void ShowBanner()
{
    if (bannerAd != null)
    {
    	bannerAd.Start();
    }  	 
}

By default, the Banner will be displayed at the bottom of the screen. This can be customized before calling Start() like this:

Ad bannerAd;

//[...]

public void ShowBanner()
{
    if (bannerAd != null)
    {
    	bannerAd.DisplayAtTop()
    		.Start();
		// OR
		//bannerAd.DisplayAtBottom()
    	//	.Start();
    }  	 
}

Calling to several of these positioning methods will make the last one display.

Handling Banner Callbacks

You may want to receive notifications about what’s happening with a Banner while it’s being displayed. In order to do so, you can attach a delegate for the following events:

void OnEnable()
{
    // Called when the banner was clicked
	FyberCallback.BannerAdClicked += OnBannerAdClicked;
	// Called when the banner triggers an error
	FyberCallback.BannerAdError += OnBannerAdError;
	// Called when the banner was loaded
	// this is usually called when the banner rotates (i.e., a new content is shown to the user)
	FyberCallback.BannerAdLoaded += OnBannerAdLoaded;
	// Called when the banner interaction causes an external application to be open
	FyberCallback.BannerAdLeftApplication += OnBannerAdLeftApplication;
	// iOS only
	// The banner will present a modal view
	FyberCallback.BannerAdWillPresentModalView += OnBannerAdWillPresentModalView;
	// iOS only
	// The user did dismiss a modal view
    FyberCallback.BannerAdDidDismissModalView += OnBannerAdDidDismissModalView;
}

// don't forget to remove your delegates when your object is disabled
void OnDisable()
{
      FyberCallback.BannerAdClicked -= OnBannerAdClicked;
      FyberCallback.BannerAdError -= OnBannerAdError;
      FyberCallback.BannerAdLoaded -= OnBannerAdLoaded;
      FyberCallback.BannerAdLeftApplication -= OnBannerAdLeftApplication;
      // iOS only
      FyberCallback.BannerAdWillPresentModalView -= OnBannerAdWillPresentModalView;
      // iOS only
      FyberCallback.BannerAdDidDismissModalView -= OnBannerAdDidDismissModalView;
}

If you don’t want to use a global delegate to handle the events, you can attach your own implementation of the BannerAdCallback

public interface BannerAdCallback
{
    // Called when the banner triggers an error
    void OnAdError(BannerAd ad, String error);

    // Called when the banner was loaded
    void OnAdLoaded(BannerAd ad);

    // Called when the banner was clicked
    void OnAdClicked(BannerAd ad);

    // Called when the banner interaction causes an external application to be open
    void OnAdLeftApplication(BannerAd ad);

    // iOS only
    // The banner will present a modal view
    void OnAdWillPresentModalView(BannerAd ad);

    // iOS only
    // The user did dismiss a modal view
    void OnAdDidDismissModalView(BannerAd ad);
}

to the BannerAd instance before calling its Start() method, like this:

Ad bannerAd;
MyBannerAdCallback bannerAdCallback;

//[...]

public void ShowBanner()
{
    if (bannerAd != null)
    {
    	bannerAd.WithBannerAdCallback(bannerAdCallback)
    		.Start();
    }  	 
}

Controlling a Banner Visibility

Once a Banner is being displayed, it is possible to hide it temporarily by calling:

Ad bannerAd;

//[...]

bannerAd.Hide()

You can then show it again by simply calling:

Ad bannerAd;

//[...]

bannerAd.Show()

Destroying a Banner

Only one banner can be displayed at a time. In order to request a new one, the previous instance has to be destroyed, releasing all its resources.

When a banner is not going to be used anymore, either because another banner has to be displayed or because of activity termination, destroy it by performing the following on your BannerAd instance:

Ad bannerAd;

//[...]

bannerAd.Destroy();