PubMatic Windows SDK Developer Guide

Document created by pubmatic-archivist on Mar 27, 2017Last modified by catherine.racette on Jun 12, 2017
Version 8Show Document
  • View in full screen mode

Introduction

The PubMatic Windows SDK enables developers to incorporate ads into Windows applications. This guide is for engineers who install and configure PubMatic SDK for Windows.

The SDK is completely modular, which provides the following benefits:

  • You can integrate with either single or multiple ad formats at same time.
    This considerably reduces the SDK size.
  • Complete flexibility to choose between PubMatic and Mocean Ad Server

 

Supported Ad Formats

PubMatic Windows SDK supports following ad formats:

  • Banner
  • Interstitial
  • Native
  • Video

 

Additional Features

  • Rich Media MRAID 2.0-compliant Banner ads
  • VAST 3.0-supported Video Ads
  • Dynamic AdFormat

 

More Information

For full working demo of all adformats, refer to the sample app provided with the SDK. Both the sample app and the SDK itself are available in source code.

For Mocean AdServer API, please use the following  link: http://developer.moceanmobile.com/Mocean_Ad_Request_API .

For PubMatic SSP AdRequest specifications, please refer the link: http://developer.pubmatic.com/documentation/http-parameters-details. (Note: Developer needs to request access for PubMatic API link from respective Account Manager.)

 

IAB references for Adtypes:

  1. Banner : http://www.iab.com/guidelines/iab-display-advertising-guidelines/
  2. Native : http://www.iab.com/guidelines/native-advertising/
  3. Video: http://www.iab.com/guidelines/digital-video-ad-serving-template-vast-3-0/

Downloading Windows SDK

System Requirements

  • Desktop/Laptop with Windows 10 OS installed
  • MS Visual Studio 2015 version(with Universal Windows App Development Tools)
  • 100 Mb free disk space

SDK Contents

You can download or clone PubMatic SDK source from following path: https://github.com/PubMatic/pubmatic-sdk-windows. Contents of the git repo are: 
  • PubMatic-Microsoft-SDK/PubMaticSDK -PubMatic SDK library files
  • PubMatic-Microsoft-SDK/Samples - Demo usage and test app
  • SDK/Documentation - Developer Guide

Installing Visual Studio

Download and install Visual Studio before you add the PubMatic Windows SDK. The SDK is distributed as a .dll library.

To install Windows development platform, download and install the Visual Studio 2015 or the latest from Microsoft website.

https://www.visualstudio.com/en-us/downloads#d-express-windows-8?CR_CC=200395106

Refer to these links for detailed information:

https://dev.windows.com/en-us/getstarted

https://msdn.microsoft.com/library/windows/apps/xaml/dn609832.aspx#target_win10

 

Configuring the Windows SDK

Installing the SDK

 

To add the SDK to an application project:

  1. Unzip the SDK zip file in your source code working area.
  2. Open PubMatic's sample app; use one of the following methods:
  • Select the solution file of the application
  • Create a new Universal Windows application in the Visual Studio IDE
  1. To refer your application to the SDK in the application, use one of the following:
  • Add the SDK as a .dll to an application; see Adding the SDK as a .dll
  • Add the Source code of the SDK to application; see Adding the SDK Source Code

Adding the SDK as a .dll

To add the SDK as a .dll to the application:

  1. Right click the References of the application.
  2.  Select the Add Reference option.


  3. Locate the SDK .dll in your workspace.
  4. Click Add Reference.


  5. Select the .dll to reference: After you add the SDK .dll, it is in References in the application project.

    PubMatic SDK reference in the Application Project

 

 

Adding the SDK Source Code

To add the SDK source code to the application:

  1. Select the Solution explorer and add the existing SDK source project into the IDE.
  2. Locate the SDK project from your workspace and select the .csproj file of the SDK. The SDK project and application project are added in IDE.


Adding the SDK project

  1. Add the reference of the SDK project to the application.
  2. Go to: Application -> References -> Add New Reference ->
  3. Browse to the .csproj file of the SDK.
  4. Click OK.

Note: The .csproj file is visible only after you change the file filter to All Type.

 

 

Integrating Ad Formats

Creating an Ad view

Note: This example uses Banner Ads. You can substitute any of the ad formats listed in Supported Ad Formats.

To create an Ad view:

  1. Create an AdRequest object for the chosen ad format; for example, PubMaticBannerAdRequest.
  2. You can set the optional fields of the AdRequest for better user targeting.
    Best Practice: Using more targeting parameters increases the chances of an ad receiving clicks and conversions. You can configure parameters in the request, such as age, gender, ethnicity, city, country, area code and others.
  3. Initialize Ad View/Controller with request and parameters.
  4. Execute the request.

Permissions Requirements

Publishers must enable following permissions in the Package.appxmanifest file of the application.

 

Permissions

             

Capability

Purpose

Internet (Client)

To access the Internet to request ads from the AdServer.

Location

To get Latitude and Longitude for Geo-Targeting

 

Integrating Banner Ads

Banner ads are simple ads displaying an image or text or both. Some ads that support MRAID are interactive. MRAID or RichMedia ads allow user actions like expand/collapse/resize alongwith options to call/sms/calendar events etc.

In the PubMatic SDK, PMBannerAdView represents this category of display ads. PMBannerAdView is basically a Canvas element. So, it can be added independently in the page layout or it can be added to a parent view like UserControl, StackPanel etc to create unique UI experience.

After deciding where to put an ad in your UI:

  1. Create the ad view.
  2. Add the ad view to your page in one of the following ways:
  • Dynamically, by creating the view in code and adding it to a layout
  • In an XML-layout definition

Initializing Banner Ads

Initializing Banner Ads using PubMatic SSP

Banner ads can be created in cs code as well as Xaml code. Below sections show examples using both approaches.

Example: Initializing PMBannerAdView in the .cs file using SSP

    

 PMBannerAdView adView = new PMBannerAdView();

 // Mandatory initialization of ad-tag.

PubMaticBannerAdRequest adRequest =

 PubMaticBannerAdRequest.CreatePubMaticBannerAdRequest("<pubId>", "<siteId>", "<adId>");

                                              

// Set targeting parameters

adRequest.Height = 250;

adRequest.Width = 300;

adRequest.City = "paris";

adRequest.Country = "FR";

adRequest.Gender = Gender.Female;

 

adView.LogLevel = LogLevel.Error;

adView.UpdateInterval = 15;         // Interval to refresh ad.

adView.LocationDetectionEnabled = true;

adView.Execute(adRequest);

// adView is a Canvas. It can be displayed independently or added to another parent control like UserControl, StackPanel etc.

UserControl1.Content = adView;

PMBannerAdView in an XAML File

  1. Import the banner namespace.

             xmlns:PM="using:PubMaticSDK.Banner"

  1. Enter the appropriate values for adId, siteId and pubId.

Example: Initializing PMBannerAdView in an XAML File

    

 

<!-- Ad View Component -->

<PM:PMBannerAdView Name="AdP" Channel="PubMatic" Height ="250" Width ="300" LocationDetectionEnabled ="True" UpdateInterval="15">

                <PM:PMBannerAdView.Resources>

                    <x:String x:Key="pubId">aaaaa</x:String>

                    <x:String x:Key="siteId">bbbbb</x:String>

                    <x:String x:Key="adId">ccccc</x:String>

                </PM:PMBannerAdView.Resources>

          </PM:PMBannerAdView>

 

Initializing PMBannerAdView in a Mocean AdServer

Initialize PMBannerAdView in the.cs file.

Example: Initializing PMBannerAdView in a Mocean AdServer using the .cs file

    

PMBannerAdView adView = new PMBannerAdView();

MoceanBannerAdRequest adRequest = MoceanBannerAdRequest.CreateMoceanBannerAdRequest("<zone_id>");

 

// Optional targeting params

adRequest.Height = 250;

adRequest.Width = 300;

adRequest.Zip = "1233";

adRequest.Keywords = "travel,sports,music";

 

adView.AdFailed += BannerAd_AdFailed; // Failed event delegate

adView.UpdateInterval = 15;                  // Interval to refresh ad.

ad.Execute(adRequest);

// adView is a Canvas. It can be displayed independently or added to another parent control like UserControl, StackPanel etc.

UserControl1.Content = adView ;     

 

Initialize PMBannerAdView in the XAML file

  1. Import the Banner namespace:

xmlns:PM="using:PubMaticSDK.Banner"

  1. Add the following code where the ad will be displayed.
  2. Enter the correct zone ID.

Example: Initialize PMBannerAdView in the XAML file

    

<!-- Ad View Component -->

<PM:PMBannerAdView Name="AdM" Channel="Mocean" Height="250"  Width="300" LocationDetectionEnabled="True" UpdateInterval="15">

    <PM:PMBannerAdView.Resources>

        <x:String x:Key="zone">xxxxxx</x:String>

    </PM:PMBannerAdView.Resources>

</PM:PMBannerAdView>

After this code is executed:

  • The SDK renders the Banner ad for the specified Ad Tag.
  • After rendering the ad, the SDK sends the impression URL.
  • After the initial ad content is displayed, you can continue to invoke the Execute() function manually to refresh the ad content when desired.  However, if you have defined a UpdateInterval as shown in the samples above, this is not necessary. The SDK sets a timer and will automatically download updated ad content for you based on the timer setting.
  • To be notified of Ad failure cases, publishers can provide callback using the AdFailed delegate:

adView.AdFailed += BannerAd_AdFailed;

 

Note You must specify the proper Zone for Mocean and the correct AdTag for PubMatic SSP for ad request to succeed.

 

An example of a well Targeted AdRequest :

    

     ...

MoceanBannerAdRequest adRequest = MoceanBannerAdRequest.CreateMoceanBannerAdRequest("<zone_id>");

adRequest.Width = 300;

adRequest.Height = 250;

adRequest.City = "new york";

adRequest.Country = "US";

adRequest.Age = 21;

adRequest.Area = 12345;

adRequest.Zip = "1233";

adRequest.Ethnicity = "latino";

adRequest.Language = "English";

adRequest.Keywords = "travel,sports,music";

adRequest.Gender = Gender.Male;

 

  // Enable Location detection too.

    adView.LocationDetectionEnabled = true;

 ...

 

Detecting Ad Load Failures

Publisher can provide a function to handle the PMBannerAdView.AdFailed event to listen to Ad Request failure event. Failure can be caused by the following conditions:

  • If no available ad satisfies the current constraints sent to the ad server. This might occur if a particular ad type or minimum size was requested, and no matching ad is available.
  • If the provided ‘zone’ (for Mocean) or ‘ad-tag’ (for PubMatic SSP) does not exist.
  • If all ads scheduled for the requested zone have reach the maximum daily or monthly cap.

You can configure publisher applications by listening for failure messages. Following are commonly used callback functions.

  • AdReceived: invoked when the ad content is inserted into a view for display.
  • AdFailed: invoked if downloading ad content fails for any reason.

 

Example: AdFailed Event

    

...ad = new PMBannerAdView();adRequest = MoceanBannerAdRequest.CreateMoceanBannerAdRequest("<zone_id>");ad.AdFailed += BannerAd_AdFailed; // Failed event delegatead.Execute(adRequest);} //Callback implemented by publisher for failed event.private void BannerAd_AdFailed(object sender, PMBannerAdView.AdFailedEventArgs e){// handle failed case}

Banner Ad Deallocation

Call Dispose() on the ad instance when the ad is no longer required. Usually called during back navigation from a page.

    

protected override void OnNavigatedFrom(NavigationEventArgs e)

{

    if (e.NavigationMode == NavigationMode.Back)

        {

          ad.Dispose();

          ad = null;

         }

    base.OnNavigatedFrom(e);

}

 

Integrating Interstitial Ads

Interstitial ads are full-screen ads displayed at transition points in the application; for example, when the app is launched, or when moving between screens. Interstitial ads always include a Close button. Optionally, you can configure an ad to close automatically after a specified time.

Interstitial ads do not appear in layouts. They are created exclusively in code. Unlike banner ads, interstitial ads cannot use an XAML definition.

Steps:

  1. Create an object of PMInterstitialAdView.
  2. Execute the adrequest. The response is then received, but not yet displayed.
  3. Display the ad. There are two functions for this purpose:
  • ShowInterstitial(): Displays the fetched response as a full screen popup that has a close button.
  • ShowInterstitialForDuration(int t): Displays the fetched response as a full screen popup that closes automatically after ‘t seconds have passed.

The ad stays in front of the activity screen until clicked or dismissed via close icon. An example of creating and displaying an interstitial ad in C# code is shown below:

Note: To request interstitial ads, create an object of  PMInterstitialAdView  

Example:Interstitial Ads

    

PMInterstitialAdViewinterstitialAd = new PMInterstitialAdView ();

MoceanBannerAdRequest adRequest = MoceanBannerAdRequest.CreateMoceanBannerAdRequest("<zone_id>");

interstitialAd.Execute(adRequest);

//Later in code

       int timeduration = 10;

       interAd.ShowInterstitial(); //displayed ad will not close automatically;

… OR

       interAd.ShowInterstitialForDuration(timeDuration); // ad dismisses after 10 secs

Note: An interstitial ad will not be displayed again for the same instance. Create a new object to display the interstitial ad again.

Once the full screen ad is displayed, impression trackers will be initiated. If the user clicks on the ad, click trackers will be fired and landing page will be launched in browser. On returning from browser, the ad will have been removed.

 

Best practices: for better user experience, use interstitial ads judiciously and at logical breaks in apps.

Interstitial Ad Deallocation

Call Dispose() on the ad instance when the ad is no longer required. Usually called during back navigation from a page.

 

Integrating Native Ads

Native ads are the seamless ads that mingle with the surrounding app content so uniformly that it is hard to differentiate between the ad and actual application content.

Use case:

A website that displays a grid of thumbnails for showing movies with picture, title and rating, can display a native ad in the grid with the same format. 

To do this, specify the assets you require for an ad that is, image, title, rating, description, and others.

The SDK provides the requested assets, which are rendered by the developer in the app layout accordingly.

Native ads solve two problems for publishers. One, they do not seem like nuisance sticking out from rest of the content. Second, they are not affected by ad fatigue.

To display Native Ads in your application:

  1. Initialize PMNativeAd.
  2. Use an INativeRequestListener instance to get the callback and assets for native ad request.

Example: Initialize Ad request Listener

    

// Setting Ad request listener

MoceanAdRequestListener moceanNativeAdRequestlistener = new MoceanAdRequestListener(this); 

 

PMNativeAd  ad = new PMNativeAd();

// Setting Ad request listener

ad.SetRequestListener(moceanNativeAdRequestlistener);

// Request for native assets

ad.AddNativeAssetRequestList(GetAssetRequests()); // GetAssetRequests function  described below

 

// Set to use in-app-browser

ad.UseInternalBrowser = true;

// Enable location detection

ad.EnableLocationDetection = true;

 

// Create Mocean native request

NativeAdRequest adRequest = MoceanNativeAdRequest.CreateMoceanNativeAdRequest("<zone_id>");

// Execute the ad request

ad.Execute(adRequest);

Example: Request for native assets

    

private List<PMAssetRequest> GetAssetRequests()

{

List<PMAssetRequest> assets = new List<PMAssetRequest>();

 

// Title asset

PMTitleAssetRequest titleAsset = new PMTitleAssetRequest();

titleAsset.AssetId = REQUEST_TITLE; // Unique assetId is mandatory for each asset

titleAsset.Length = 30;

titleAsset.IsAssetRequired = true; // Optional (Default: false)

assets.Add(titleAsset);

 

// Description text asset

PMDataAssetRequest dataAssetDesc = new PMDataAssetRequest();

dataAssetDesc.AssetId = REQUEST_DATA_DESC;

dataAssetDesc.DataAssetType = DataAssetTypes.DESC;

assets.Add(dataAssetDesc);

 

// Main, Logo and Icon image assets

PMImageAssetRequest imageAssetLogo = new PMImageAssetRequest();

imageAssetLogo.AssetId = REQUEST_IMAGE_LOGO;

imageAssetLogo.ImageType = ImageAssetTypes.Logo;

imageAssetLogo.Width = 50;

imageAssetLogo.Height = 50;

assets.Add(imageAssetLogo);

 

PMImageAssetRequest imageAssetMainImage = new PMImageAssetRequest();

imageAssetMainImage.AssetId = REQUEST_IMAGE_MAIN;

imageAssetMainImage.ImageType = ImageAssetTypes.Main;

imageAssetMainImage.Width = 50;

imageAssetMainImage.Height = 50;

assets.Add(imageAssetMainImage);

 

PMImageAssetRequest imageAssetIcon = new PMImageAssetRequest();

imageAssetIcon.AssetId = REQUEST_IMAGE_ICON;

imageAssetIcon.ImageType = ImageAssetTypes.Icon;

imageAssetIcon.Width = 50;

imageAssetIcon.Height = 50;

 assets.Add(imageAssetIcon);

 

 // Rating bar

PMDataAssetRequest dataAssetRating = new PMDataAssetRequest();

dataAssetRating.AssetId = REQUEST_DATA_RATING;

dataAssetRating.DataAssetType = DataAssetTypes.RATING;

assets.Add(dataAssetRating);

return assets;

}

Example: Make the ad request via chosen platform :

Via Mocean Platform :

    

// Create request for native ad.

MoceanNativeAdRequest adRequest = MoceanNativeAdRequest.CreateMoceanNativeAdRequest("<zone_id>");

// Execute the ad request

ad.Execute(adRequest);

2. Via PubMatic SSP

    

PubMaticNativeAdRequest adRequest = PubMaticNativeAdRequest.CreatePubMaticNativeAdRequest("<pubId>", "<siteId>", "<adId>");

// Execute the ad request

ad.Execute(adRequest);

Example: Receiving Notification from PMNativeAd:

    

async void PMNativeAd.INativeRequestListener.OnNativeAdReceived(PMNativeAd ad)

    {

          if (ad != null) {

                   // Code to render native assets on UI.

                   // Refer NativeSample.cs in Sample App implementation.

                   /* Use this method to tell PubMatic SDK to handle clicks and send the impression trackers as well as click trackers

                    */

         ad.RegisterTrackersForControl(adView); // Important for Monetization 

    }

void PMNativeAd.INativeRequestListener.OnNativeAdFailed(PMNativeAd ad, Exception ex)

    {

        // Code for the failed case.

     }

Rendering Native Ad Response Assets

Native ad responses can return the following information:

  • To render a list of assets, use onNativeAdReceived callback.
  • To get a list of asset types, use the response from ad.GetNativeAssets()in onNativeAdReceived callback method.

For example, a news view flow content will have the following assets:

  • Title: Title of the ad, String
  • Content: Description of the ad, String
  • Landing URL: URL to be opened upon ad click
  • Icon: Icon details such as the URL, height and width in JSON format

NOTE: According to the openRTB native ad specification, the assetId passed in native ad request must match the assetId in response. You can get and render the assets based on the asset IDs that you have passed during the ad request.

Example: Implementing PMNativeAd.INativeRequestListener to render Native Ad Response Assets

    

// Listener for Success/Failure/other events that resulted from a Native Ad request

public class NativeAdRequestListener:PMNativeAd.INativeRequestListener

 {

   Page page;

 

   public NativeAdRequestListener(Page page)

   {

        this.page = page;

   }

  

   async void PMNativeAd.INativeRequestListener.OnNativeAdReceived( PMNativeAd ad)

   {

if (ad != null)

{

List<PMAssetResponse> nativeAssets = ad.GetNativeAssets();

for (int i = 0; i < nativeAssets.Count; i++)

{

   PMAssetResponse asset = nativeAssets.ElementAt(i);

   switch (asset.AssetId)

   {

     case REQUEST_TITLE:

      if (asset is PMTitleAssetResponse)

{

await CoreApplication.MainView.CoreWindow.Dispatcher.RunAsync(CoreDispatcherPriority.Normal,

() =>

{

((NativeSample)this.page).MoceanNativeTitle.Text = ((PMTitleAssetResponse)asset).TitleText;

});

}

break;

case REQUEST_IMAGE_ICON:

if (asset is PMImageAssetResponse)

{

// Code to render icon image ...

PMNativeAd.Image iconImage = ((PMImageAssetResponse)asset).Image;

if (iconImage != null)

{

ImageDownloader.LoadImage(iconImage.GetUrl(), ((NativeSample)this.page).MoceanCTAImage);

}

}

break;

 

case REQUEST_IMAGE_LOGO:

if (asset is PMImageAssetResponse)

{

// Code to render logo image ...

PMNativeAd.Image logoImage = ((PMImageAssetResponse)asset).Image;

if (logoImage != null)

{

ImageDownloader.LoadImage(logoImage.GetUrl(), ((NativeSample)this.page).MoceanLogoImage);

}

}

break;

case REQUEST_IMAGE_MAIN:

if (asset is PMImageAssetResponse)

{

// Code to render main image ...

PMNativeAd.Image mainImage = ((PMImageAssetResponse)asset).Image;

if (mainImage != null)

{

ImageDownloader.LoadImage(mainImage.GetUrl(), ((NativeSample)this.page).MoceanNativeImage);

}

}

break;

case REQUEST_DATA_DESC:

if (asset is PMDataAssetResponse)

{

await CoreApplication.MainView.CoreWindow.Dispatcher.RunAsync(CoreDispatcherPriority.Normal,

() =>

{

((NativeSample)this.page).MoceanNativeDescription.Text = ((PMDataAssetResponse)asset).Value;

});

}

break;

case REQUEST_DATA_RATING:

if (asset is PMDataAssetResponse)

{

await CoreApplication.MainView.CoreWindow.Dispatcher.RunAsync(CoreDispatcherPriority.Normal,

() =>

{

((NativeSample)this.page).MoceanSymbolIcon1.Symbol = Symbol.SolidStar;

});

}

break;

}

}

// Register UIControl for click trackers

ad.RegisterTrackersForControl(((NativeSample)this.page).NativeAd);

}

}

Deallocating PMNativeAd

Deallocation frees memory that was previously used by the PMNativeAd.

Example: Deallocating PMNativeAd

    

protected override void OnNavigatedFrom(NavigationEventArgs e)

{           

     if (e.NavigationMode == NavigationMode.Back)

     {

          // Remove any Native Ad request (pending or not)

          if (nativeAd != null)

              nativeAd.Dispose();

     }

}

Note: Mocean and PubMatic SSP channels use the same native ad requesting process, except for the NativeAdRequest object types.

 

Objects (Channels) for PubMatic SSP and Mocean

           

Object/Channel

PubMatic SSP

Mocean

AdRequest

PubMaticNativeAdRequest

MoceanNativeAdRequest

 

Integrating Video Ads

Video Ads are the most profitable and engaging ads. PubMatic SDK supports IAB VAST 3.0 specifications. The AdPod feature is not currently available.

There are several ways to integrate video ads with applications that have videoPlayer. PubMatic supports the following video ad components:

  1. Linear Ads: Video ads that are played inline in the player itself. It is a short video clip that can be played before, after, or in-between the master content (application’s media file). Video ads can be pre-, mid-, or post-roll.
  2. Non-Linear Ads: These are like banner ads that are displayed as an overlay above the master content. A Close button is rendered to enable the dismiss function.
  3. Companion Ads: These ads are displayed in the views in vicinity of the main player. Their content is related to the linear or non-linear ads.

You can configure applications to display any or all ad categories. When video AdRequest is successful, it receives the components requested by the application. In the VideoAdReceived callback, the application must supply reference to the views that display the corresponding component.

Initializing PMVideoAdManager

 

PMVideoAdManager must be initialized to request the video ads, as shown in the sample code.

1. Initialize channel-specific video AdRequest object with the correct Adtag parameters.

a. Via Mocean AdServer :

    

MoceanVideoAdRequest adRequest = new MoceanVideoAdRequest("<zone_id>");

 

b. Via PubMatic SSP:

 

    

PubMaticVideoAdRequest adRequest = new PubMaticVideoAdRequest("<pubId>", "<siteID>", "<adId>");

2. Set targeting parameters in the video adRequest object:

    

adRequest.VideoAdFormat = PubMaticVideoAdRequest.VIDEO_AD_FORMAT.VAST2;

adRequest.VideoDurationMin = 1;

adRequest.VideoDurationMax = 25;

adRequest.VideoType = PubMaticVideoAdRequest.VIDEO_TYPE.ANY;

3. Implement the interface IVideoAdListener object and implement its method (explained in next topic):IVideoAdListener

    

PMVideoAdListener videoAdListener = new PMVideoAdListener (this);

4. Execute the ad request:

    

PMVideoAdManager vAdManager = new PMVideoAdManager(videoAdListener);

vAdManager.UseInternalBrowser = true;

try

{

     vAdManager.Execute(adRequest);

}

catch (Exception ae)

{

 // Handle exception here. 

}

5. Receiving Notification from PMVideoAdManager via IVideoAdListener:   

IVideoAdListener relays application events, such as success or failure.

Example: Implementing IVideoAdListener

    

 IVideoAdListener implementation:

    public class PMVideoAdListener : IVideoAdListener

    {

...

public void OnVideoAdReceived(PMVideoAdManager adManager)

{

// Setup Video Ad parameters here.

VAdParams adParams = new VAdParams();

// Linear Ad

adParams.VideoViewInfo = new LinearViewInfo();

adParams.VideoViewInfo.Container = adPage.PubMaticVideoPlayerContainer;

 

// Non-Linear Ad

adParams.NonLinearInfo = new NonLinearViewInfo();

adParams.NonLinearInfo.ParentView = adPage.PubMaticVideoPlayerNonLinearContainer;

adParams.NonLinearInfo.Width = 300;

adParams.NonLinearInfo.Height = 50;

 

//Companion Ad

List<CompanionViewInfo> companionViewInfoList = new List<CompanionViewInfo>();

CompanionViewInfo companionContainer = new CompanionViewInfo();

companionContainer.ParentView = adPage.PubMaticVideoPlayerCompanionContainer;

companionContainer.Width = 730;

companionContainer.Height = 100;

companionViewInfoList.Add(companionContainer);

adParams.CompanionViewInfoList = companionViewInfoList;

 

adManager.Init(adParams);

  }

 

public void OnContentPause()

{

  //Pause the master content. Master content player will be replaced by video ad player.

this.adPage.contentPlayer.Pause();

}

 

public void OnContentResume()

{

  //Add the master content player back to your container & resume the master content.

this.adPage.PubMaticVideoPlayerContainer.Content = this.adPage.contentPlayer;

this.adPage.contentPlayer.Play();

}

 

public bool OnOverrideCompanionHandling()

{

     return false;

}

 

public void OnRenderCompanionAds(List<Companion> companionList)

{

   //Render companion ads from companionList

}

 

public void OnThirdPartyRequest()

{

   ...

}

 

public void OnVideoAdEvent(PMVideoAdManager adManager, AD_EVENT adEvent)

{

switch (adEvent)

{

case AD_EVENT.AD_LOADED:

//Call PlayAd() on PMVideoAdManager object.

adManager.PlayAd();

break;

case AD_EVENT.AD_STOPPED:

//Ad stopped. Add the master content player back to your container & resume the master content.

this.adPage.PubMaticVideoPlayerContainer.Content = this.adPage.contentPlayer;

this.adPage.contentPlayer.Play();

break;

}

}

 

public void OnVideoAdFailed(PMVideoAdManager adManager, Exception exception)

{

  //Handle video ad failure.

}

}

Components of all Adtypes

Following are a list of components that are in all Adtypes.

Unique Device ID

Unique Device ID (UDID). This parameter is required by the adServer for proper targeting of the user. This device ID is determined by the SDK internally on behalf of the Publisher, and its MD5 value is appended to the adRequest before sending.

In Windows, an App Specific Hardware ID (ASHWID) generates a constant identifier on per-app per-device basis ASHWID can be affected by addition or removal of various system parts. In the SDK, only the BIOS part of the ID is used to maintain a constant ID.

 

Windows Advertising ID

The Windows Advertising ID is queried internally by the SDK and appended to the ad request. This feature can be enabled or disabled, based on the feature setting the user has selected on their device.  If the user resets this features, a different Advertising ID is retrieved the next time it is enabled.

 

Detecting Location

The SDK provides an API call for geo-targeting in all adView configurations.

adView.EnableLocationDetection = true;

Above code enables the SDK to start the GeoLocator and get the Latitude-Longitude information from device GPS.

Best practice: PubMatic recommends enabling GeoLocator for better targeting and hence better fill-rate and monetization.

 

If the application itself uses GeoLocation, this feature need not be enabled. The publisher can simply pass the Location information in SetLocation(double latitude, double longitude)function of the AdRequest object.

For example:

adRequest.SetLocation(18.437645,73.625344);

Note: (For PubMatic channel only) - In case publisher provides the location data, then he must set LocationSource field correctly. Otherwise default value of LocationSource is considered as ‰ЫчUser_Provided‰ЫЄ.

 

In-App Browser

SDK provides API for an In-App Browser.

     adView.UseInternalBrowser = true;

If set to true, when the user clicks on an ad, the user remains within the app, and the link is opened in the custom browser page provided by the SDK.

If the in-App Browser is false, the links are opened normally in the native browser in the device, after leaving the app context.

 

Logging

SDK provides logging api to print out the logs pertaining to each ad format on the visual studio console. There are three levels of reporting provided by the enum ‰ЫчPubMaticSDK.Common.LogLevel‰ЫЄ namely None, Debug and Error. Developer can get helpful information in case of errors by using this feature.

For example,

                adView.LogLevel = LogLevel.Error;

 

Ad Request Parameters

Common Parameters

Best Practices: Although it is not mandatory to pass extra targeting information in ad request, PubMatic highly recommends passing this information for better monetization.  Extra targeting information passed in the ad request often leads to demand partners bidding higher for such impressions.

 

Platform-Independent Parameters

These parameters can be used regardless of which platform (SSP or Mocean Ad Server) is being used.

                                                             

Parameter

Mandatory

Description

Example

Country

No

Two letter country code in the ISO 3166 format. It overrides a country code detected by IP.

US

City

No

City of the user.

new york

Dma

No

Designated market area (DMA) code of the user. This field is applicable for US users only

734

Zip

No

Home zip code if the visitor is present in the U.S; otherwise, it indicates the postal code.

411045

Gender

No

Gender of the visitor. Possible values are provided in enum in SDK.

Male

Ethnicity

No

Ethnicity of user. Possible values are provided in enum in SDK.

Asian

Language

No

User's preferred Language.

English

Carrier

No

Wireless Carrier Name

Verizon

Keywords

No

A comma-separated list of keywords indicating the consumer's interests or intent.

music, games

 

Mocean Parameters

Mocean AdServer

 

Sample initialization:

MoceanBannerAdRequest adRequest = new MoceanBannerAdRequest.CreateMoceanBannerAdRequest("<zone>");

adRequest.City = "new york";

adRequest Age = 27;

 

Mocean Server AdRequest parameters

                                                                     

Parameter

Mandatory

Description

Example

ZoneId

Yes

Zone Id of the publisher. (accepted as constructor parameter. Cannot be changed later. )

12345

Height

No

Height of the ad.

250

Width

No

Width of the ad.

300

Timeout

Yes*

Timeout of ad call in milliseconds. This is the maximum time you are willing to wait for an ad response from the ad server.

Default is 3000.

3

Age

No

Age of the user.

28

Income

No

User's income or income range in dollars (integers).

50000 or 50000-75000

Area

No

Area code of a user.

212

Region

No

Country subdivisions (for example, regions, provinces or states) in the ISO 3166-2 format.

NY

VideoProtocol

No

Video protocol version for video ads to be served: 
• "0" - VAST 2.0; 
• "1" - VAST 3.0. 
This parameter overrides zone level settings. 

0

Test

No

Set to true to serve ads in a test mode. Please note that in a test mode only creative which refers to a test order can be served. Default value is false.

1

 

PubMatic Parameters

 

Sample Initialization 

 

PubMaticBannerAdRequest adRequest = PubMaticBannerAdRequest.CreatePubMaticBannerAdRequest("aaa", "bbb", "ccc");

adRequest.BirthYear = “1975”;

adRequest.Income = “30000”;

Parameters specific to an AdRequest to the PubMatic SSP: 

                                                                                                                                       

Parameter

Mandatory

Description

Example

PubId

Yes

ID of the publisher. This value can be obtained from the pubId parameter in the PubMatic ad tag.

(accepted as constructor parameter. Cannot be changed later. )

1234

SiteId

Yes

ID of the publisher's Web site. A publisher can have multiple sites. This value can be obtained from the siteId parameter in the PubMatic ad tag.

(accepted as constructor parameter. Cannot be changed later. )

56783

AdId

Yes

ID of the ad's placement. A site can have multiple ad placements or positions which have the same or different ad sizes. AdId is the unique identifier for such an ad placement and this value can be obtained from the adId parameter in the PubMatic ad tag.

(accepted as constructor parameter. Cannot be changed later. )

341133

Height

No

Height of the ad.  Note: For native ad format, sizes for native assets (not for ad) are provided. This is an optional parameter.

250

Width

No

Width of the ad. Note: For the native ad format, sizes for native assets (not for ad) are provided. This is an optional parameter.

300

LocationSource

Yes*

Source of user's mobile device's location as provided in the Location parameter. 

Possible values are provided as options in enum.

Note: This parameter is mandatory only if the Location parameter is provided. This field has no significance if Location data (lat,long) is not given by publisher.

GPS

AdOrientation

No

ID of the ad orientation for the given ad request.

 

State

No

State of the user.

NY

AdRefreshRate

No

This parameter is used to specify the time interval (in seconds) after which the ad is refreshed.

By default, this time interval is set to 0 seconds. Therefore, the ad does not get refreshed automatically. This value should be in the range of 12 to 120 seconds.

0

BirthYear

No

Visitor's birth year as a four-digit integer.

1976

Income

No

User's income or income range in dollars (whole numbers).

 50000 or 50000-75000

IABCategory

No

List of IAB content categories for the overall site/application. If the site/application falls under multiple IAB categories, you can send categories separated by comma, and the string should be URL encoded.

IAB1%2CIAB-5%2CIAB1-6

Coppa

No

Indicates whether the visitor is COPPA-specific or not. For COPPA (Children's Online Privacy Protection Act) compliance, if the visitor's age is below 13, then such visitors should not be served targeted ads.

Possible options are:

  • 0 - Indicates that the visitor is not COPPA-specific and can be served targeted ads.
  • 1 - Indicates that the visitor is COPPA-specific and should be served only COPPA-compliant ads.

1

OrmmaComplianceLevel

No

Minimum compliance level. Possible values are 0, 1 and 2.

0

DoNotTrack

No

Indicates whether the user has opted out of the publisher or not, or whether HTTP_DNT is set or not. Possible values are: true or false.

false

Aid

No

Mobile application's ID on the exchange

 

AppName

No

Name of the mobile application. This value should be same as that mentioned on the application (app) store.

 

AppCategory

No

Application primary category as displayed on storeurl page of the Windows Store.

 

StoreURL

No

URL of the app store from where a user can download this application.

 

Paid

No

Indicates whether the mobile application is a paid version or not. Possible values are:

  • 0 - Free version
  • 1 - Paid version

0

AppDomain

No

Indicates the domain of the mobile application

 

 

Native-Specific Parameters

Most native-specific parameters are automatically added by the SDK. A few are not mandatory; the client will add them if needed.

Asset Objects

Asset objects are the main container object for each asset requested.

8 Main Container Objects for each Asset

                                 

Parameter

Mandatory

Description

AssetId

Yes

Asset ID to map with the creative assets.

IsAssetRequired

No

Flag to check if asset is required or optional

title

No

Title object for title assets. Refer to the Title Objectdefinition.

img

No

Image object for image assets. Refer to the Image Object definition.

data

No

Data object for ratings, prices etc.  Refer to the Data Object definition.

 

Title Object

The Title object is used for the title element of the Native Ad.

           

Parameter

Mandatory

Description

Length

Yes

Maximum length of the text in the title element.

 

Image Object

The Image object to be used for all the image elements of the Native ad such as Icons, Main Image, and others.

                                 

Parameter

Mandatory

Description

ImageType

No

Type ID of the image element supported by the publisher. The publisher can display this information in an appropriate format. Possible values : Icon, Logo, Main

Width

No

Width of the image in pixels.

MinWidth

No but recommended

The minimum requested width of the image in pixels.  This option should be used for any rescaling of images by the client.  Either w or wmin should be transmitted. If w is included it should be considered an exact requirement.

Height

No

Height of the image in pixels.

MinHeight

No but recommended

The minimum requested height of the image in pixels.  This option should be used for any rescaling of images by the client. Either h or hmin should be transmitted. If hmin is included it should be considered an exact requirement.

 

Data Object

The Data Object is to be used for all non-core elements of the native unit such as Ratings, Review Count, Stars, Download count, descriptions etc.

                  

Parameter

Mandatory

Description

DataAssetType

Yes

Type ID of the element supported by the publisher. The publisher can display this information in an appropriate format.  Choose  value from DataAssetTypes  enum provided in SDK.

Length

No

Maximum length of the text in the element’s response.

 

Video-Specific Parameters 

                                                                                             

Parameter

Mandatory

Description

Example

VideoType

No

Type of video. Possible values are:

  • 0 - Any type
  • 1 - Linear
  • 2 - Overlay

Note: Its default value is 0.

1

VideoPosition

No

Position of the ad to be displayed. Possible values can be chosen from enum VIDEO_POSITION

  • ANY
  • PRE_ROLL
  • IN_ROLL
  • POST_ROLL

PRE_ROLL

VideoDurationMin

No

Minimum duration (in seconds) of the video clip.

10

VideoDurationMax

No

Maximum duration (in seconds) of the video clip.

30

RequestCompanion

No

Whether companion ads must be requested.

 

VideoBitRateMin

No

Minimum bitrate (in kbps) allowed for the video stream.

300

VideoBitRateMax

No

Maximum bitrate (in kbps) allowed for the video stream.

600

VideoStreamFormat

Yes

Acceptable video streaming formats. It is a combination of the following values separated by +:

  • 0 - All
  • 1 - video/mp4
  • 2 - application/swf
  • 3 - video/wmv
  • 4 - video/h264
  • 5 - video/webm
  • 6 - application/javascript
  • 7 - video/ogg

1+4

CompanionWidth

Highly recommended

Width (in pixels) of the companion ad. Note: Its default value is 300.

300

CompanionHeight

Highly recommended

Height (in pixels) of the companion ad.
Note: Its default value is 250.

250

VideoAdFormat

Yes

Video ad format (VAST version) supported as per the IAB standards in response. Possible options are:

  • 1 - VAST 1.0 (unsupported)
  • 2 - VAST 2.0
  • 3 - VAST 3.0

2

VideoAdAPI

No

API version for VPAID

VPAID1

VideoContext

No but Highly recommended

Contextual information about the Web page serving the ad. This partner-dependent data can be encoded and has to be passed to the demand side for Brand Safety or used internally for blocking lists

 

VideoPlayback

Yes

List of allowed playback methods. If blank, assume that all are allowed. Possible values are as follows:

  • 1 - Auto-play sound on
  • 2 - Auto-play sound off
  • 3 - Click-to-play
  • 4 - Mouse-over

1+3

 

Dynamic Ad Integration

Dynamic or FreeForm ads is a new feature supported by the PubMatic Windows SDK.
 

An ad-slot always showing the same type of ad can get boring sometimes. Also if the adFormat is fixed, then it is possible that the application is missing out on better monetization provided by a different adFormat at that instance of time.

To overcome this, PubMatic provides the dynamic ads concept. It provides flexibility in the adFormat selected for display in an ad-slot. Same slot can now display random ads (Banner/RichMedia/Native/Video) with a single adRequest on the same zone id.

Benefits

  • This feature can help publisher to get the highest eCPM ad available at any particular moment using a single request to the server.
  •  This also avoids the hassles of updating the application code in future, if a different adFormat is desired.
  • Developer can specify their choice of ads via the ‰ЫПType‰Ыќ field.

Note:  As of now, dynamic ads are supported via Mocean AdServer only.

 

Basic steps for implementing Dynamic ads: 

Publisher app must contain a blank UserControl of desired size and pass it to the SDK which in turn renders ad in this control.

Create an instance of PMDynamicAdManager and pass the UserControl in which the ads must be displayed.

    

 

 PMDynamicAdManager dynamicAd = new PMDynamicAdManager(<UserControl1>);

 

  1. Create an instance of MoceanDynamicAdRequest.
    1. Set mandatory params i.e. zone.
    2. Set the Type field as per desired ad formats.

       // In case only native and video are required.

 adRequest.Type = AdType.Native | AdType.Video;    

Note: By Default, all adFormats are included for request, if Type field is not set.

    

 

    MoceanDynamicAdRequest adRequest = new    MoceanDynamicAdRequest("<zone>");

    adRequest.Width = (int)DynamicAdView.Width;

    adRequest.Height = (int)DynamicAdView.Height;

    adRequest.Type = AdType.NATIVE | AdType.VIDEO;

 

Set relevant listeners: In case Video or Native type is included as desired ads for dynamic slot, developer must set corresponding listeners to enable SDK data interaction.

    

 

// Setting Ad request listener.

 dynamicAd.NativeAdListener = new NativeAdRequestListener(this);

 

// Request for native assets. Supply an instance of    List<PMAssetRequest>

 dynamicAd.AddNativeAssetRequestList(GetAssetRequests());

 

// Setting IVideoListener for Video.

  DynamicVideoAdListener videoAdListener = new DynamicVideoAdListener(this);

  dynamicAd.VideoAdListener = videoAdListener;

Note:

 

Execute the AdRequest.

    

 dynamicAd.Execute(adRequest);

 

Caching & Deallocating Ads

To provide proper user experience, the ads must maintain state while going on forward path in an app while they must be disposed when going back from a page.

For example, if a user is viewing a video ad, and he clicks the ad after watching it for 10 seconds, the control will move to the browser page. But now when he returns back, the ad must pick up where he left.

 

Enable Cache

Windows 10 SDK, by default clears the page state as soon as the user moves away from it. Thus, all the ads will be removed when moving forward as well as backward by default.
To avoid it, developer must enable NavigationCacheMode in the Xaml page where the ads will be displayed.

    

  <Page

         x:Class="Samples.AdPages.VideoSample"

        ...       

        NavigationCacheMode="Enabled">

 

Deallocation

To conserve memory usage, the adViews must be disposed when moving backwards. For this, override the Navigation callbacks and dispose ads as follows.

    

   protected override void OnNavigatedFrom(NavigationEventArgs e)

   {

      if (e.NavigationMode == NavigationMode.Back)

            {

                bannerAd.Dispose();          //bannerAd is PMBannerAdView instance

                BannerAdControl.Content = null; //remove from UserControl

            }

   }

Best Practice: It is recommended that the Windows Page Navigation events ‰ЫТ OnNavigatedTo and OnNavigatedFrom be used for ad creation and ad dispose respectively.

 

Events in AdFormat

This Appendix lists available events in each AdFormat.

Banner

Following are the various events, related to banner and RichMedia ads, available to the developer to listen to and override if required.

 Banner Event Names

                                                                    

EventName

Delegate

Description

AdReceived

EventHandler

Event triggered when the SDK receives and renders an ad.

AdFailed

public delegate void AdFailedEventHandler(object sender, AdFailedEventArgs e);

Event triggered when the SDK fails to receive or render an ad.

OpeningURL

public delegate void OpeningURLEventHandler(object sender, OpeningURLEventArgs e);

Event triggered when user action with the SDK will invoke opening a URL.

InternalBrowserOpened

EventHandler

Event triggered when the SDK opens the internal browser.

CloseButtonPressed

EventHandler

Event triggered when the close button on an expanded interstitial ad is pressed

AdExpanded

EventHandler

Event triggered when a rich media ad is expanded.

AdResized

EventHandler

Event triggered when a rich media ad is resized.

AdCollapsed

EventHandler

Event triggered when a  rich media ad is expanded or resized is collapsed

LeavingApplication

EventHandler

Event triggered when user interaction with an ad causes the SDK to invoke another Windows application for example, browser/phone.

PlayingVideo

public delegate void PlayingVideoEventHandler(object sender, PlayingVideoEventArgs e);

Event triggered when a rich media ad requests playing of a video.

SavingCalendarEvent

public delegate void SavingCalendarEventEventHandler(object sender, SavingCalendarEventEventArgs e);

Event triggered when a rich media ad requests saving a calendar event to the user's calendar.

SavingPhoto

public delegate void SavingPhotoEventHandler(object sender, SavingPhotoEventArgs e);

Event triggered when a rich media ad requests saving a photo to the user's media library.

 

Native

Native AdRequest results are provided by PMNativeAd.INativeRequestListener.

Functions in INativeRequestListener

                     

Function

Description

OnNativeAdReceived

AdRequest success callback. The response with the requested assets is made available via the argument PMNative object.

OnNativeAdFailed

AdRequest failure callback. Override this to get the failure exception.

OnReceivedThirdPartyRequest

SDK calls this function when a mediation ad is received. This feature is not in current scope.

OnNativeAdClicked

Click Event when a native ad is clicked.

 

Video

Video AdRequest from PMNativeAd.INativeRequestListener

                                       

Function

Description

OnContentPause

SDK will call this function before playing the video ad. The application should pause the master content on this function call.

OnContentResume

SDK will call this function on completion of video ad. Application should resume the master content on this function call.

OnOverrideCompanionHandling

SDK will call this function to check whether the application wants to handle the Companion ads or not. SDK will render the Companion ads, if the application returns false.

OnRenderCompanionAds

Event invoked when companion ads are rendered.

OnVideoAdEvent

Notifications for various ad events, such as loaded, played, or stopped.

OnVideoAdFailed

AdRequest failure callback.

OnVideoAdReceived

Video Ad received callback.

OnThirdPartyRequest

SDK will call this function in case of mediation ad received. This feature is not in current scope.

 

Dynamic

Following are the various events, related to Dynamic ads, available to the developer to listen to and override if required.

Dynamic Ad Event Names

                                                          

EventName

Delegate

Description

DynamicAdFailed

public delegate void AdFailedEventHandler(object sender, AdFailedEventArgs e);

Event triggered when the SDK fails to receive or render a dynamic ad.

BannerAdReceived

EventHandler

Event triggered when the SDK receives and renders a banner as response for dynamic ad.

BannerOpeningURL

public delegate void OpeningURLEventHandler(object sender, OpeningURLEventArgs e);

Event triggered when user action with the banner ad (in dynamic slot) will invoke opening a URL.

BannerCloseButtonPressed

EventHandler

Event triggered when the close button on an expanded/interstitial ad (in dynamic slot) is pressed

BannerAdExpanded

EventHandler

Event triggered when a rich media ad (in dynamic slot) is expanded.

BannerAdResized

EventHandler

Event triggered when a rich media ad (in dynamic slot) is resized.

BannerAdCollapsed

EventHandler

Event triggered when a rich media ad (in dynamic slot) is expanded or resized is collapsed

RichMediaPlayingVideo

public delegate void PlayingVideoEventHandler(object sender, PlayingVideoEventArgs e);

Event triggered when a rich media ad (in dynamic slot) requests playing of a video.

RichMediaSavingCalendarEvent

public delegate void SavingCalendarEventEventHandler(object sender, SavingCalendarEventEventArgs e);

Event triggered when a rich media ad (in dynamic slot) requests saving a calendar event to the user's calendar.

RichMediaSavingPhoto

public delegate void SavingPhotoEventHandler(object sender, SavingPhotoEventArgs e);

Event triggered when a rich media ad (in dynamic slot) requests saving a photo to the user's media library.

 

Apart from above events, the events related to native and video ads can be subscribed via the respective listeners. Functions in the listener interface are same as listed out in sections Native and Video respectively in the same appendix.

 

Targeting AdRequest Parameters

 

Following is a list of adrequest parameters that are available to the publisher to provide better targeting and provide relevant ads that are to the user.

Common Parameters

Platform-independent Parameters

                                                             

Parameter

Mandatory

Description

Example

Country

No

Two letter country code in the ISO 3166 format. It overrides a country code detected by IP.

US

City

No

City of the user.

New York

Dma

No

Designated market area (DMA) code of the user. This field is applicable for US users only

734

Zip

No

Home zip code if the visitor is present in the U.S; otherwise, it indicates the postal code.

411045

Gender

No

Gender of the visitor. Possible values are provided in enum in SDK.

Male

Ethnicityе_е_е_е_

No

Ethnicity of user. Possible values are provided in enum in SDK.

Asian

Language

No

User's preferred Language.

English

Carrier

No

Wireless Carrier Name

Verizon

Keywords

No

A comma-separated list of keywords indicating the consumer's interests or intent.

music, games

 

Mocean AdServer

Sample initialization

MoceanBannerAdRequest adRequest = new MoceanBannerAdRequest.CreateMoceanBannerAdRequest("<zone>");

adRequest.City = "new york";

adRequest Age = 27;

 

Mocean Server AdRequest parameters

                                                                     

Parameter

Mandatory

Description

Example

ZoneId

Yes

Zone Id of the publisher. (accepted as constructor parameter. Cannot be changed later. е_)

12345

Height

No

Height of the ad.

250

Width

No

Width of the ad.

300

Timeout

Yes*

Timeout of ad call in milliseconds. This is the maximum time you are willing to wait for an ad response from the ad server.

Default is 3000.

3

Age

No

Age of the user.

28

Income

No

User's income or income range in dollars (integers).

50000 or 50000-75000

Area

No

Area code of a user.

212

Region

No

Country subdivisions (for example, regions, provinces or states) in the ISO 3166-2 format.

NY

VideoProtocol

No

Video protocol version for video ads to be served: 
‰Ыў "0" - VAST 2.0; 
‰Ыў "1" - VAST 3.0. 
This parameter overrides zone level settings. 

0

Test

No

Set to true to serve ads in a test mode. Please note that in a test mode only creative which refers to a test order can be served. Default value is false.

1

 

PubMatic SSP

Sample Initialization:

PubMaticBannerAdRequest adRequest = PubMaticBannerAdRequest.CreatePubMaticBannerAdRequest("<pubId", "<siteId>", "<adId>");

    

adRequest.BirthYear = ‰ЫП1975‰Ыќ;

adRequest.Income = ‰ЫП30000‰Ыќ;

adrequest.City = ‰ЫПparis‰Ыќ;

 

Parameters specific to an AdRequest to the PubMatic SSP

                                                                                                                                       

Parameter

Mandatory

Description

Example

PubId

Yes

ID of the publisher. This value can be obtained from the pubId parameter in the PubMatic ad tag.

(accepted as constructor parameter. Cannot be changed laterе_. )

1234

SiteId

Yes

ID of the publisher's Web site. A publisher can have multiple sites. This value can be obtained from the siteId parameter in the PubMatic ad tag.

(accepted as constructor parameter. Cannot be changed later. е_)

56783

AdId

Yes

ID of the ad's placement. A site can have multiple ad placements or positions which have the same or different ad sizes. AdId is the unique identifier for such an ad placement and this value can be obtained from the adId parameter in the PubMatic ad tag.

(accepted as constructor parameter. Cannot be changed later. е_)

341133

Height

No

Height of the ad.  Note: For native ad format, sizes for native assets (not for ad) are provided. This is an optional parameter.

250

Width

No

Width of the ad. Note: For the native ad format, sizes for native assets (not for ad) are provided. This is an optional parameter.

300

LocationSource

Yes*

Source of user's mobile device's location as provided in the Location parameter. 

Possible values are provided as options in enum.

Note: This parameter is mandatory only if the Location parameter is provided. This field has no significance if Location data (lat,long) is not given by publisher.

GPS

AdOrientation

No

ID of the ad orientation for the given ad request.

 

State

No

State of the user.

NY

AdRefreshRate

No

This parameter is used to specify the time interval (in seconds) after which the ad is refreshed.

By default, this time interval is set to 0 seconds. Therefore, the ad does not get refreshed automatically. This value should be in the range of 12 to 120 seconds.

0

BirthYear

No

Visitor's birth year as a four-digit integer.

1976

Income

No

User's income or income range in dollars (whole numbers).

 50000 or 50000-75000

IABCategory

No

List of IAB content categories for the overall site/application. If the site/application falls under multiple IAB categories, you can send categories separated by comma, and the string should be URL encoded.

IAB1%2CIAB-5%2CIAB1-6

Coppa

No

Indicates whether the visitor is COPPA-specific or not. For COPPA (Children's Online Privacy Protection Act) compliance, if the visitor's age is below 13, then such visitors should not be served targeted ads.

Possible options are:

  • 0 - Indicates that the visitor is not COPPA-specific and can be served targeted ads.
  • 1 - Indicates that the visitor is COPPA-specific and should be served only COPPA-compliant ads.

1

OrmmaComplianceLevel

No

Minimum compliance level. Possible values are 0, 1 and 2.

0

DoNotTrack

No

Indicates whether the user has opted out of the publisher or not, or whether HTTP_DNT is set or not. Possible values are: true or false.

false

Aid

No

Mobile application's ID on the exchange

 

AppName

No

Name of the mobile application. This value should be same as that mentioned on the application (app) store.

 

AppCategory

No

Application primary category as displayed on storeurl page of the Windows Store.

 

StoreURL

No

URL of the app store from where a user can download this application.

 

Paid

No

Indicates whether the mobile application is a paid version or not. Possible values are:

  • 0 - Free version
  • 1 - Paid version

0

AppDomain

No

Indicates the domain of the mobile application

 

 

Native-Specific Parameters

Most native-specific parameters are automatically added by the SDK. A few are not mandatory; the client will add them if needed.

Asset Objects

Asset objects are the main container object for each asset requested.

Main Container Objects for each Asset

                                 

Parameter

Mandatory

Description

AssetId

Yes

Asset ID to map with the creative assets.

IsAssetRequired

No

Flag to check if asset is required or optional

title

No

Title object for title assets. Refer to the Title Object definition.

img

No

Image object for image assets. Refer to the Image Object definition.

data

No

Data object for ratings, prices etc.  Refer to the Data Object definition.

 

Title Object

The Title object is used for the title element of the Native Ad.

           

Parameter

Mandatory

Description

Length

Yes

Maximum length of the text in the title element.

 

Image Object

The Image object to be used for all the image elements of the Native ad such as Icons, Main Image, and others.

                                 

Parameter

Mandatory

Description

ImageType

No

Type ID of the image element supported by the publisher. The publisher can display this information in an appropriate format. Possible values: Icon, Logo, Main

Width

No

Width of the image in pixels.

MinWidth

No but recommended

The minimum requested width of the image in pixels.  This option should be used for any rescaling of images by the client.  Either w or wmin should be transmitted. If w is included, it should be considered an exact requirement.

Height

No

Height of the image in pixels.

MinHeight

No but recommended

The minimum requested height of the image in pixels.  This option should be used for any rescaling of images by the client. Either h or hmin should be transmitted. If hmin is included, it should be considered an exact requirement.

 

Data Object

The Data Object is to be used for all non-core elements of the native unit such as Ratings, Review Count, Stars, Download count, descriptions etc.

                  

Parameter

Mandatory

Description

DataAssetType

Yes

Type ID of the element supported by the publisher. The publisher can display this information in an appropriate format.  Choose value from DataAssetTypes  enum provided in SDK.

Length

No

Maximum length of the text in the element‰ЫЄs response.

 

Video -specific Parameters

                                                                                             

Attachments

    Outcomes