Ad Player Configuration

You can customize the ad player look and behavior through a set of options defined in SVSAdPlayerConfiguration class. You'll find all informations needed to alter the default player's behavior on this page.

  1. Overview
  2. Integration
  3. Configuration options
    1. Display options
    2. Publisher options
    3. VPAID options
    4. RTB options

Overview

Ad player configuration is used to modify the look and feel and the behavior of your ad player.

Your custom ad player configuration can be created programmatically or directly from a JSON file hosted remotely.


There are 3 categories of configurable options:

  • Display options defines the look and feel of the ad player.
  • Publisher options defines the behavior of the ad player.
  • RTB options defines RTB parameters passed with your ad calls.


Creating your own ad player configuration is not mandatory: if none is passed to the SVSAdManager instance on its creation a default SVSAdPlayerConfiguration will be applied.

Integration

There are 2 ways to integrate your ad player configuration

  • Programmatically, by initializing a SVSAdPlayerConfiguration instance.
  • or by loading a remote JSON file.


Initializing a SVSAdPlayerConfiguration instance.

You can directly instantiate your custom configuration in your application and modify the options by simply manipulating the object.


@property (nonatomic, strong) SVSAdPlayerConfiguration *myAdPlayerConfiguration;

- (void)instantiateAdPlayerConfiguration {
	self.myAdPlayerConfiguration = [[SVSAdPlayerConfiguration alloc] init];

	// This example will force a skip delay of 2 seconds for every ads.
	self.myAdPlayerConfiguration.publisherOptions.forceSkipDelay = YES;
	self.myAdPlayerConfiguration.publisherOptions.skipDelay = 2.0;
}

private SVSAdPlayerConfiguration adPlayerConfiguration;

public void instantiateAdPlayerConfiguration() {
  adPlayerConfiguration = new SVSAdPlayerConfiguration();

  // This example will force a skip delay of 2 seconds for every ads.
  adPlayerConfiguration.getPublisherOptions().setForceSkipDelay(true);
  adPlayerConfiguration.getPublisherOptions().setSkipDelay(2000);
}

You can then pass the resulting object when initializing your SVSAdManager.


Fetching your configuration from a remote JSON file.

Hosting your configuration in a JSON file on a remote server is a convenient way to modify your ad player configuration without having to publish a new version of your application.

This is how you can retrieve an ad player configuration from a distant JSON file:


@property (nonatomic, strong) SVSAdPlayerConfiguration *myAdPlayerConfiguration;

- (void)instantiateAdPlayerConfiguration {
	NSURL *myRemoteJSONURL = [NSURL URLWithString:@"https://www.domain.com/pathtojsonfile/configuration.json"];

	[SVSAdPlayerConfiguration adPlayerConfigurationFromURL:myRemoteJSONURL completionHandler:^(SVSAdPlayerConfiguration *retrievedConfiguration, NSError *error) {
 		if (error) {
 			NSLog(@"There was an error when retrieving JSON configuration. %@", [error description]);
 		} else {
			self.myAdPlayerConfiguration = retrievedConfiguration;
			// Continue with your SVSAdManager initialization here.
		}
	}];
}

private static class AdRulesAsyncTask extends AsyncTask {
  @Override
  protected SVSAdPlayerConfiguration doInBackground(String... urls) {
    try {
      return SVSAdPlayerConfiguration.parseFromUrl(urls[0]).get();
    } catch (Exception e) {
      return null;
    }
  }
  @Override
  protected void onPostExecute(SVSAdPlayerConfiguration adPlayerConfiguration) {
    if (adPlayerConfiguration != null) {
      // Continue with your SVSAdManager initialization here
      // …
    } else {
      Log.e("TAG", "There was an error when retrieving JSON Ad Player Configuration.");
    }
  }
}

// …

public void instantiateAdPlayerConfiguration() {
  // Retrieving ad player configuration from an url is a blocking task, you should not do it in the main thread
  new AdRulesAsyncTask().execute("https://www.domain.com/pathtojsonfile/configuration.json");
}

Here is an example of a valid ad player configuration JSON:


{
	"player": {
		"enableFullscreen": false,
		"enableCountdownVideo": false,
		"enableCountdownSkip": false
	},
	"publisher": {
		"forceSkipDelay": true,
		"skipDelay": 5.0,
		"pauseMainContentUntilVASTIsLoaded": false,
		"totalTimeout": 15.0,
		"requestTimeout": 5.0,
		"stallTimeout": 6.0,
		"numMaxRedirect": 3,
		"numberOfPassbackAds": 5,
		"replayAd": true,
		"enableSSAR": false,
		"enableMobileClickThroughButton":false
	},
	"rtb": {
		"vdmin":1.0,
		"vdmax":2.0,
		"vbrmin":3.0,
		"vbrmax":4.0,
		"vpmt":2,
		"pgDomain": "domain"
	}
}

Configuration options

Here is an exhaustive list of the ad player configuration options.

You can check the API documentation for iOS or Android for more detailed descriptions.

Note that some options have a specific JSON key to remain compatible with the HTML JSON Ad Player Configuration.

Display Options

Display options are defined in the SVSAdPlayerConfigurationDisplayOptions class.

These options will modify the look and feel of the ad player.

Name Description Default JSON
enableFullscreen Show or hide the fullscreen / exit fullscreen buttons during a linear ad break. TRUE
enableCountdownVideo Show or hide the countdown before the end of a linear ad break. TRUE
enableSkipCountdown Show or hide the countdown before current ad can be skipped. TRUE
restrictControlsToAdPlayerBounds
(Android only)
Ensure that ad player controls stay within ad player video frame instead of using the whole parent container space (true to avoid breaking the parent layout when in WRAP_CONTENT) TRUE Not available

Publisher Options

Publisher options are defined in the SVSAdPlayerConfigurationPublisherOptions class.

These options will modify the behavior of the ad player.

Name Description Default JSON
checkUniversalAdId Indicates if UniversalAdId should be taken into account, when the plugin selects ads to display.
If enabled, the publisher rejects ads with ‘unknown’ or undefined UniversalAdId on his network. If the plugin receives such an ad, it will discard it, report an error, and replace it by a passback ad if available. Also, with this feature, an ad with the same UniversalAdId will never be displayed in an ad pod more than once. Ads with the same UniversalAdId will also be discarded and replaced by a passback ad if available.
The default value is false, which means that this option is not active.
FALSE
enableSSAR Indicates if Server-Side Ad Rules should be used for this configuration. Please refer to the Ad Rules documentation for more information. FALSE enableSSAR
enableClickThroughButton When TRUE, a clickthrough button will be displayed above the video layer, by default, the whole ad player layer view is clickable. FALSE enableMobileClickThroughButton
enableVPAID When FALSE, the SDK will not request or display any VPAID ads. TRUE
forceSkipDelay When TRUE, ignore any offset attribute from the VAST document and uses the skipDelay value instead. FALSE
maximumNumberOfRedirects Maximum number of wrapper redireaction allowed per ad. This is useful to avoid endless wrapper loops. 5 numMaxRedirect
numberOfPassbackAds Number of passback ads returned by the ad server.
  • -1 will make the delivery engine return default passback value (if there is enough ads available on the placement)
  • 0 will disable Passback Ads
  • N > 0 for a precise number of passback ads (if there is enough ads available on the placement)
-1
pauseMainContentUntilVASTIsLoaded Defines if the ad manager should pause the content player at exact ad break time even if ad break data are not loaded yet. When FALSE, the ad manager will ask to pause the content player only when the ad break is ready to play. TRUE
replayAds Indicates if preroll and postroll breaks should be displayed again when main content is rewinded. See the ad break management page for more info. TRUE replayAd
requestTimeout Time allowed for a single HTTP request. It must be less than totalTimeout. 3s
skipDelay Duration after which a linear ad can be skipped when forceSkipDelay is TRUE. -1 means that the ads will not be skippable. 0 means they are skippable immediately. Other positive values are delays in seconds. -1
totalTimeout Time allowed for an ad break request. If the ad break is not ready to play before the timeout, it is cancelled and content should resume. 8s
stallTimeout Time allowed for an ad to resume its playback when the video stalls. If the ad can not resume until the stallTimeout has elapsed, the ad playback will exit in error and either the next ad will try to play, or the ad break will end. 10s

VPAID Options

VPAID options are defined in the SVSAdPlayerConfigurationVPAIDOptions class.

These options will modify the behavior of the ad player, only concerning VPAID ads.

Name Description Default JSON
enableCountdownVideo Show or hide the countdown before the end of a linear ad break. TRUE enableCountdownVideo
enableSkip Show or hide the skip button. TRUE enableSkip

RTB Options

RTB options are defined in the SVSAdPlayerConfigurationRTBOptions class.

These options will pass specific parameters along with your ad calls for a better management of your RTB ads.

These parameters will only be sent if you set a positive value.

Name Description Default JSON
minimumVideoDuration The minimum duration (in secs) for the requested video creatives. -1 vdmin
maximumVideoDuration The maximum duration (in secs) for the requested video creatives. -1 vdmax
minimumVideoBitrate The minimum bitrate (in Kbps) for the programmatically requested video creatives. -1 vbrmin
maximumVideoBitrate The maximum bitrate (in Kbps) for the programmatically requested video creatives. -1 vbrmax
playbackMethod The playback method of the video creatives. -1 vpmt
pageDomain The page domain of the application's website. NULL pgDomain