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.
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 | |
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 |