Banner Ad

This article will go through all the steps required to display an Banner Ad in your application.

Banner Ads are small or medium rectangle ads that have specific dimensions and occupy a certain position of the screen width and they can be freely integrated within the content of the app.

The banner comes with two predefined dimensions:

• small banner (320x50)

• MPU (300x250)

Requirements

You have registered an application on your Ogury Dashboard. If not, please refer to the Getting Started section before the next steps.

Step 1: Create Banner Ad ad units

In case you publish your application on Android and iOS, you should do the following steps twice, once for the Android application and once for the iOS application. Otherwise just select the platform you publish for.

• Create a Banner Ad ad unit.
• Copy the Ad unit id as you will need this information later to finish the integration.

In all the following code samples, we will refer to:

• the Ad unit id for the Android application by using the string ANDROID_AD_UNIT_ID.

• the Ad unit id for the iOS application by using the string IOS_AD_UNIT_ID.

Step 2: Load a Banner Ad

The Ogury SDK provides the OguryBannerAd that lets you load, display and control your Banner Ad.

Instantiate a Banner Ad

• Declare an OguryBannerAd instance variable in the Activity where you want to display a Banner Ad:

private OguryBannerAd _banner;

• In the Start method of your scene, instantiate the Banner Ad:

void Start() {
    // ...
    _banner = new OguryBannerAd(
        "ANDROID_AD_UNIT_ID", 
        "IOS_AD_UNIT_ID",
        bannerSize
    );
}

OguryBannerAdView takes the following parameter:

• the Ad unit id for the Android application. You can use null if your application is not available on Android.

• the Ad unit id for the iOS application. You can use null if your application is not available on iOS.

• the size of the Banner Ad. It can take one of the value defined in OguryBannerAdSize class:

OguryBannerAdSize value	Definition
SmallBanner320X50	Small Banner Ad (320x50)
Mpu300X250	Mid Page Unit Banner Ad (300x250)

Load a Banner Ad

To start loading an ad, call the Load method:

_banner.Load();

Since it may take a few seconds to fetch the ad resources (video, image, ...) from the network, you should call the loadAd method as soon as possible after getting the user's consent.

Ideally, you should implement one of the two following examples depending on your use case:

• Call the Load method right after the Initialize method in the script that also collects the consent:

using OgurySdk;
using OgurySdk.ConsentManager;

public class MyScene : MonoBehaviour {

    private OguryBannerAd _banner;

    void Start() {
        Ogury.Start("ANDROID_ASSET_KEY", "IOS_ASSET_KEY");
        
        _banner = new OguryBannerAd(
            "ANDROID_AD_UNIT_ID", 
            "IOS_AD_UNIT_ID",
            OguryBannerAdSize.SmallBanner320X50
        );
        
        // get user consent
        OguryConsentManager.OnAskComplete += OnCMComplete;
        OguryConsentManager.OnAskError += OnCMError;
        OguryConsentManager.Ask();
    }
    
    private void OnDestroy() {
        OguryConsentManager.OnAskComplete -= OnCMComplete;
        OguryConsentManager.OnAskError -= OnCMError;
    }
    
    private void OnCMComplete() {
        PassConsentToOtherSdks();
        StartSdks();
        // load ad formats
        LoadAdFormats();
    }

    private void OnCMError(OguryError error) {
        PassConsentToOtherSdks();
        StartSdks();
        // load ad formats
        LoadAdFormats();
    }
    
    private void StartSdks() {
        Ogury.StartAds();
        // start vendors' SDKs
    }
    
    private void PassConsentToOtherSdks() {
        // pass user consent to vendors' SDKs
    }
    
    private void LoadAdFormats() {
        // load the banner ad
        _banner.Load();
    }
}

• Call the Load method in the Start method of your other script:

private void Start() {
    _banner = new OguryBannerAd(
        "ANDROID_AD_UNIT_ID", 
        "IOS_AD_UNIT_ID",
        OguryBannerAdSize.SmallBanner320X50
    );
    _banner.Load(); 
}

Additionally, if you want to follow the lifecycle of the Banner Ad, you can register to events.

Step 3: Show a Banner Ad

To display the ad, call the Show method:

_banner.Show(gravity, xOffsetInPixels, yOffsetInPixels);

The Show method takes the following in parameters:

• gravity: position where the banner is displayed. It can take one of the value defined in OguryAdGravity class:

OguryAdGravity value	Definition
Top	The Banner Ad is displayed centered at the top.
TopLeft	The Banner Ad is displayed in top-left corner.
TopRight	The Banner Ad is displayed in top-right corner.
Bottom	The Banner Ad is displayed centered at the bottom.
BottomLeft	The Banner Ad is displayed in bottom-left corner.
BottomRight	The Banner Ad is displayed in bottom-right corner.

• xOffsetInPixels: optional horizontal offset in pixels. A positive value will move the banner away from the border toward the center of the screen. It is not supported in case of Top and Bottom.

• yOffsetInPixels: optional vertical offset in pixels. A positive value will move the banner away from the border toward the center of the screen.

If the method fails to show the ad, one of the following events is triggered:

• OnAdNotLoaded: if the ad was not fully loaded when Show was called.

• OnAdError: if another error occurred. Error codes are explained below.

Step 4: Test your integration

Ogury exclusively serves ads to users who have given consent. It is essential to have responded to a valid TCFv2 consent form before conducting any tests.

As our algorithm works with personified targeting, you may not receive any ad while testing your application.

You can test your integration by adding the suffix _test to your interstitial ad unit id, for more details go to Test your implementation page.

Note that if you have just registered your application in the Ogury Dashboard, it will take around 15 minutes until you can successfully load an ad.

If you are not able to display any Banner Ad, we recommend you to log every events on your OguryBannerAdView to follow the lifecycle of the Interstitial Ad:

• If you encounter the OnAdError event, you can check the error codes section below to understand the error and get some advice on how to solve the issue.

• If you encounter the OnAdNotAvailable event, you can check the test ad section to learn how to display test ads in your application.

Advanced Topics

Hide the Banner Ad

To temporarily hide the Banner Ad, call the Hide method:

_banner.Hide();

Call the Show method to display the Banner Ad again.

Events

The Ogury SDK provides events to listen to the lifecycle of a Banner Ad instance.

To register to an event, add the following code just after instantiating the OguryBannerAd:

_banner.OnAdLoaded += ad =>
{
    // ...
};

The OguryBannerAd exposes the following events:

Methods	Definition
OnAdNotAvailable	The ad server does not have an ad to present to the user. Note that during the integration, you can force the Ogury SDK to always display a test ad. More details can be found in the test ad section.
OnAdLoaded	The SDK is ready to display the ad provided by the ad server.
OnAdNotLoaded	The ad failed to display because it was not fully loaded when theShow method was called.
OnAdDisplayed	The ad has been displayed on the screen.
OnAdImpression	The ad has triggered an impression.
OnAdClosed	The ad has been closed by the user.
OnAdError	The ad failed to load or display. An additional error parameter of type OguryError contains the reason of the failure. All error codes are detailed in the section below.

Error codes

When an ad fails to load or to be displayed, the SDK will trigger the OnAdError event with an OguryError as additional parameter. The OguryError provides the ErrorCode property to retrieve the error code:

error.ErrorCode

Error codes related to Interstitial Ad are defined in the OguryAdsErrorCode class:

Code	Value	Definition
NoInternetConnection	0	The device has no internet connection. Try again when the device is connected to the Internet again.
LoadFailed	2000	The ad failed to load for an unknown reason.
AdDisabled	2001	Ad serving has been disabled for this placement/application.
AdExpired	2002	The loaded ad is expired. You must call the show method within 4 hours after the load.
ProfigNotSynced	2003	An internal SDK error occurred.
SdkInitNotCalled	2004	The Start and/or StartAds methods have not been called before a call to the Load or Show methods.
SdkInitFailed	2005	An error occurred during the initialization of the SDK.
ActivityInBackground	2006	You tried to Show an ad while the application was in background. Make sure to only call theShow method when the application is visible to the user.
AnotherAdAlreadyDisplayed	2007	Another ad is already displayed on the screen.

The OguryError may provide additional details for the issue. You can access them using following property:

error.Description

Integration Sample

Checkout our sample applications in our GitHub repository :

Banner Example