What is the Javascript SDK?

The Widespace Javascript SDK is a more powerful and advanced way to integrate ads into your site. By exposing different methods and events, the Javascript SDK allows you to get more control over how and when the ad should be delivered to your ad slot. The recommended implementation is to do it directly on the site without booking it through a third party Adserver. Below you’ll find documentation + code examples of how to get started with the Javascript SDK integration.

 

Start writing code

Start by including the following code into your document.
Also make sure that the jssdk.js file is running before the ad space container.

 

## Note that the SID needs to be replaced with your own ##

<script> var wisp = window.wisp || {}; wisp.options = {}; </script>
<script src="//engine.widespace.com/map/engine/jssdk.js"></script>

<div id="idOfElementWeShouldDisplayTheAdsIn"></div>

<script>

    var myInstance = new wisp.AdSpace({
        sid: '7daa3f23-0951-495b-81bf-ec751e122666',
        containerId: 'idOfElementWeShouldDisplayTheAdsIn' /*id of div container where ad will be displayed*/
        });

    myInstance.runAd();

</script>

 

If you want to have two or more ads hardcoded on your site, you can do as suggested below.

 

## Note that the SID needs to be replaced with your own ##

<script> var wisp = window.wisp || {}; wisp.options = {}; </script>
<script src="//engine.widespace.com/map/engine/jssdk.js"></script>

<div id="id1"></div>

<script>

    var ad1 = new wisp.AdSpace({
        sid: '7daa3f23-0951-495b-81bf-ec751e122666',
        containerId: 'id1'
        });

    ad1.runAd();

</script>



<div id="id2"></div>

<script>

    var ad2 = new wisp.AdSpace({
        sid: '7daa3f23-0951-495b-81bf-ec751e122666',
        containerId: 'id2' 
        });

    ad2.runAd();

</script>

 

Geolocation

The geolocation module allows the JS SDK to automatically apply the phones position within the request for an ad. This will not only allow more ads, that will increase fillrate & revenue, but also the reliability in delivery of the ads served on your site.

 

wisp.options.geolocation = true;

// which is equivalent to:

wisp.options.geolocation = {
  method: "DONT_ASK",
  source: "LOCAL",

  // Minimum time between requests
  requestCapInSeconds: 0,

  // iOS specific, Minutes between "ordinary" requests
  nextPermanentPermissionRequestInMinutes: 10,

  // iOS specific, Days between "permanent" requests
  nextPermissionRequestInDays: 6
};

The source property defines which frame should make the request. LOCAL makes requests from the current domain, while REMOTE makes requests from the domain “widespace.com”. The user will see what domain makes the request, and can choose to deny it. To disable geolocation on a specific platform, do as follows:

wisp.options.geolocation = true;

wisp.options.geolocation = {
  method: "ALWAYS",
  source: "LOCAL",
  disableOn: ["iOS"]  // The other options are: "Android" and "WP"
};

 

 

Demography

If you as a publisher want to supply the SDK with demography data, which will allow to deliver ads more suitable to the user. This is done by setting the wisp.demo property before loading the SDK.

An example using all available fields is shown below:

 

wisp.demo = {

        gender: 'F',                 // 'M' or 'F'. In this case, a female user

        country: 'UK',            // 2 character ISO-3166 country code

        region: 'Greater London', // Name of region, like state or 'län'

        postal: 'W1U 8EW',        // postal code, as a string like
                                    // ex: '64533', '71 343', '511-0811', 'A34 FF3'

        city: 'London',           // Name of city, in English

        yob: 1986,                // Any year between 1900-, number or string

        keywords: 'skiing,coffee' // Any comma separated string of keywords
                                  // ex: 'eclair,froyo,9gag,reddit'
};

 

Methods

 

Methods Description
adspace.runAd(); Use runAd(); to request and display the ad, if any was returned, or already existed in the ad queue.
adspace.prefetchAd(); Use prefetchAd(); to pre-load an ad and add it to queue. Use the runAd(); method when you want to display the ad.
adspace.setAutoUpdate(boolean); Use setAutoUpdate(); set to true if the publisher wants the AdSpace to periodically change ads. Defaults to false.
adspace.remove(); Use adspace.remove(); when AdSpace is no longer required.

 

Initialization Object

 

Parameter Required Description
sid: string The ID, used by the system to identify the AdSpace. An Error is thrown if the sid isn’t a string.
containerId: string The containerId property should be the id of the HTMLElement in which to put the ads. An Error is thrown if neither containerId or containerElem can be used to access a HTMLElement.
containerElem: HTMLElement The containerElem property should directly reference the HTMLElement in which to put the ads. An Error is thrown if neither containerId or containerElem can be used to access a HTMLElement.
maxWidth: int Sets the maximum width allowed for ads within the adspace.
maxHeight: int Sets the maximum height allowed for ads within the adspace.
autoUpdate: boolean Set to true if the publisher wants the AdSpace to periodically change ads. Defaults to false.

 

Events

 

function adLoadedLogger() {
  console.log(Array.prototype.slice.call(arguments));
}
//Add
adspace.addEventListener('adloaded', adLoadedLogger);

//Remove
adspace.removeEventListener('adloaded', adLoadedLogger);
Event name Arguments Description
adopened After opening an ad.
adclosed After closing an ad.
adloading Before reqesting an ad.
adloaded After recieving a successful ad response.
adexpanded final width:int, final height:int After an ad has expanded.
adcollapsed final width:int, final height:int After an ad has collapsed.
adprefetched status:string(NO_MEDIA, MEDIA_CACHED, MEDIA_NOT_CACHED) After prefetch ad done, including media caching.
displaymodechanged display mode:string(inline, modal, fullscreen) After the ad has changed display mode.
mediastarting media type:string Before media playback has started.
mediastopped media type:string After media has been paused.
mediacompleted media type:string After media playback has reached it’s end, or if the mediaplayer was closed by the user.
noad After recieving a “noAd” response. A valid response but where the ad server does not deliver and ad.
error type:string, message:string, origin:object Raised whenever the SDK cannot accomplish the expected task. See Errors for the error types.

 

Error

 

Error name Message Description
NO_ERROR Error instance could not be initiated properly.
MEDIA_ERROR Media.
PERMISSIONS_ERROR Permission, if the user denies access to a feature
FEATURE_ERROR Feature missing (in case browser does not support what the SDK is trying to do)
LAYOUT_ERROR Layout “locked” by publisher.
DEPRECATED_SDK_ERROR Deprecated SDK version (in case we want to block older versions from showing ads).
CONNECTION_LIMIT_ERROR Connection Limit Exceed Exception
HTTP_ERROR Connection failed.Connection timed out. Connection denied. Unauthorized request. etc. Anything except a 200 OK response, or Engine non-standard responses (i.e. connection denied, unauthorized etc.)
JSON_PARSE_ERROR Invalid server response. Malformed JSON.
SDK_INTERNAL_ERROR SDK did not perform as expected. Please file bug-report!

 

 

 

Do you have any questions or need further guidance?

Feel free to contact integrations@widespace.com and we’ll do our very best to help you out!

Was this article helpful to you?