Show Sidebar

Requesting Ads – iOS Unity Plugin

Points to Remember

  1. Cache the next ad only after the previous ad is completely consumed. The same will be notified using the willDismissAd callback.
  2. Before showing an ad, pause all game sounds and animations that might interfere with an ad. You can resume the same after getting the willDismissAd callback (when the ad ends).
  3. Follow the best practices of the ad networks that you wish to integrate.
  4. Make sure you pass the Activity Context to the VMAX SDK if you want to display banner, native, interstitial or incent-based ads.
  5. VMAX being a mediation platform will try to maximize the yield for you. It is not recommended to send another request for an ad if there is an unsuccessful attempt in fetching an ad. Please wait at least 30 seconds before requesting an ad after an unsuccessful fetch attempt.

Requesting Ads

The VMAX Unity plugin provides you with various mechanisms to request for Ads in your Unity application/game. The plugin provides both simple fully-managed Ad request methods and also the Cache & Show Ad methods to enable prefetching of ads and showing them later.

Requesting Banner Ads

Note: For Banner Ads, please ensure that you have turned off the refresh from the mediation partner’s web interface when using a fresh integration of VMAX Unity Plugin 3.4.0 or higher. This change in settings is not required when updating from an earlier version to 3.4.0 or higher.

Requesting Interstitial Ads

Requesting Native Ads

Native Ad types that are available in Unity are Icon, Infeed & Content Stream. One can specify the native ad type for rendering by setting the native ad type to one of the following VMaxNativeAdType options:

To integrate Native Ads, use:

Registering Icon Button

Un-registering Icon Button

Extension to Native Icon ads

In addition to using the icon as an element to invoke an ad, you can use other ad elements in VMAX. Currently, the following elements are supported for the icon ad format as part of image extension sub-feature:

  • imageIcon
  • imageMain
  • imageMedium
  • textTitle
  • textDesc2

You can choose between rendering the Icon ad by specifying the element desired from among:

This can be done as follows:

Positioning Infeed & Content Stream ads

For positioning Infeed & Content Stream ads, you can use the AbosolutePosition api as follows

Properties for Text Extension

You can set the following properties to make the text look native in your app.

Listening to Ad Callbacks

  • Load the Ad with Automatic Refresh.
    Note: Automatic Refresh is valid for Banner Ads only; Billboard Ads are not supported.
  • To Request an Ad with Orientation use the loadAdWithOrientation method from the Required_Orientation_From_EnumVMaxAdOrientation.
    Use the following values from VMaxAdOrientation Enum,

  • To have greater control over Ad Display, use

  • [Optional] Set an Ad Refresh rate greater than the default of 30 seconds.
    Note 1: The minimum Ad Refresh rate is 30 seconds; setting a lower value will default to 30 seconds.
    Note 2: Refresh rate is valid for Banner Ads only; Billboard Ads are not supported

  • [Optional] Set the User details for appropriate ad delivery.

  • Set the Request Timeout of Ads greater than the default Timeout of 20 seconds.
    Note: The minimum Request Timeout is 20 seconds; setting a lower value will default to 20 seconds.

  • To know the state of the Ad, call
    VMaxAdState state = adRef.GetAdState();
  • To Customize the appearance of Ad, use

  • To pause the ad refresh, call

  • To resume the paused ad, call

  • To Stop the refresh permanently , call

  • Destroy the VMax Ad instance.

Ad Filter Blocking

Ads can be blocked on the following:

  • Event based
    To block the ads manually, use

Note 1: A boolean of YES will block Ads and not take any space on the device screen.
Note 2: Set a boolean of NO to unblock Ads

  • Session based
    To block the ads for a certain number of App sessions,use
    Note 1: Ads will be blocked for a specified number of Application sessions.
    Note 2: To reset, call this API with inNoOfSessions = 0.
  • Country based
    To Block or Allow the Ads in certain countries, use

Disable offline access

To disable an app from starting, if an internet connection is unavailable, use the inShouldDisableOffline flag. If set to YES, the plugin will prompt for an internet connection not being available. In this case, the user either will have to activate the internet connection or quit the App.

Note: Insert the Key NSLocationWhenInUseUsageDescription and the description for Location access message box in your Application’s info.plist file of Xcode that allows SDK to access the user location and deliver more appropriate ads.

Integrating Banners with Strict Dimensions (SBD)

SBD will allow VMAX to fetch banners with strict dimensions with the below Ad sizes:

  • 320×50
  • 728×90
  • 300×250
  • 480×320
  • 320×480
  • 480×800
  • 800×480
  • 1024×600
  • 600×1024

You need to use SetAdSettings API available in VMaxPlugin instance with argument settings,which will be an Dictionary. You should set value for key from VMaxAdSize enum.The different size available are

  • VMaxAdSize._320x50,
  • VMaxAdSize. _728x90,
  • VMaxAdSize._300x250,
  • VMaxAdSize. _480x320,
  • VMaxAdSize._320x480,
  • VMaxAdSize._480x800,
  • VMaxAdSize. _800x480,
  • VMaxAdSize. _1024x600,
  • VMaxAdSize._600x1024

These are the constants available in VMaxAdview.h

  1. Creating adview instance for Strict Banner
  2. Set required adSize

Note: Rest all of the invocation codes for Strict Banners will be same as that for Normal Banners

Mediation partners supported for SBD are Admob, Facebook, and Millennial Media with sizes
“320×50”, “728×90” , “300×250”

SBD Adspot and Mediation Partner configuration:

Ad size Mediation Partner Instructions
320×50 and

728×90 Banner

VMAX Agency Ads Create a Banner Adspot on the VMAX dashboard.
Admob Create an Admob adunit id on your Admob dashboard and link it to a VMAX banner Adspot.
Facebook Create a Facebook placement id on your Facebook dashboard and link it to a VMAX banner Adspot.
Millennial Media Create a Millennial Media Banner Appid (Banner placement) on your MM dashboard and link it to a VMAX banner Adspot.
300×250 Billboard VMAX Agency Ads Create a Billboard Adspot on the VMAX dashboard.
Admob Create an Admob banner adunit id on your Admob dashboard and link to a VMAX Billboard Adspot.

*Backend configuration is required (kindly contact your VMAX Account Manager)

Facebook Create a Facebook banner placement id on your Facebook dashboard and link to a VMAX Billboard Adspot.

*Backend configuration is required (kindly contact your VMAX Account Manager)

Millennial Media Create a Millennial Media rectangle Ap id (Rectangle placement) on your MM dashboard and link to a VMAX Billboard Adspot. As MM will always serve a rectangle ad (300×250), ignore the ad settings passed by VMAX, if any.
480×320, 480×800, 1024×600,320×480
,800×480,600×1024 Billboard
VMAX Agency Ads,Admob Create a Billboard Adspot on the VMAX dashboard.

Requesting Rewarded Video Ads

Following are Reward Video Incent Partners Adcolony, Vungle, UnityAds, and Chartboost. VMAX provides unified rewarding system for above listed partners. One can configure reward amount and maximum impression cap on VMAX dashboard for respective adspot.

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.
Note: Some partners like Chartboost support incent pre roll and post roll messages via their interface. So make sure to OFF pre roll and post roll messages while using VMAX Incent Reward code.

Below snippet shows initialisation of Wallet with Rewarded Video Ads.

  1. Get the wallet instance
  2. Initialize VMax ad with Reward Video
  3. Implement callback methods for RewardVideo and WalletElement events
    VMaxPlugin instance will provide following events for Rewarded video
    VMaxWalletElement will generate following events
  4. Note:
    1. By default all pop will be enabled.
    2. You can customize rewarded video popup reward amount and currency name by using 2 of the above api in following format.
  5. Call these methods on WalletElement

Postback URL for rewarded videos

To add the postback URL for rewarded videos, visit Settings >> Apps and Adspots >> Rewarded Video Adspots
Read more on how to add mediation partners.