Working with Ads (Closed Beta)

DoubleClick for Publishers (DFP), AdSense for video (AFV), and AdSense for games (AFG) enable publishers to earn revenue from their rich media content through interactive media ads. The procedures on this page assume you have already created your ads and downloaded and installed the IMA library. Follow the steps below to request and display ads from any VAST-compliant ad server using the IMA Xbox for 360 SDK v3.

There are two different approaches to integrating your player with the IMA SDK. Which one you choose will depend on whether your application uses MMPPF.

MMPPF integration

If your application declares SMFPlayer instance in the xaml as follows:

<core:SMFPlayer Name="Smf" AutoPlay="True">
            <core:SMFPlayer.Playlist>
                <media:PlaylistItem DeliveryMethod="AdaptiveStreaming" MediaAssetId="adaptiveAsset" MediaSource="http://az30243.vo.msecnd.net/ss-video/HawaiiSurfing_H264_EE4_CBR_1080p_Xbox.ism/manifest"/>
            </core:SMFPlayer.Playlist>
        </core:SMFPlayer>

then you can schedule ads in your code as follows:

Smf.ScheduleAdTrigger(adTag, "googleads");

where the value of adTag is a URL that you reveived from the trafficking UI and "googleads" is the format that triggers the loading of our plugin which handles all ads rendering and reporting. That's the only line of code you need to write. ScheduleAdTrigger is a standard SMFPlayer API which has several overloads that allow you to specify the precise time when the ads should be requested (if not set, ads will play immediately). You must reference the following MMPPF DLLs (your application should already be referencing most of them):

  • MMPPF.Core.Xbox
  • MMPPF.Plugins.Advertising.Xbox
  • MMPPF.Plugins.Xbox
  • MMPPF.Utilities.Xbox

Non-MMPPF integration

Follow these procedures:
  1. Requesting Ads
  2. Displaying Ads
  3. Media Selection

Requesting Ads

Complete these steps to request ads from any VAST-compliant ad server.

  1. Create an instance of AdsLoader

    Access the relevant namespace and create an AdsLoader instance by pasting the following code into your application (e.g. the constructor of your application's main page).

    Note: You should use the same ads loader instance to make all ads requests for the same content video.

    using Google.InteractiveAds.Api;
    ...
    private readonly AdsLoader _adsLoader;
    public MainPage()
    {
      InitializeComponent();
      _adsLoader = new AdsLoader();
    }
      
  2. Handle AdsLoader events

    Register event handlers for the AdsManagerLoaded and AdError events found on the AdsLoader instance you just created.

    using Google.InteractiveAds.Api;
    ...
    private readonly AdsLoader _adsLoader;
    public MainPage()
    {
      InitializeComponent();
      _adsLoader = new AdsLoader();
    _adsLoader.AdsManagerLoaded += OnAdsManagerLoaded;
      _adsLoader.AdError += OnAdsLoaderAdError;
    }
    
    private void OnAdsManagerLoaded(object sender, AdsManagerLoadedEventArgs e)
    {
      // Handle displaying ads here.
    }
    
    private void OnAdsLoaderAdError(object sender, AdErrorEventArgs e)
    {
      // Handle error here. (Error information provided in AdErrorEventArgs.)
      _adsLoader.Dispose();
    }
      
  3. Request ads from your networks

    Create an AdsRequest object for each tag you are using and set its size parameters to the dimensions of your video player. This is recommended since ad networks use these parameters for ad selection. Then, use the AdsRequest(...) method on the AdsLoader instance to retreive ads from each network.

    using Google.InteractiveAds.Api;
    ...
    private readonly AdsLoader _adsLoader;
    
    
    // The video player which displays your application's video content.
    private readonly MediaElement _videoPlayer;
    
    
    public MainPage()
    {
      InitializeComponent();
      _adsLoader = new AdsLoader();
       _adsLoader.AdsManagerLoaded += OnAdsManagerLoaded;
      _adsLoader.AdError += OnAdsLoaderAdError;
    
    
      _videoPlayer = new MediaElement();
    
      var adsRequest = new AdsRequest
      {
        AdTagUrl = "ad tag URI goes here.",
        LinearAdSlotHeight = _videoPlayer.ActualHeight,
        LinearAdSlotWidth = _videoPlayer.ActualWidth,
        NonLinearAdSlotHeight = _videoPlayer.ActualHeight,
        NonLinearAdSlotWidth = _videoPlayer.ActualWidth
      };
      _adsLoader.RequestAds(adsRequest);
    }
    
    
    private void OnAdsManagerLoaded(object sender, AdsManagerLoadedEventArgs e)
    {
      // Handle displaying ads here.
    }
    
    private void OnAdsLoaderAdError(object sender, AdErrorEventArgs e)
    {
      // Handle error here. (Error information provided in AdErrorEventArgs.)
      _adsLoader.Dispose();
    }
      
  4. Handle Content Complete

    When your video content has finished playing, call the ContentComplete() method on your AdsLoader instance. This allows AdsLoader to cleanup the session for the content. If there are active ads managers, they will request and play post-roll ads.

    Note: Remember to also dispose of the AdsLoader instance when you are no longer using it or when an error occurs.

    ...
    public MainPage()
    {
      InitializeComponent();
      _adsLoader = new AdsLoader();
      _adsLoader.AdsManagerLoaded += OnAdsManagerLoaded;
      _adsLoader.AdError += OnAdsLoaderAdError;
    
      _videoPlayer = new MediaElement();
    
      _videoPlayer.MediaEnded += OnContentVideoEnded;
    
    
      var adsRequest = new AdsRequest
      {
        AdTagUrl = "ad tag URI goes here.",
        LinearAdSlotHeight = _videoPlayer.ActualHeight,
        LinearAdSlotWidth = _videoPlayer.ActualWidth,
        NonLinearAdSlotHeight = _videoPlayer.ActualHeight,
        NonLinearAdSlotWidth = _videoPlayer.ActualWidth
      };
      _adsLoader.RequestAds(adsRequest);
    }
    ...
    
    private void OnContentVideoEnded(object sender, EventArgs e)
    {
      _adsLoader.ContentComplete();
      _adsLoader.Dispose();
    }
      

Displaying Ads

After requesting and receiving ads from the relevant ad networks (e.g., DoubleClick, DFP, AdSense, VAST-compliant ad servers), use the AdsManager object returned through the AdsLoader.AdsManagerLoaded event to display them. To do this, complete the steps below:

  1. Get the AdsManager

    Once ads have been loaded successfully, the handler method that you added for the AdsManagerLoaded event is called. Get the AdsManager instance from the AdsManagerLoadedEvent by calling the GetAdsManager(...) method found on AdsManagerLoadedEventArgs. In addition, you may optionally specify media selection preferences, by passing an AdsRenderingSettings object. Refer to the Media Selection section below for more information.

    using Google.InteractiveAds.Api;
    ...
    private readonly AdsLoader _adsLoader;
    // The video player which displays your application's video content.
    private readonly MediaElement _videoPlayer;
    private IAdsManager _adsManager;
    
    ...
    
    private void OnAdsManagerLoaded(object sender, AdsManagerLoadedEventArgs e)
    
    {
      var adsRenderingSettings = new AdsRenderingSettings
      {
        // Specify media selection preferences here.
      };
      _adsManager = e.GetAdsManager(adsRenderingSettings);
    }
    
    ...
      
  2. Handle AdsManager events

    There are five important AdsManager events that should be handled by your application in order to correctly deal with ads playback.

    • AdLoaded: Raised when an ad has finished loading. You can use this opportunity to start the ads using the Start method on AdsManager if this is the first ad to be played.
    • ContentPauseRequested: Raised when one or more linear ads are about to be played and your video content must be paused.
    • ContentResumeRequested: Raised when all linear ads have completed and your video content can be resumed.
    • AllAdsCompleted: Raised when there are no more ads to be played. Use this opportunity to dispose of the AdsManager.
    • AdError: Raised when an error occurs when loading or playing an ad.

    Register handlers for each of these events and others if desired. Refer to the IAdsManager interface in the API reference documentation for more information.

    using Google.InteractiveAds.Api;
    ...
    private void OnAdsManagerLoaded(object sender, AdsManagerLoadedEventArgs e)
    {
      var adsRenderingSettings = new AdsRenderingSettings
      {
        // Specify media selection preferences here.
      };
      _adsManager = e.GetAdsManager(adsRenderingSettings);
    
    
      // Register AdsManager event handlers here.
      _adsManager.AdLoaded += OnAdLoaded;
      _adsManager.ContentPauseRequested += OnContentPauseRequested;
      _adsManager.ContentResumeRequested += OnContentResumeRequested;
      _adsManager.AllAdsCompleted += OnAllAdsCompleted;
      _adsManager.AdError += OnAdsManagerAdError;
    }
    
    {
      // Handle error here. (Error information provided in AdErrorEventArgs.)
      _adsLoader.Dispose();
    }
    ...
    
    private void OnAdLoaded(object sender, EventArgs e)
    {
      // Add code to retrieve the ads container and start the ads here.
    }
    
    private void OnContentPauseRequested(object sender, EventArgs e)
    {
      _videoPlayer.Pause();
    }
    
    private void OnContentResumeRequested(object sender, EventArgs e)
    {
      _videoPlayer.Resume();
    }
    
    private void OnAllAdsCompleted(object sender, EventArgs e)
    {
      // Remove AdsContainer from display, unregister from all AdsManager events and dispose AdsManager.
    }
    
    private void OnAdsManagerAdError(object sender, AdErrorEventArgs e)
    {
      // Handle error here. (Error information provided in AdErrorEventArgs.)
    }
    
      
  3. Initialize and play the ads

    We strongly recommend that you invoke _adsManager.Init(...) before starting playback of the content, even if the ad is only to be played in the middle or at the end of your content. This implementation provides flexibility for future compatibility. For example, if an ads rules response is returned from the ad server, you won't have to change your player code. When you are ready to play the ad, attach the _adsManager.adsContainer to your display surface above your video player and invoke _adsManager.start().

    ...
    private void OnAdsManagerLoaded(object sender, AdsManagerLoadedEventArgs e)
    {
      var adsRenderingSettings = new AdsRenderingSettings
      {
        // Specify media selection preferences here.
      };
      _adsManager = e.GetAdsManager(adsRenderingSettings);
      // Register AdsManager event handlers here.
      // For example:
      _adsManager.AdLoaded += OnAdLoaded;
      _adsManager.ContentPauseRequested += OnContentPauseRequested;
      _adsManager.ContentResumeRequested += OnContentResumeRequested;
      _adsManager.AllAdsCompleted += OnAllAdsCompleted;
      _adsManager.AdError += OnAdsManagerAdError;
    
    
      // Initialize AdsManager.
      _adsManager.HandshakeVersion();
      _adsManager.Init(_videoPlayer.ActualWidth, _videoPlayer.ActualHeight, ViewModes.NORMAL);
    }
    
    ...
    private void OnAdLoaded(object sender, EventArgs e)
    {
    
      layoutRoot.Children.Add(_videoPlayer);
      layoutRoot.Children.Add(_adsManager.AdsContainer);
      _adsManager.Start();
    
    }
    ...
      
  4. Dispose of the AdsManager

    When the AdsManager raises the AllAdsCompleted event, you can unregister any event handlers that are attached to the AdsManager and call the Dispose() method on it.

    Note: Remember to unregister from all the AdsManager events for which you previously registered before you dispose it.

    ...
    private void OnAllAdsCompleted(object sender, EventArgs e)
    {
    
      _adsManager.AdLoaded -= OnAdLoaded;
      _adsManager.ContentPauseRequested -= OnContentPauseRequested;
      _adsManager.ContentResumeRequested -= OnContentResumeRequested;
      _adsManager.AllAdsCompleted -= OnAllAdsCompleted;
      _adsManager.AdError -= OnAdsManagerAdError;
      _adsManager.Dispose();
    
    }
    
    private void OnAdsManagerAdError(object sender, AdErrorEventArgs e)
    {
      // Handle error here. (Error information provided in AdErrorEventArgs.)
    
      _adsManager.AdLoaded -= OnAdLoaded;
      _adsManager.ContentPauseRequested -= OnContentPauseRequested;
      _adsManager.ContentResumeRequested -= OnContentResumeRequested;
      _adsManager.AllAdsCompleted -= OnAllAdsCompleted;
      _adsManager.AdError -= OnAdsManagerAdError;
      _adsManager.Dispose();
    
    }
      

Additional details about AdsManager events

Here are some additional tips related to AdsManager events:

  • Register a handler for the AdError event from the to address any errors that may be raised. AdError is raised when a fatal error has occurred, so we recommend that you call .Dispose() on your AdsManager instance within the handler for this event.
  • Register a handler for the ContentPauseRequested and ContentResumeRequested events (on linear ads). These events are raised by the AdsManager for linear ads since they require that the video content be paused while the ad is played. ContentPauseRequested will be dispatched when an ad in linear playback mode is about to begin. ContentResumeRequested will be dispatched when the ad is complete or when the ad changes its playback mode to non-linear. Two examples of this scenario are:
    • when non-linear video ads are overlaid on top of the publisher's video content. In this case, it is best if the content is paused before the ad starts.
    • when a linear ad that is designed to be overlaid on top of the whole video player's visual area is played. In this case, it is best if content is paused before the ad is displayed since it would otherwise hide or block the content. Instead of asking publishers to register handlers for different events for different types of ads, we raise these common events to simplify publisher code.

You can handle additional events, such as events which inform publishers when ads get paused, record impressions or complete, though this is not required. Refer to the IAdsManager interface for the complete list.

Media Selection

If multiple media files are available within a VAST response, properties within AdsRenderingSettings influence which file to select and play.

  • Bandwidth is defined per media file using the Bitrate property, as part of the VAST standard. If your video player can detect or provide bandwidth information, providing this information can help the SDK deliver the best ad experience for your users. To do this, use the Bitrate property and specify a value in kilobits/sec.
  • Use the MediaFormats property to specify a list of the media formats that you want to prioritize for ad media selection and display. This property does not filter down to videos of the specified formats but simply gives them higher priority.
  • The SDK defaults to VideoDeliveryTypes.Streaming media files, but this can be changed by setting the Delivery property to VideoDeliveryTypes.Progressive. If no videos of the specified delivery type are found, the SDK displays videos of any delivery type.

Send feedback about...

IMA SDK for Xbox