Requesting

All requests to retrieve and show ads are done through NimbusAdsManager's Singleton Access Pattern. This Singleton can be accessed through any MonoBehavior.

Banner Ads

Banner Ads

Showing a single Ad can done through the NimbusAdsManager's Singleton Access Pattern via RequestBannerAdAndLoad

using Nimbus.Internal;
using Nimbus.Runtime.Scripts;
using UnityEngine;

public class BannerRequest : MonoBehaviour {
    // The position field is required and used explicitly within the Ads By Nimbus reporting UI. The data in this field 
    // should remain fairly constant and allows you to distinguish ads units within the Nimbus reporting dashboard. 
    private const string NimbusReportingPosition = "banner_ad_unit";
    [Tooltip("Floors can be dynamically set through the Nimbus Dashboard")]
    [SerializeField] private float _bannerAdFloor = 0.00f;

    private NimbusAdUnit _bannerAd;
    private void Start() {
        // This method will call to the Nimbus Exchange and 
        // if an ad was successfully returned it will immediately display it.
        // Storing the ad unit as a class variable allows you to remove the ad by
        // calling it's Destroy Method
        _bannerAd = NimbusManager.Instance.RequestBannerAdAndLoad(NimbusReportingPosition, _bannerAdFloor);
    }
    
    private void OnDisable() {
        _bannerAd?.Destroy();
    }
}

To continuously refresh and display Banner Ads call RequestRefreshingBannerAdAndLoad

using System.Threading;
using Nimbus.Runtime.Scripts;
using UnityEngine;

public class RefreshingBannerRequest : MonoBehaviour {
    // The position field is required and used explicitly within the Ads By Nimbus reporting UI. The data in this field 
    // should remain fairly constant and allows you to distinguish ads units within the Nimbus reporting dashboard. 
    private const string NimbusReportingPosition = "banner_ad_unit";
    [Tooltip("Floors can be dynamically set through the Nimbus Dashboard")]
    [SerializeField] private float _bannerAdFloor = 0.00f;

    // To stop refreshing banner ads or remove them from the screen the source must be cancelled
    private CancellationTokenSource _ctx;
    private void Awake() {
        _ctx = new CancellationTokenSource();
        // This method will call to the Nimbus Exchange and 
        // if an ad was successfully returned it will immediately display it.
        // Banner ads will continuously be refreshed every 30 seconds. If no ad was returned from
        // the Nimbus exchange any currently displayed ads will remain and an attempt to display another
        // ad will be made at the next interval.
        NimbusManager.Instance.RequestRefreshingBannerAdAndLoad(_ctx, NimbusReportingPosition, _bannerAdFloor);
    }
    
    private void OnDisable() {
        _ctx.Cancel();
    }
}

RequestRefreshingBannerAdAndLoad should only ever be called once.

Interstitial Ads

Showing an Interstitial Ad can done through the NimbusAdsManager's Singleton Access Pattern via RequestHybridFullScreenAd. Interstitial ads make use of the Nimbus Hybrid auction. In a Hybrid Auction, static display and video ads compete against each other to fill your placement. This maximizes CPMs and ensures you get the highest fill rates possible. Ads will remain on screen for 5 seconds because a user is allowed to hit the X button and close the ad.

using Nimbus.Internal;
using Nimbus.Runtime.Scripts;
using UnityEngine;

public class FullScreenRequest : MonoBehaviour {
    // The position field is required and used explicitly within the Ads By Nimbus reporting UI. The data in this field 
    // should remain fairly constant and allows you to distinguish ads units within the Nimbus reporting dashboard. 
    private const string NimbusReportingPosition = "interstitial_ad_unit";
    [Tooltip("Floors can be dynamically set through the Nimbus Dashboard")]
    [SerializeField] private float _fullScreenAdFloor = 0.00f;

    private NimbusAdUnit _fullscreenAd;
    private void Start() {
        // This will method will the Nimbus server to return an ad
        // if an ad was successfully returned it will immediately display it
        _fullscreenAd = NimbusManager.Instance.RequestHybridFullScreenAd(NimbusReportingPosition, _fullScreenAdFloor);
    }
    
    private void OnDisable() {
        _fullscreenAd?.Destroy();
    }
}

Requesting For Reward Video Ads

Showing an Interstitial Ad can done through the NimbusAdsManager's Singleton Access Pattern via RequestHybridFullScreenAd. Interstitial ads make use of the Nimbus Hybrid auction. In a Hybrid Auction, static display and video ads compete against each other to fill your placement. This maximizes CPMs and ensures you get the highest fill rates possible. Ads will remain on screen for 5 seconds because a user is allowed to hit the X button and close the ad.

using Nimbus.Internal;
using Nimbus.Runtime.Scripts;
using UnityEngine;

public class RewardedRequest : MonoBehaviour {
    // The position field is required and used explicitly within the Ads By Nimbus reporting UI. The data in this field 
    // should remain fairly constant and allows you to distinguish ads units within the Nimbus reporting dashboard. 
    private const string NimbusReportingPosition = "rewarded_ad_unit";
    [Tooltip("Floors can be dynamically set through the Nimbus Dashboard")]
    [SerializeField] private float _rewardedAdFloor = 0.00f;

    private NimbusAdUnit _rewardedAd;
    private void Start() {
        // This will method will the Nimbus server to return an ad
        // if an ad was successfully returned it will immediately display it
        _rewardedAd = NimbusManager.Instance.RequestRewardVideoAdAndLoad(NimbusReportingPosition, _rewardedAdFloor);
    }
    
    private void OnDisable() {
        _rewardedAd?.Destroy();
    }
}

Decoupled Request and Load

It is possible to call for an Ad from the Nimbus server and display it later (ad caching). It is not recommended. The Nimbus Exchange operates at low latency that can be discussed during the onboarding phase. The reason it is recommended to cache these ads is because Nimbus does not control or own returned ads. As such impression trackers embedded by connected demand partners may expire before an ad can be displayed to a user. It is suggested that if you wish to cache ads to talk to your connected demand partners directly to determine and negotiate expiration times on tracking pixels. So that your system can implement a smart caching system to avoid any revenue loss due to ads being expired.

using Nimbus.Internal;
using Nimbus.Runtime.Scripts;
using UnityEngine;

public class DecoupledRequest : MonoBehaviour {
	private const string NimbusReportingPositionBanner = "banner_ad_unit";
	private const string NimbusReportingPositionInterstitial = "intersitial_ad_unit";
	private const string NimbusReportingPositionReward = "rewarded_ad_unit";
		
	private NimbusAdUnit _bannerAd;
	private NimbusAdUnit _interstitialAd;
	private NimbusAdUnit _rewardedAd;
	private void Start() {
		// ads are requested from the Nimbus Exchange but they are not shown to the user
		_bannerAd = NimbusManager.Instance.RequestBannerAd(NimbusReportingPositionBanner);
		_interstitialAd = NimbusManager.Instance.RequestHybridFullScreenAd(NimbusReportingPositionInterstitial);
		_rewardedAd = NimbusManager.Instance.RequestRewardVideoAd(NimbusReportingPositionReward);
	}


	private void OnEnable() {
		// to show an ad that has been successfully returned from the server call ShowLoadedAd and pass in the 
		// NimbusAdUnit object
		NimbusManager.Instance.ShowLoadedAd(_bannerAd);
		// NimbusManager.Instance.ShowLoadedAd(_interstitialAd);
		// NimbusManager.Instance.ShowLoadedAd(_rewardedAd);
	}
}Decoupled Request and Load

Advanced Requesting

Nimbus is an RTB exchange and as such all communication to Nimbus is done via the Nimbus Open RTB Spec. As such, for those confident in their RTB knowledge we expose two additional methods on the NimbusManager.Instance

public NimbusAdUnit RequestAdAndLoad(string nimbusReportingPosition, BidRequest bidRequest)
public NimbusAdUnit RequestAd(string nimbusReportingPosition, BidRequest bidRequest) 

Noting that each of the above methods takes in a BidRequest object. All accessible data models and fields can be found in the open source nimbus-openrtb repository.

Constructing a 100% valid Nimbus RTB bid request requires understanding of the RTB Nimbus Open RTB Spec and the data models nimbus-openrtb repository. There are a few static helpers to jump start BidRequest objects based on Nimbus ad type. Below are examples of the 4 main static constructor types. For an overview of all the static extensions please examine the RequestBuilder package within the Ads By Nimbus Package in Unity. /Package/Ads By Nimbus/Runtime/Scripts/Nimbus.Internal/RequestBuilder

public static BidRequest ForHybridInterstitialAd(string reportingPosition) 
public static BidRequest ForStaticInterstitialAd(string reportingPosition)
public static BidRequest ForBannerAd(string reportingPosition)
public static BidRequest ForVideoInterstitialAd(string position)

Here is an example of what the ForVideoInterstitialAd expands into, again noting that it's setting many of the required Nimbus RTB fields..

public static BidRequest ForVideoInterstitialAd(string position) {
	var impression = new[] {
		new Imp {
			Video = new Video().Interstitial(),
			Instl = 1,
			Secure = 1,
			Ext = new ImpExt {
				Position = position
			}
		}
	};
	return new BidRequest {
		Imp = impression,
		Format = new Format {
			W = Screen.width,
			H = Screen.height
		}
	};
}

Here is a fuller example using a custom request

using System;
using Nimbus.Internal;
using Nimbus.Internal.RequestBuilder;
using Nimbus.Runtime.Scripts;
using OpenRTB.Request;
using UnityEngine;

public class AdvancedRequest : MonoBehaviour {
	private const string NimbusReportingPosition = "video_interstitial_checkpoint";
	
	// subscribe to events of interest
	private void OnEnable() {
		NimbusManager.Instance.NimbusEvents.OnAdImpression += OnAdImpression;
		NimbusManager.Instance.NimbusEvents.OnAdCompleted += OnAdCompleted;
		NimbusManager.Instance.NimbusEvents.OnAdError += OnAdError;
	}
	
	// unsubscribe to events as clean up
	private void OnDisable() {
		NimbusManager.Instance.NimbusEvents.OnAdImpression -= OnAdImpression;
		NimbusManager.Instance.NimbusEvents.OnAdCompleted -= OnAdCompleted;
		NimbusManager.Instance.NimbusEvents.OnAdError -= OnAdError;
	}
	
	// check if the player crossed a trigger zone 3D
	private void OnTriggerEnter(Collider other) {
		Trigger(other.gameObject);
	}

	// check if the player crossed a trigger zone 2D
	private void OnTriggerEnter2D(Collider2D col) {
		Trigger(col.gameObject);
	}
	
	// Trigger allows for 2d/3d abstraction
	private static void Trigger(GameObject go) {
		if (!go.CompareTag("Player")) return;
		ShowAdToPlayerAtTriggerCheckPointImmediately();
	}

	/// <summary>
	/// Constructs a custom video Interstitial. This differs from calling RequestHybridFullScreenAd as this limits
	/// Nimbus's auction to returning video assets, rather than hybridizing and also returning any winning "static" ads.
	/// Likewise, I'm customizing the request by adding additional RTB data. Also, recall that this differs from calling RequestRewardVideoAdAndLoad.
	/// Returned Video Rewarded ads require that the user watch the video ad to completion, whereas an video interstitial, will allow
	/// a user to skip after 5 seconds.
	/// </summary>
	/// <returns></returns>
	private static BidRequest VideoOnlyInterstitialRequest() {
		// using the NimbusRtbBidRequestHelper package provides extensions on top off the BidRequest object
		var bidRequest = NimbusRtbBidRequestHelper.ForVideoInterstitialAd(NimbusReportingPosition);
		// pass in user data, this is hardcoded as an example
		bidRequest.User = new User {
			Age = 32,
			Gender = "male",
			Yob = 1991
		};
		return bidRequest;
	}
	
	/// <summary>
	/// Calling RequestAdAndLoad sends the RTB data object to Nimbus Servers immediately and if the server
	/// responds with an ad attempts to display it to the user 
	/// </summary>
	private static void ShowAdToPlayerAtTriggerCheckPointImmediately() {
		var bidRequest = VideoOnlyInterstitialRequest();
		NimbusManager.Instance.RequestAdAndLoad(NimbusReportingPosition, bidRequest);
	}
	
	/// <summary>
	/// OnAdError will be invoked anytime the Nimbus Server cannot return an ad
	/// This includes anytime Nimbus returns a No Fill, which means integrated partners
	/// Do not have an ad return at this time
	/// </summary>
	/// <param name="adUnit"></param>
	private void OnAdError(NimbusAdUnit adUnit) {
		Debug.Log($"The Nimbus Auction ID {adUnit.ErrResponse.Id}");
		Debug.Log($"The Nimbus Error Message {adUnit.ErrResponse.Message}");
		Debug.Log($"The Nimbus Nimbus Status Code {adUnit.ErrResponse.StatusCode}");
		if (adUnit.ErrResponse.StatusCode == 400) {
			Debug.Log($"There was a problem with the RTB request data, check the message");
		} else if (adUnit.ErrResponse.StatusCode == 404) {
			Debug.Log($"Integrated partners did not have an ad to return, try again later");
		} else if (adUnit.ErrResponse.StatusCode == 429) {
			Debug.Log($"The request to Nimbus was rate limited");
		} else if (adUnit.ErrResponse.StatusCode == 500) {
			Debug.Log($"There was likely a transient server issue, try again later");
		}
	}
	
	/// <summary>
	/// OnAdImpression is invoked anytime an ad is successfully rendered on screen
	/// </summary>
	/// <param name="adUnit"></param>
	private void OnAdImpression(NimbusAdUnit adUnit) {
		Debug.Log($"The Ad was successfully rendered");
	}

	/// <summary>
	/// OnAdCompleted is invoked when the Interstitial ad is closed. Because Video Interstitial ads can closed
	/// after 5 seconds, we can check the adWasViewedToCompletion to determine if the user watched the entire ad
	/// of closed the ad early. Both states are valid, however perhaps the reward given to the user changes.
	/// </summary>
	/// <param name="adUnit"></param>
	/// /// <param name="adWasViewedToCompletion"></param>
	private void OnAdCompleted(NimbusAdUnit adUnit, bool adWasViewedToCompletion) {
		if (adWasViewedToCompletion) {
			Debug.Log($"The user watched the entire video ad, 10 points given");
		} else {
			Debug.Log($"The user watched the at least 5 seconds of the video ad, 5 points given");
		}
	}
}