Documentation

Namespace: adswizzSDK

adswizzSDK

This is the global namespace that Adswizz uses for JS Adswizz SDK. This SDK works with AIS 7.2 and higher. AIS should have activated 'set-session-cookie' flag activated inside of 'listen-socket' section.

Members

<static> this.onReceivedDetailsInfo :function

Set a listener where receiving details about the streaming server.

Type:
  • function
Example
adswizzSDK.onReceivedDetailsInfo = function(detailsObj, errorObj) {

    if (errorObj) {
         //treat the error: errrObj.code, errorObj.message
    }

    printlog("Received Details: " + JSON.stringify(detailsObj));

}

Methods

<static> addMetadataChangedListener(listener)

Register a new handler for metadata changing. The response object available to this function contains the metadata as string.

Parameters:
Name Type Description
listener function

Function to register
Example
adswizzSDK.addMetadataChangedListener(function(metadataString) {
    metadataLabel.innerHTML = metadataString;
});

<static> addMetadataConnectionListener(event, listener)

Use this function only for debug purposes

Parameters:
Name Type Description
event String

Possible values: "init", "message"
listener function

This is the function that is triggered whenever the MetadataConnection has a change. The response object available to this function contains the MetadataConnection result as string.
Example
adswizzSDK.addMetadataConnectionListener("init", function(metadataURL) {
     metadataUrlLabel.innerHTML = metadataURL;
     printlog("MetadataConnection initialised with URL: " + metadataURL);
});

<static> getVersion()

Retrieve the current AdsWizz Javascript SDK version

Returns:

SDK current version

Type
string

<static> init(configObj)

Used to initialize and setup the SDK.

Parameters:
Name Type Description
configObj Object

The configuration object

Properties
Name Type Description
listenerConsent Boolean

Can be true or false. When true the listenerId is get from Cookie, otherwise the listenerID is randomised.
contentPlayer HtmlElement

HtmlElement object which contains the audio stream.
playerId String

Player Id.
metadata Object

If this object is missing, then the default settings are used (recommended)

Properties
Name Type Description
listeners Array

An array of functions
pollingInterval Number

Interval in milliseconds between the metadata requests. Default value is 2000 ms.
connectionType MetadataConnection

Metadata connection type. Default is TIMED_POLLING!
companionBanner Object

If this object is missing, then the companion banner feature is disabled. You can set companionBannerConfig later using adswizzSDK.setCompanionBannerConfig(bannerConfigObj)

Properties
Name Type Description
container Object

The div object which will contain the companion banner. Not mandatory. If not set you should register with callbacks to get the companionAd URL and load it on your own.
containers Array

The div object which will contain the array of companion banners. Not mandatory. If not set you should register with callbacks to get the companionAd URL and load it on your own.
size Array

(Optional) Width and height of the added companion banner.
baseURL String

This is the base URL used to create the companion banner requests. [YOUR_ADSERVER_INSTANCE] should be provided by AdsWizz.
zoneId String

Commercial zone for display ads. Should be a numeric value from your AdServer instance provided by Adswizz
fallbackZoneId String

The fallback display zone id. It can be used when audio ad doesn't have a companion banner and you need to display one or it can be used outside of the adbreak itself (as a filler element). Should have numeric value.
alwaysDisplayAds Boolean

Can be true or false. If set on true then the companion banner will be shown on display outside of the ad break as well, not only during the audio ad break.
extraExposureTime Number

Time in milliseconds defining how long the sync-banner is supposed to be visible after the ad playout. Default value is 0 ms, meaning the sync-banner is removed when the ad ends.
outOfContextListener function

Not mandatory. This function is called when needed to inform the player that the rendering of the display ad has finished.
willDisplayListener function

Not mandatory. Contains the srcURL and it is called when synchronized companion ad will be rendered.
willDisplayFallbackListener function

Not mandatory. Contains the srcURL and it is called when the fallback companion ad will be rendered. anymore with the companionView
Example
function changeMetadataFunction(metadataString) {
          metadataLabel.innerHTML = metadataString;
    }

    function adsWizzCompanionOutOfContextFunction() {
          console.log("adsWizzCompanionOutOfContextFunction");
    }

    function adsWizzCompanionWillDisplayFunction(companionBannerURLString) {
          console.log("adsWizzCompanionWillDisplayFunction with banner srcURL =" + companionBannerURLString);
    }


    adswizzSDK.init({

          //You can disable the load of register2.php script that is used to appened the listenerID. By default this value is true, so the listenerID is appended from Cookie. You can disable it by setting the value to false. In this case the listenerId is randomised.
          listenerConsent: true,

          //You can set here the audio element object. This is a mandatory field but it can be set also later after the init method using adswizzSDK.setContentPlayer("audio player")
          contentPlayer : document.getElementById('contentPlayer'),

          //You can set here your playerId provided by Adswizz. This is a mandatory field and needs to be set right from the start.
          playerId : "Example_Player_JS",

          //If the metadata fields are not defined then the default values are used. However it is recommended to keep the default values unless otherwise specified.
          metadata : {
               listeners : [changeMetadataFunction], //register here synchronized metadata callbacks
               pollingInterval: NUMERIC_VALUE, //It is defined in miliseconds, replace NUMERIC_VALUE with desired value (if not defined the default value is 2000)
               connectionType : adswizzSDK.MetadataConnection.LONG_POLLING,//if not defined the default value is TIMED_POLLING, you can choose between the 4 predefined values
          },

          //If the following companionBanner section is not defined then the companionBanner feature is DISABLED.
          //You can also set the companionBanner config later after the init method using adswizzSDK.setCompanionBannerConfig(bannerConfigObj);
          companionBanner : {
               container   : document.getElementById("companionBannerDiv"), //Not mandatory. If not set you should register with callbacks to get the companionAd URL and load it on your own.
               containers  : [document.getElementById("companionBannerDiv1"), document.getElementById("companionBannerDiv2")], //Not mandatory. If not set you should register with callbacks to get the companionAd URL and load it on your own.
               size        : [720,80], //width,height in pixels. The 720/80 is used here just as an example, you can put whatever values here.
               baseURL     : "https://[YOUR_ADSERVER_INSTANCE].deliveryengine.adswizz.com/www/delivery/afr.php", //can be http also. [YOUR_ADSERVER_INSTANCE] should be provided by AdsWizz.
               zoneId      : "[YOUR_ZONE_ID]", //commercial zone for display ads. Should be a numeric value from your AdServer instance provided by Adswizz
               fallbackZoneId  : "[YOUR_FALLBACK]", //the fallback display zone id. It can be used when audio ad doesn't have a companion banner and you need to display one or it can be used outside of the adbreak itself (as a filler element). Should have numeric value.
               alwaysDisplayAds : true, //Can be true or false. If set on true then the companion banner will be shown on display outside of the ad break as well, not only during the audio ad break.
               outOfContextListener : adsWizzCompanionOutOfContextFunction, //Not mandatory. This function is called when needed to inform the player that the rendering of the display ad has finished.
               willDisplayListener : adsWizzCompanionWillDisplayFunction, //Not mandatory. Contains the srcURL and it is called when synchronized companion ad will be rendered.
               willDisplayFallbackListener : adsWizzCompanionWillDisplayFallbackFunction //Not mandatory. Contains the srcURL and it is called when the fallback companion ad will be rendered.
          }
    });

<static> removeMetadataChangedListener(listener)

Parameters:
Name Type Description
listener function

Function which was registered
Example
adswizzSDK.removeMetadataChangedListener(listener);

<static> setCompanionBannerConfig(companionBannerConfig)

Register a new companionBanner config.
To reset the current companionBanner config pass null like in the below example. In this way companionBanner feature will be disabled

Parameters:
Name Type Description
companionBannerConfig Object

The companion banner configuration object
Example
adswizzSDK.setCompanionBannerConfig({
               container   : document.getElementById("companionBannerDiv"), //may not be set. If not set, you should register with listeners to get the companionAd URL and then load it on your own. If provided, we'll load the banner in an iFrame.
               containers  : [document.getElementById("companionBannerDiv1"), document.getElementById("companionBannerDiv2")], //may not be set. If not set, you should register with listeners to get the companionAd URL and then load it on your own. If provided, we'll load the banner in an iFrame.
               size        : [720,80], //[width,height]
               baseURL     : "https: //[YOUR_INSTANCE].deliveryengine.adswizz.com/www/delivery/afr.php", //can be http also. [YOUR_INSTANCE] should be provided by AdsWizz.
               zoneId      : "[YOUR_ZONE_ID]", //commercial zone for display ads. Should be like "12353"
               fallbackZoneId  : "[YOUR_FALLBACK]", //the fallback zone id for the case when the audio ad doesn't have a companion banner. Should be like "12354"
               alwaysDisplayAds : true, //if true then Adswizz will take control of the companion banner outside of the ad break also.
               outOfContextListener : adsWizzCompanionOutOfContextFunction, //Not mandatory. This function is called when needed to inform the player that the rendering of the display ad has finished.
               willDisplayListener : adsWizzCompanionwillDisplayFunction, //Not mandatory. Contains the srcURL and it is called when synchronized companion ad will be rendered.
               willDisplayFallbackListener : adsWizzCompanionWillDisplayFallbackFunction //Not mandatory. Contains the srcURL and it is called when the fallback companion ad will be rendered.
           }); //set a new companionBanner config
adswizzSDK.setCompanionBannerConfig(null); //reset the current companion banner config

<static> setContentPlayer(contentPlayer)

Register a new contentPlayer.
To reset the current contentPlayer pass null like in the below example

Parameters:
Name Type Description
contentPlayer HtmlElement

HtmlElement object which contains the audio stream.
Example
adswizzSDK.setContentPlayer(document.getElementById('contentPlayer')); //set a new contentPlayer
adswizzSDK.setContentPlayer(null); //reset the current contentPlayer

<static> setHowlerPlayer(howlerPlayer)

Register a new contentPlayer.
To reset the current howlerPlayer pass null like in the below example

Parameters:
Name Type Description
howlerPlayer Howl

object.
Example
adswizzSDK.setHowlerPlayer(howlerPlayer); //set a new howlerPlayer
adswizzSDK.setHowlerPlayer(null); //reset the current howlerPlayer

<static> setListenerConsent(true|false)

Set the listener's consent value

Parameters:
Name Type Description
true|false Boolean

The value of the listenerConsent. True if the listenerConsent is given, otherwise false. If true the listenerID used to decorate the streamURL is taken from Cookie, otherwise randomly generated.
Example
adswizzSDK.setListenerConsent(true); //set a new value for the listenerConsent. In this example the listener consent is given.

<static> setMetadataConnectionType()

Set the desired MetadataConnection type. If not set, then default setting is used. It's recommended to use the default setting.

Throws:

EventSource is not supported by IE and Microsoft Edge and it throws an exception

Example
adswizzSDK.settings.setMetadataConnectionType(adswizzSDK.MetadataConnection.TIMED_POLLING);