Step 5: Requesting Ads
Currently, only Banners, Interstitials, Frames, and Native ads are supported.
Requesting Interstitials
The VMAX SDK provides various mechanisms to request for Ads in your UWP application. The SDK makes available both simple fully-managed Ad request methods and also the Cache & Show Ad methods to enable prefetching of ads for later viewing.
To request Managed Interstitials using LoadAd()
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 |
VMAXAdView adView=new VMAXAdView (); // To initialize the VMAXAdView. adView.UX=AdUX.Interstitial; // To specify Interstitial ads. adView.AdspotId = "MY_ADSPOT_ID"; // To specify the Adspot Id. Replace “MY_ADSPOT_ID” with your actual Adspot Id. adView.TimeOut = 20; // To specify the timeout in case of Ad failure. Default is 20 // Location and demographic targeting information may also be specified. Out of respect for user privacy, VMAX asks that you only specify location and demographic data if that information is already used by your app. Below are example of optional properties: adView.UserInfo.Age ="age"; adView.UserInfo.City = "city"; adView.UserInfo.Country = "country"; adView.UserInfo.DOB = "dob"; adView.UserInfo.Email = "email"; adView.UserInfo.Gender = "gender"; Note* - where "age", "city", "country", "dob", "email" and "gender" should be replaced with the actual values meeting your targeting requirements. for e.g.- Note: Kindly don’t copy paste the code as it is. As that may have bad impact on targeting of Ads served to user. adView.UserInfo.Age = 23; adView.UserInfo.City = "Mumbai"; adView.UserInfo.Country = "India"; adView.UserInfo.Gender = eGender.Male; adView.UserInfo.DOB = DateTime.Now; adView.UserInfo.Email = "abc@xyz.com"; adView.LoadAd(); // This will load the Ad and on success provides a callBack named DidLoadAd. You need to handle this to perform any action on this event in your application. //Interstitial Caching //To Cache Interstitial Ads for later viewing is possible through the below API: adView.CacheAd(); // To perform caching of the Ad. If required, this event can be used to run any custom code. //Showing Cached Ads: adView.ShowAd(); // To show the Cached Ad //Cancel Ads: adView.CancelAd(); // To cancel the Cached Ad and free up all adview resources . |
Requesting Rewarded Video Incent ads
VMAX also supports video ads with incent provision. These are video ads which on view completion will provide some virtual currency to users.
Vmax SDK supports wallet management to maintain walletElements also known as currency name which stores respective currency amount or total reward amount. And provides provision of getting total virtual currency, spending virtual currency, awarding virtual currency.
Below snippet shows the example of requesting Vast MarkUp Ads
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 |
// Initialize the adview object with proper adspot id and ux type VMAXAdView adView = new VMAXAdView(); adView.AdspotId = "MY_ADSPOT_ID"; adView.UX= AdUX.Interstitial; //Initialize wallet object Wallet wallet = Wallet.GetWallet(); //Create a wallet element WalletElement element = wallet.AddWalletElement("SampleWalletPath", "CurrencyName"); //SampleWalletPath is just a url for the icon for your virtual currency. This icon // will be reflected on to the message boxes related to Rewarded Videos in the future // sdk releases. As of now, this will not show up. You can pass it as an empty string. //Rewarded Video RewardedVideo rv = new RewardedVideo(element); // Set the following flags of the rewarded video to true or false as per your need to // show different popups rv.showCappingPopup = true; rv.showInterruptedPopup = true; rv.showPrePopup = true; rv.showPostPopup = true; // Set the texts for pre, post, interrupted and capping popups texts rv.PrePopupText = "Watch this video and get <reward> <currency>"; rv.PrePopupTitle = "VMAX"; rv.PostPopupText = "You earned <reward> <currency>"; rv.PostPopupTitle = "VMAX"; rv.InterruptedPopupText = "You will lose your reward"; rv.InterruptedPopupTitle = "VMAX"; rv.CappingPopupText = "Daily maximum count to view the ad reached"; rv.CappingPopupTitle = "VMAX"; // Set the necessary event handlers element.OnUpdateFailedVirtualCurrency += Element_OnUpdateFailedVirtualCurrency; element.OnUpdateVirtualCurrency += Element_OnUpdateVirtualCurrency; rv.OnRewardedVideoCompleted += Rv_OnRewardedVideoCompleted; rv.OnRewardedVideoInterrupted += Rv_OnRewardedVideoInterrupted; rv.OnRewardedVideoPlaybackError += Rv_OnRewardedVideoPlaybackError; // This is the most important API you need to call once initialization has been done adView.InitRewardedVideo(rv); // Now you can call CacheAd() or LoadAd()according to your need. adView.LoadAd(); // If you need to award currency, use AwardVirtualCurrency API. It takes long value as // input parameter element.AwardVirtualCurrency(100); // If you need to spend the currency, use SpendVirtualCurrency API. It takes long // value as input parameter element.SpendVirtualCurrency(20); // To get the currency for an WalletElement use GetVirtualCurrency element.GetVirtualCurrency(); |
Requesting Video Interstitial Ads for Video Player adspots
This will help you to get vast Markup(XML) in string format for video player Adspot where developers have their own players to play video Ads.
Below snippet shows the example of requesting Vast MarkUp Ads
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
// Initialize the adview object with proper adspot id and ux type and then call // CacheAd() api. VMAXAdView adView = new VMAXAdView(); adView.AdspotId = "MY_ADSPOT_ID"; adView.UX= AdUX.Interstitial; adView.CacheAd(); //Once ad has been caached successfully, initialize the VastAdObject as follows. private void AdView_AdCached(object sender, EventArgs e) { VastAdObject adobj = adView.vastAdObject; if(adobj != null) { string str = adobj.GetVastResponse(); } } |
Requesting Banner Ads
Managed Banner Ads using LoadAd()
You can request for Banner Ads that refresh automatically in a container using the LoadAd() method. The signature for this method is:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
VMAXAdView adView=new VMAXAdView (); // To initialize the VMAXAdView //To set the mandatory properties and to configure the adView after initialization. adView.AdspotId = "MY_ADSPOT_ID"; // To specify the Adspot Id. Replace "MY_ADSPOT_ID" with your actual Adspot Id. adView.UX= AdUX.Banner; // To specify banner ads. // In case you are adding the control through codeBehind(C#) you have to place the VMAXAdView into a container control such as a Grid, StackPanel, and so on. this.ContentPanel.Children.Add(adView); // Below are optional properties to enable / disable or modify refresh rate/stop/pause/resume. By default refresh is on in SDK with 30 sec adView.RefreshRate = refreshRate; // To specify the refresh rate for banner ads Usage : int adView.Refresh =true; // To enable banner refresh – Usage: boolean adView.ResumeRefresh(); // To resume refresh adView.StopRefresh(); // To stop refresh adView.PauseRefresh(); // To pause refresh Timeout and Demographics are same as above. |
Requesting Native Ads
Native ads are ads which you can customize to match the unique user experience of your app.
Instructions for using the Native Ad Helper Library are available here.
Native ads can be requested in the following manner –
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 |
VMAXAdView adView=new VMAXAdView (); // To initialize the VMAXAdView // To set the mandatory properties and to configure the adView after initialization. adView.AdspotId = "MY_ADSPOT_ID"; // To specify the Adspot Id. Replace “MY_ADSPOT_ID” with your actual Adspot Id. adView.UX= AdUX.Native; // To specify native ads. adView.DidCacheAd +=AdView_AdCached; // add handler for successful callback of caching of native ad. adView.FailedToCacheAd +=DidFailed_CacheAd; // add handler for failure callback of caching of native ad. To request Native ads - adView.CacheAd(); Note : LoadAd() is not allowed for requesting Native ads. Using that will give an error message. The VMAXAdView provides the success and failure callback for Caching of Ads. The success callback can be used to provide the customization logic of the ad Unit. NativeAd is represented by the NativeAd property of the VMAXAdView object that you created which gives you an object of type NativeAd. In case of success it will contain the various elements of the NativeAd. You can extract the values of NativeAd elements by using the GetElementValue(<Predefined constant values>) API of NativeAd class. Predefined Constants are defined in the class- NativeAdConstants. or If you want all the elements in the form of a single JSON object and provide your own parsing logic, you can use the GetContent() API of the NativeAd class, which will return the NativeAd content in the form of JSON. eg. private void AdView_AdCached(object sender, EventArgs e) { var nativeVMAXAdView = sender as VMAXAdView; if (nativeVMAXAdView.NativeAd!=null) { var nativeAd = nativeVMAXAdView.NativeAd; // gets the NativeAd property of the VMAXAdView class. var nativeAdCustomJson = nativeAd.GetContent(); // gets the Native Ad content as a JSON object.You can provide your own custom logic to parse this or fetch values of individual elements as shown below. var buttonLabel = nativeAd.GetElementValue(NativeAdConstants.BUTTON_LABEL); var titleText = nativeAd.GetElementValue(NativeAdConstants.TITLE_TEXT); var imageUrl = nativeAd.GetElementValue(NativeAdConstants.LARGE_IMAGE); var iconUrl = nativeAd.GetElementValue(NativeAdConstants.ICON); var description = nativeAd.GetElementValue(NativeAdConstants.DESCRIPTION); } } Note: On Failure of Cache request the NativeAd property of VMAXAdView object will have the value null. Impression and Click Logging- Impression and Click logging will be done by the application itself. For this, just use the following API - NativeAdHelper.RegisterViewForInteraction(adView, NativeAdGrid, listOfNativeClickableElements ); listOfNativeAdClickableElements is nothing but a list of elements in the rendered native ad which you want to make clickable. To make the entire native ad clickable you can pass this parameter as null. It can be initialised as below: List<UIElement> listOfNativeClickableElements = new List<UIElement>(); listOfNativeClickableElements.Add(description); listOfNativeClickableElements.Add(this); Remember: Only after registering the impression the ad will be considered successfully rendered in application and impression will be recorded. Also, Only after registering the nativeAdView for clicks the clicks on the ad will be recorded. Absence of calling this mandatory API on successful ad rendering will impact revenue so just ensure that you make a call to it as soon as the NativeAd gets loaded. The SDK will automatically prevent a duplicate impression from being recorded for a single request. Note : In cases where you re-use the view to show different ads over time, make sure to call UnRegisterNativeViewForCallToAction() before registering the same view with a different instance of NativeAd. VMAX also provides a helper library to render the native ad. This Appendix section will summarize the use of Native Ad helper library. |
Requesting Video Interstitial Ads for Video Player adspots
This will help you to get vast Markup(XML) in string format for video player Adspot where developers have their own players to play video Ads.
Below snippet shows the example of requesting Vast MarkUp Ads
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
// Initialize the adview object with proper adspot id and ux type and then call // CacheAd() api. VMAXAdView adView = new VMAXAdView(); adView.AdspotId = "MY_ADSPOT_ID"; adView.UX= AdUX.Interstitial; adView.CacheAd(); //Once ad has been caached successfully, initialize the VastAdObject as follows. private void AdView_AdCached(object sender, EventArgs e) { VastAdObject adobj = adView.vastAdObject; if(adobj != null) { string str = adobj.GetVastResponse(); } } |
Step 6: Optional Callbacks
The VMAXAdView generates callbacks for successful and unsuccessful fetching attempts of Ads.
Methods
Specifying callbacks in XAML
1 2 3 4 5 6 7 8 9 |
<ad:VMAXAdView x:Name="adView" DidCacheAd="AdCached" DidLoadAd="AdReceived" FailedToLoadAd="AdFailed" WillDismissOverlay="AdCollapsed" WillLeaveApp="LeavingApplication" WillPresentOverlay="AdExpanded" FailedToCacheAd="DidFailed_CacheAd"/> |
Specifying callbacks through Code
1 2 3 4 5 6 |
adView.DidLoadAd+=AdReceived; adView.FailedToLoadAd+=AdFailed; adView.WillDismissOverlay+=AdCollapsed; adView.WillLeaveApp+=LeavingApplication; adView.WillPresentOverlay+=AdExpanded; adView.FailedToCacheAd+=DidFailed_CacheAd; |
The different methods to generate an API callback are as follows.
FailedToLoadAd Callback
The VMAX SDK offers this callback, in cases where an Ad is not served. If required, this event can be used to run any custom code.
1 2 3 4 |
private void AdFailed(object sender, com.vmax.windows.ads.wp10.VMAXAdView.AdFailedEventArgs e) { // ..Custom code goes here } |
FailedToCacheAd Callback
The VMAX SDK offers this callback, in cases where an Ad is not cached. If required, this event can be used to run any custom code.
1 2 3 4 |
private void DidFailed_CacheAd(object sender, EventArgs e) { // … Custom code goes here } |
DidLoadAd Callback
The VMAX SDK offers this callback, in cases where an Ad is rendered successfully. If required, this event can be used to run any custom code.
1 2 3 4 |
private void AdReceived(object sender, EventArgs e) { // ..Custom code goes here } |
DidCacheAd Callback
The VMAX SDK offers this callback, in cases where an Ad is cached successfully. If required, this event can be used to run any custom code.
1 2 3 4 |
private void AdCached(object sender, EventArgs e) { // ..Custom code goes here } |
WillDismissOverlay Callback
The VMAX SDK offers this callback, in cases of an Ad dismissal. If required, this event can be used to run any custom code.
1 2 3 4 |
private void AdCollapsed(object sender, EventArgs e) { // ..Custom code goes here } |
WillLeaveApp Callback
The VMAX SDK offers this callback, in cases of the Ad closing the current App and opening another App. If required, this event can be used to run any custom code.
1 2 3 4 |
private void LeavingApplication(object sender, EventArgs e) { // ..Custom code goes here } |
WillPresentOverlay Callback
The VMAX SDK offers this callback, in cases where an interstitial/overlay is shown . If required, this event can be used to run any custom code.
1 2 3 4 |
private void AdExpanded(object sender, EventArgs e) { // ..Custom code goes here } |
View the process of testing the integration here.