Thumbnail Ad

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

Thumbnail Ads are small rectangle ads that are displayed as overlays to your application content. They are closable and draggable by the user, and can be used to (i) monetize your application through new incremental inventories and (ii) push cross-promotion campaigns.

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 Thumbnail 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 Thumbnail 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: Thumbnail Ad on Unity 2018+ versions

If you encounter a black video instead of a normal video playback, this is due to the missinghardwareAccelerated property in the Android manifest. This is required to play HTML5 videos.

[Android] Add hardwareAccelerated property in the Android manifest

Create the following class in the path Assets/Editor

using System.IO;
using System.Text;
using System.Xml;
using UnityEditor.Android;

public class ModifyUnityAndroidAppManifest : IPostGenerateGradleAndroidProject
{

    public void OnPostGenerateGradleAndroidProject(string basePath)
    {
        // If needed, add condition checks on whether you need to run the modification routine.
        // For example, specific configuration/app options enabled

        var androidManifest = new AndroidManifest(GetManifestPath(basePath));

        // Add your XML manipulation routines
        androidManifest.SetHardwareAcceleration();
        androidManifest.Save();
    }

    public int callbackOrder { get { return 1; } }

    private string _manifestFilePath;

    private string GetManifestPath(string basePath)
    {
        if (string.IsNullOrEmpty(_manifestFilePath))
        {
            var pathBuilder = new StringBuilder(basePath);
            pathBuilder.Append(Path.DirectorySeparatorChar).Append("src");
            pathBuilder.Append(Path.DirectorySeparatorChar).Append("main");
            pathBuilder.Append(Path.DirectorySeparatorChar).Append("AndroidManifest.xml");
            _manifestFilePath = pathBuilder.ToString();
        }
        return _manifestFilePath;
    }
}


internal class AndroidXmlDocument : XmlDocument
{
    private string m_Path;
    protected XmlNamespaceManager nsMgr;
    public readonly string AndroidXmlNamespace = "http://schemas.android.com/apk/res/android";
    public AndroidXmlDocument(string path)
    {
        m_Path = path;
        using (var reader = new XmlTextReader(m_Path))
        {
            reader.Read();
            Load(reader);
        }
        nsMgr = new XmlNamespaceManager(NameTable);
        nsMgr.AddNamespace("android", AndroidXmlNamespace);
    }

    public string Save()
    {
        return SaveAs(m_Path);
    }

    public string SaveAs(string path)
    {
        using (var writer = new XmlTextWriter(path, new UTF8Encoding(false)))
        {
            writer.Formatting = Formatting.Indented;
            Save(writer);
        }
        return path;
    }
}


internal class AndroidManifest : AndroidXmlDocument
{
    private readonly XmlElement ActivityElement;

    public AndroidManifest(string path) : base(path)
    {
        ActivityElement = SelectSingleNode("/manifest/application/activity") as XmlElement;
    }

    private XmlAttribute CreateAndroidAttribute(string key, string value)
    {
        XmlAttribute attr = CreateAttribute("android", key, AndroidXmlNamespace);
        attr.Value = value;
        return attr;
    }

    internal void SetHardwareAcceleration(){
        ActivityElement.Attributes.Append(CreateAndroidAttribute("hardwareAccelerated", "true"));
    }
   
}

When you build the project, the script will automatically modify the Android manifest and the video will playback correctly.

Step 3: Load a Thumbnail Ad

The Ogury SDK provides the OguryThumbnailAd object that lets you load, display and control your Thumbnail Ad.

Instantiate a Thumbnail Ad

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

private OguryThumbnailAd _thumbnailAd;

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

void Start() {
    // ...
    _thumbnailAd = new OguryThumbnailAd("ANDROID_AD_UNIT_ID", "IOS_AD_UNIT_ID");
}

OguryThumbnailAd takes the following parameters:

• 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.

Load a Thumbnail Ad

To start loading an ad, call the Load method:

_thumbnailAd.Load();

The ad is loaded with a default max size of 180x180dp(Android)/points(iOS). The max size can be changed by following the instructions in this section.

Since it may take a few seconds to fetch the ad resources (video, image, ...) from the network, you should call the Load 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 OguryThumbnailAd _thumbnailAd;

    void Start() {
        Ogury.Start("ANDROID_ASSET_KEY", "IOS_ASSET_KEY");
        
        _thumbnailAd = new OguryThumbnailAd(
            "ANDROID_AD_UNIT_ID",
            "IOS_AD_UNIT_ID"
        );
        
        // 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 intertitial ad
        _thumbnailAd.Load();
    }
    
}

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

private void Start() {
    _thumbnailAd = new OguryThumbnailAd(
        "ANDROID_AD_UNIT_ID",
        "IOS_AD_UNIT_ID"
    );
    _thumbnailAd.Load(180, 180);
}

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

Step 4: Show a Thumbnail Ad

To display the ad, call the Show method:

_thumbnailAd.Show();

Thumbnail Ads are displayed bottom-right aligned, with a margin of 20 dp on the right and 20 dp on the bottom. More details on how to set the thumbnail position can be found in this section.

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.

By default the Thumbnail Ad remains on screen while the user is navigating between activities(Android)/View Controllers(iOS) of your application.

You can customize where Thumbnail Ads are displayed in this section.

Step 5: 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 Thumbnail Ad, we recommend you to log every events on your OguryThumbnailAd to follow the lifecycle of the Thumbnail 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

Customize Thumbnail Ad size

To customize the size of the Thumbnail Ad, replace your call to the Load method by the following:

_thumbnailAd.Load(maxWidth, maxHeight);

maxWidth and maxHeight parameters define the maximum size that the Thumbnail Ad will take on the screen. Both values are in dp(Android)/points(iOS).

We recommend to use maxWidth = 180 and maxHeight = 180 to improve the readability of the content of the Thumbnail Ad.

Example: when given maxWidth= 180 and maxHeight= 180, the Ogury SDK may decide to display a 16:9 video ad inside. In this case the Thumbnail Ad size will be 180x102 to match the ratio of the 16:9 video.

The following constraints apply on the values you can pass to these parameters:

• maxWidth and maxHeight must not be greater than the size of the screen.

• maxWidthandmaxHeight must be greater than or equal to 101.

• longest side, either maxWidth or maxHeight, must be greater than or equal to

  180.

Check if an ad is ready to be displayed

Call the following method to check if an Thumbnail Ad is ready to be displayed:

_thumbnailAd.Loaded;

If you want to be informed when the ad is ready to be displayed, you can also register to the OnAdLoaded event.

Customize Thumbnail Ad position

To customize the position where the Thumbnail Ad is displayed, replace your call to the Show method by the following:

_thumbnailAd.Show(gravity, xMarginInPoints, yMarginInPoints);

The Show method takes the following parameters:

• gravity : the corner based on which the Thumbnail Ad will be positioned and it can have the following values:

  • OguryThumbnailAdGravity.TopLeft

  • OguryThumbnailAdGravity.TopRight

  • OguryThumbnailAdGravity.BottomLeft

  • OguryThumbnailAdGravity.BottomRight

• xMarginInPoints: distance on the x axis from the gravity corner to the Thumbnail Ad. Value must be in dp(Android)/points(iOS).

• yMarginInPoints: distance on the y axis from the gravity corner to the Thumbnail Ad. Value must be in dp(Android)/points(iOS).

Customize in which page Thumbnail Ad is displayed

Thumbnail Ad remains on screen while the user navigates across the page of your application.

Android

By default, a Thumbnail Ad is displayed in an Activity only if the two first packages of its classname match the two first packages of the classname of the Activity passed as parameter to the show method.

Example: If you pass com.ogury.game.GameActivity as parameter of the show method, the Thumbnail Ad will stay on screen in all the activities in the com.ogury package and all packages at any level under it.

iOS

By default, a Thumbnail Ad is displayed in an ViewController only if this bundle identifier are the main bundle of application.

You can override these default settings using whitelists and blacklists.

[Android] Whitelist packages

You can increase the number of whitelisted packages where Thumbnail Ads are displayed and stay on screen. This can be useful if you have Activity provided by a library like a game engine, in this case you need to whitelist the package associated to this library.

Call the SetWhitelistPackages method to whitelist packages:

_thumbnailAd.SetWhitelistPackages("org.games.ui", "com.settings.activities");

[iOS] Whitelist bundles

You can increase the number of whitelisted bundles where Thumbnail Ads are displayed and stay on screen. This can be useful if you have ViewController provided by a library like a game engine, in this case you need to whitelist the bundle associated to this library.

Call the SetWhitelistBundleIdentifiers method to whitelist bundles:

_thumbnailAd.SetWhitelistBundleIdentifiers("com.example.bundle", "com.example.bundle2");

[Android] Blacklist activities

You can prevent Thumbnail Ads from being displayed on a given Activity by using the SetBlacklistActivities method:

_thumbnailAd.SetBlacklistActivities(
    "com.your.app.TermsAndConditionsActivity", 
    "com.your.app.SettingsActivity");

When the user navigates to an Activity that is not in a whitelisted package or that is explicitly blacklisted, the Thumbnail Ad is hidden and paused. It comes back on the screen when the user navigates back to anActivitythat is allowed.

[iOS] Blacklist View Controllers

You can prevent Thumbnail Ads from being displayed on a given ViewController by using the setBlacklistViewControllors method:

_thumbnailAd.SetBlacklistViewControllers(
    "TermsAndConditionsViewController",
    "SettingsViewController");

When the user navigates to an ViewController that is not in a whitelisted bundle or that is explicitly blacklisted, the Thumbnail Ad is hidden and paused. It comes back on the screen when the user navigates back to a ViewController that is allowed.

Events

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

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

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

The OguryThumbnailAd 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 Thumbnail 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 :

Thumbnail Ad Example