Cookbook¶
Here you will find some samples and explanations for several specific use cases.
Integrating a sticky banner on your website
We recommend the following setup for a sticky banner.
- Create a DIV container on your HTML page
- Add a CSS class to this DIV container with position:fixed and position it where ever you want or need it on the page (left, bottom, right or top)
- Add also a z-index for the DIV container in the range of 2 000 000 - 2 999 999. Please check the official display guidelines.
- If you want to support our "Dynamic banners" or "Resize Banners", you must listen on the event listeners ADvantageUpdateLayoutEvent, ADvantageResizeEvent, etc. (check ADvantage events) and dynamically change the ad space position based on the creative size.
Optional you can add width:100%; and text-align:center; to the css. This will center the ad space.
Example CSS:
.sticky{
position:fixed;
z-index:2000000;
bottom:0px;
width:100%;
text-align:center;
line-height:0px;
}
Example HTML:
<div class="sticky" id="sticky"></div>
Example Javascript:
window.onload = function(){
banner = new ADvantage_WebSDK( 'sticky' )
.setLicenseKey( '[LICENSE KEY]' )
.setSiteId('[SITEID]')
.setPosition('[POSITION]')
.setWidth( '320px' )
.setHeight( '50px' )
.addEvent(function(ev){
switch (ev.status){
...
case "ADvantageUpdateLayoutEvent":
//the creative is using update layout for the current instance
break;
case "ADvantageResizeEvent":
//the creative is using resize for the current instance
//do something
break;
case "ADvantageResizeClosedEvent":
//the creative is going back to the default size
//do something
break;
case "ADvantageCloseEvent":
// advertisement closed
break;
...
}
})
.initialize();
};
Disabling transparency of the ad space
By default, the advertisement space is transparent.
The transparency can be enabled or disabled with setTransparent().
setTransparent(false) will disable transparency in your ad space and set the background colour to white.
...
<div id="advertisement"></div>
...
<script>
banner = new ADvantage_WebSDK( 'advertisement' )
.setLicenseKey( '[LICENSE KEY]' )
.setSiteId('[SITE ID]')
.setPosition('[POSITION]')
.setWidth( '320px' )
.setHeight( '50px' )
.setTransparent( false )
.initialize();
</script>
...
Overriding the background color
You can always override the background color in the creative, however, they can not change the default behaviour of the advertisement space (transparency).
Centering the ad space
To center your ad space, all that has to be done is:
.adspace{
width:100%;
text-align:center;
}
Setting the maximum dimension for the understitial banner
The maximum allowed dimension for an understitial banner can be changed very easily.
Call the function setPublisherMaxSize( width, height ).
...
<div id="advertisement"></div>
...
<script>
banner = new ADvantage_WebSDK( 'advertisement' )
.setLicenseKey( '[LICENSE KEY]' )
.setSiteId('[SITE ID]')
.setPosition('[POSITION]')
.setWidth( '320px' )
.setHeight( '50px' )
.setPublisherMaxSize( 320, 600)
.initialize();
</script>
...
Here is an example if you need to call setPublisherMaxSize() when the banner is already loaded for example on a resize.
<script>
banner.setPublisherMaxSize( 320, 600);
</script>
...
Changing behaviour of the back button
The WebSDK is using an own back button controller for interstitials and modal views. This back button controller checks when an Interstitial or Modal view is opened if the user clicks on the back button. In this case the back button controller closes the interstitial or modal view.
The back button controller is per default enabled.
If you wish to disable the back button controller, use the following method .enableBackButtonController(false). The SDK will then not listen to the back button anymore.
Changing back button behaviour on an interstitial
For an interstitial you need to call setBackButtonEnabled() before setInterstitial().
interstitial = new ADvantage_WebSDK( 'advertisement' )
.setLicenseKey( '[LICENSE KEY]' )
.setSiteId('[SITE ID]')
.setPosition('[POSITION]')
.setBackButtonEnabled( false )
.setInterstitial( true )
...
Special use cases
If you are using <base href="..." /> in your source code, then you have two options: You either remove the "base href" from your code or disable the back button controller.
The reason for this is that some browsers (e.g. Chrome, IE, etc.) are not handling the pushState event correctly in case the URL is null or not defined when "base href" is defined.
How to define a whitelist so that an ad can add a Custom CSS to your website
To define a whitelist for Custom CSS use the function addWhiteListCSS. The function allows a string, an array of strings or a regualar expression. The provided string will be matched with the url which is provided by the ad.
Note: By default the ad is not able to add a custom CSS to your website.
Here are some examples:
banner = new ADvantage_WebSDK( 'advertisement' )
.setLicenseKey( '[LICENSE KEY]' )
.setSiteId('[SITE ID]')
.setPosition('[POSITION]')
.addWhiteListCss( 'style.css' ) // this will allow all style.css from any url
.addWhiteListCss( 'style' ) // this will allow all CSS files with the string style in the url
.addWhiteListCss( '^https://www.example.com/customstyle.css$' ) // this will allow only this url
.addWhiteListCss( '.*' ) // this will allow all css files
...
banner = new ADvantage_WebSDK( 'advertisement' )
.setLicenseKey( '[LICENSE KEY]' )
.setSiteId('[SITE ID]')
.setPosition('[POSITION]')
.addWhiteListCss( ['style.css','style','^https://www.example.com/customstyle.css$','.*'] ) // an array with strings and regualar expressions is added to the whitelist
...
Important Note
- We recommend that you test all custom CSS files before you allow it in the whitelist. Digitalsunray is not responsible if the custom CSS is not working.
- The creative developer should provide you the url, path or file name which you can add to the whitelist.
- For regular expressions don't use a delimiter.
- If you want to test the rules, book in a campaign on your ad server which is injecting the CSS. In the console output of your browser you can see if a rule matched the url provided by the the creative. Example string which you can search for
CSS Injected - by rule. You will see as well if the regular expression has thrown an error. - Do not use more then one creative with a custom CSS per page.
- For security issues please add full URLs only as regular expression like in the samples above. Otherwise someone can abuse this function by adding a valid entry from the whitelist as a querystring
https://www.test.com/hack.css?https://www.example.com/customstyle.css.
How to change margin of the corner ad
Corner ad margin can be set using the following code snippet:
banner = new ADvantage_WebSDK( 'advertisement' )
.setLicenseKey( '[LICENSE KEY]' )
.setSiteId('[SITE ID]')
.setPosition('[POSITION]')
.setCornerAdVerticalMargin(100); //this sets the vertical margin to 100px
.setCornerAdHorizontalMargin(100); //this sets the horizontal margin to 100px