Search REST and JavaScript API

This API allows access to advertising content from the Cxense Advertising platform either by using REST or Javascript as the transport protocol.

Basic Concepts

To receive advertising content, an advertising search (impression request) request needs to be made to the Cxense Advertising platform.

Cxense Advertising has two search API's that provide interfaces to request advertising content impressions:

the search REST API; and
the JavaScript search API.

The REST API provides an interface to make HTTP impression requests to the Cxense Advertising platform to receive results in HTML or XML form. The JavaScript API provides a method to embed a hook directly into content which makes an asynchronous call to the Cxense Advertising platform.

REST Search API

Impression Request

The default and only REST action is a GET on the Cxense Advertising REST search API.

The REST request requires the following form ¹:

http://adserver.cxad.cxense.com/adserver/search?asId=

¹ Impression requests will not fail without parameters. However, asId is mandatory for delivering impressions.
Requirements for (k=), (l=) and (cat=) depend on the matching criteria of the specified AdSpace in asId=.

Usage of the REST APIs will still record statistics (such as increased impression counts) and impact metrics used to rank the ad (such as click through rate). To avoid this, you can use the sandbox environment. Please contact the Cxense Advertising customer support team for access.

Search Parameters

Each REST API search request accepts parameters.

Parameter	Description	Default	Example	Mandatory
`asId`	AdSpace Id. The identifier of the advertising space that impressions are for.	n/a	`asId=0000000000004748 (multiple are allowed so that asId=0000000000004748&asId=0000000000004749 is valid)`	Yes
`media`	Media format. The media type for the response.	`html`	`media=html` `media=xml` `media=json` `media=javascript` `media=vast2 (IAB VAST 2.0 compliant xml)` `media=vast3 (IAB VAST 3.0 compliant xml)`	No
`k`	Keywords. The keywords to use as matching criteria. Individual keyword parmeters ('`k=`') must contain no more than 10 unique terms.	n/a	`k=volvo`	No
`ctx`	Context. The "context" for the request, often a URL.	n/a	`ctx=http%3A%2F%2Fwww.cxense.com`	No
`cat`	Category. Specifies the registered category name that this advertisement will match.	n/a	`cat=business,` (or `cat=abc-categories:business` for custom categories, where <abc> is your Customer prefix)	No
`l`	Location. The location to use as matching criteria.	n/a	`l=usa`	No
geo	Geo location. The coordinates to use as geospatial matching criteria. Format is latitude,longitude,distance/accuracy in km's.	n/a	geo=-37.6832,144.583,1	No
`ps` `pn`	Pagination works in two modes: Manual. Setting the number of results / page size (ps) and zero-based page number (pn). Automatic. If you do not supply these parameters, the adserver will construct a page using the horizontal and vertical size of the ad space and the matched creatives. If you wish to use render templates you must control pagination manually as the adserver is unable to determine whether creatives will fit in your allocated space.	n/a	`ps=5` `pn=0`	No
`lang`	Language. The languages in which results apply. ISO language code.	n/a	`lang=en_US`	No
`usi`	User ID. Typically set to a session ID from your application server. Automatically set if you are using the JavaScript tag.	n/a	`usi=678844C407B6E28C546AF36CF21BC336`	No
`dup`	Destination URL prefix. This can be added to do click tracking. Will be prepended to the destination URL	n/a	`dup=http://a.com/trackClick?destinationURL=`	No
`useSecureUrls`	Set this flag to true to get HTTPS-versions of click URLs and content URLs	`false`	`useSecureUrls=true`	No
`callback`	The function name for the jsonp callback. Note that the media type (via the `media` parameter) must be set to `javascript`	n/a	`callback=ad_callback`	No
`auw` `auh` `sz`	The `auw` and `auh` parameter control the size of creatives returned (ad-unit width and ad-unit height respectively). The `sz` parameter is a convenience to set the width and height in a single parameter.	n/a	`auw=300` `auh=150` `sz=300x150`	No
`duration.min` `duration.max`	Filters the duration of video creatives. The values are in milliseconds.	n/a	`duration.min=60000`	No
tzo	(Optional) The Timezone the request is being made for, in minus minutes (I.e. Melbourne is GMT+10, so we would pass in -600)	Obtained from the clients browser by Javascript	tzo=-600 (Melbourne is 10 hours ahead of UTC)	No

Parameter Constraints

Parameter	Constraint
`k`	If an impression request application is likely to have greater than 10 unique keyword parameter terms, parameter strings must be broken into multiple '`k=`' parameters. For example: "black 17inch intel i7 laptop NiMH battery 10 hours less than 10lbs" has 12 terms in the keyword string: '`k=black%2017inch%20intel%20i7%20laptop%20NiMH%20battery%2010%20hours%20less%20than%2010lbs`' should be re-written as: '`k=black&k=17inch&k=intel%20i7%20laptop&k=NiMH%20battery&k=10%20hours&kless%20than%2010lbs`' Care must be taken to choose logical boundaries if specifying multiple '`k=`' parameters so as not to restrict phrase or exact match keyword targeting since each '`k=`' will be targeted individually i.e. from the example above: an ad targeting the phrase 'Intel i7' will not match '`k=intel&k=i7`' Impression search terms greater than 10 for end-user typed terms issued as direct values for the '`k=`' may be atypical. A more common case where this constraint is an issue is where both a user's keyword terms and machine generated '`k=`' terms are joined together as a string and submitted as a single '`k=`' parameter string. A good practice is to specify a '`k=`' for each set of terms created by your application and not the user. An example might be where you map the navigated location of your site onto keyword terms e.g. 'Home -> Products -> Electronics -> Computer -> Laptop -> Home -> Gaming -> Intel i7' Concatenating the above as terms to user inputted keyword terms may trigger this constraint.

Parameter

Constraint

k

If an impression request application is likely to have greater than 10 unique keyword parameter terms, parameter strings must be broken into multiple 'k=' parameters.

For example:
"black 17inch intel i7 laptop NiMH battery 10 hours less than 10lbs"

has 12 terms in the keyword string:

'k=black%2017inch%20intel%20i7%20laptop%20NiMH%20battery%2010%20hours%20less%20than%2010lbs'

should be re-written as:

'k=black&k=17inch&k=intel%20i7%20laptop&k=NiMH%20battery&k=10%20hours&kless%20than%2010lbs'

Care must be taken to choose logical boundaries if specifying multiple 'k=' parameters so as not to restrict phrase or exact match keyword targeting since each 'k=' will be targeted individually i.e. from the example above:
an ad targeting the phrase 'Intel i7' will not match 'k=intel&k=i7'

Impression search terms greater than 10 for end-user typed terms issued as direct values for the 'k=' may be atypical. A more common case where this constraint is an issue is where both a user's keyword terms and machine generated 'k=' terms are joined together as a string and submitted as a single 'k=' parameter string. A good practice is to specify a 'k=' for each set of terms created by your application and not the user.

An example might be where you map the navigated location of your site onto keyword terms e.g.

'Home -> Products -> Electronics -> Computer -> Laptop -> Home -> Gaming -> Intel i7'

Concatenating the above as terms to user inputted keyword terms may trigger this constraint.

Look and Feel Parameters

The look and feel for advertising content returned by the Cxense Advertising REST API can be customized. As with the search parameters described above, look and feel parameters can also be applied globally or to individual AdSpaces.

Parameter	Description	Default	Example
`lf-ac`	The ad colour. Standard text colour for text ads.	rgb(156,156,156)	`lf-ac=rgb(21,125,197)` `lf-ac=gray`
`lf-am`	The ad margin. This contains the margin to place around each ad being presented. Defaults to 0 if nothing is supplied.	`0`	`lf-am=10%2010%2010%2010` `lf-am=10px%2010`
`lf-bg`	The background colour for the presentation. Useful for setting a "site specific" colour so the ad presentation blends with the publisher's site.	rgb(255,255,255)	`lf-bg=rgb(0,0,0)` `lf-bg=black`
`lf-lc`	The link colour. This is the colour applied to the destination/display URL for the ad.	`rgb(84,176,18)`	`lf-lc=rgb(0,0,255)` `lf-lc=blue`
`lf-tc`	The title colour for the ad. This is the first line of a text creative.	`rgb(21,125,196)`	`lf-tc=rgb(0,255,255)` `lf-tc=cyan`
`lf-tmc`	The link title emphasis colour. This is invoked for matching criteria highlighting within an ads content. It has to be a different colour as the title is set to bold and there is no other way to define differentiate between matching criteria substitutions and the standard title text.	`rgb(21,125,196)`	`lf-tmc=rgb(255,140,0)` `lf-tmc=DarkOrange`
`lf-ata`	Ad text alignment (CSS text-align). All valid CSS values are valid here, e.g. 'left', right', 'center', 'justify', etc.	`left`	`lf-ata=center` `lf-ata=right`
`lf-af`	Base font to use for all text in the ad (CSS font shorthand property). All valid CSS values are valid here, e.g. font style, weight, size, line-height, font family, etc.	`12px/1.3em Verdana, Arial, Helvetica, sans-serif`	`lf-af=12px%20Tahoma`
`lf-tf`	Font to use for title text in the ad (CSS font shorthand property). All valid CSS values are valid here, e.g. font style, weight, size, line-height, font family, etc.	`12px/1.6em Verdana, Arial, Helvetica, sans-serif` (or set to value of lf-af if that is set)	`lf-tf=12px%20Tahoma`
`lf-lf`	Font to use for link text in the ad (CSS font shorthand property). All valid CSS values are valid here, e.g. font style, weight, size, line-height, font family, etc.	`12px/1.5em Verdana, Arial, Helvetica, sans-serif` (or set to value of lf-af if that is set)	`lf-tf=12px%20Tahoma`
`lf-atd`	Text decoration to use for all text in the ad (CSS text-decoration). All valid CSS values are valid here, e.g. underline, overline, line-through, etc.	`none`	`lf-atd=underline`
`lf-ttd`	Text decoration to use for title text in the ad (CSS text-decoration). All valid CSS values are valid here, e.g. underline, overline, line-through, etc.	`none`	`lf-ttd=overline`
`lf-ltd`	Text decoration to use for link text in the ad (CSS text-decoration). All valid CSS values are valid here, e.g. underline, overline, line-through, etc.	`none`	`lf-atd=none`
`lf-amfw`	Font weight to use for ad text with emphasis (see above) (CSS font-weight). All valid CSS values are valid here, e.g. bold, bolder, 600, etc.	`normal`	`lf-amfw=bolder`
`lf-tmfw`	Font weight to use for ad title text with emphasis (CSS font-weight). All valid CSS values are valid here, e.g. bold, bolder, 600, etc.	`normal`	`lf-tmfw=bold`

Impression Result

Element	Attribute	Description
`searchResult`		The impression search result container.
	`pageNumber`	The page number in the result set.
`previous`/`next`		For navigation of the result set. See the `pn=` search parameter above.
`space`		The matched space impression details.
	`id`	The AdSpace identifier provided by `asId=`.
`ads`		The matched ad impression sequence for the page.
`ad`		An impression instance.
	`id`	The unique identifier for the ad.
`creative`		An instance of the available Creative Templates described below.
`clickUrl`		The URL to that, if clicked, will register a click event to be processed.

Impression Result XML Format:

<?xml version="1.0" encoding="UTF-8"?>
<searchResult pageNumber="">
    <contentBaseURL></contentBaseURL>
    <previous></previous>
    <previous />
    <next></next>
    <next />
    <spaces>
        <space id="">
            <ads>
                <ad id="">
                    <!-- See Creative Template XML formats described below -->
                    <creative></creative>
                    <clickUrl></clickUrl>
                </ad>
            </ads>
        </space>
    </spaces>
</searchResult>

Ad Result Types

An ad impression has a Creative Template type:

Text
Image
Flash
Combo
Third Party

Note: If creating a smart-phone app or any other customer-facing interface that cannot be updated easily, be sure that the interface you're creating can handle all the different ad formats that your campaign is likely to use.

Common Creative XML Elements and Attibutes

Element	Attribute	Description
`creative`		An instance of a Creative Template type
	`formatVersion`	Version of the Creative Template type
	`id`	Unique identifier for the creative instance.
`destinationUrl`		The URL to request on click of the ad.
`contentBaseUrl`		The base URL to which you can append the content ID to form a complete reference to the media to display. Note that you can simply concatenate the ID to the base URL (the base URL will always end in a trailing slash or other valid terminator).

Text Creative

Element	Attribute	Description
`title`		The text creative title
`content`		The sequence of content lines for the creative.
	`contentLine`	Content on a Text Creative template may have several content lines.
`displayUrl`		The URL to render for display.

Text Creative Template XML Format:

<creative type="" formatVersion="" id="">
    <title></title>
    <content>
        <contentLine></contentLine>
    </content>
    <displayUrl></displayUrl>
    <destinationUrl></destinationUrl>
</creative>

Image Creative

Element	Attribute	Description
`contentServerId`		CDN location of image creative.
`source`		Complete URI of the image creative.
`description`		Description of the uploaded creative file.
`filename`		The file name of the creative uploaded.
`spec`		The Image Creative Template specifications.
	`height`	Height dimension of the creative.
	`width`	Width dimension of the creative.

Image Creative Template XML Format:

<creative type="" formatVersion="" id="">
    <contentServerId></contentServerId>
    <source></source>
    <description></description>
    <filename></filename>
    <spec>
        <height></height>
        <width></width>
    </spec>
    <destinationUrl></destinationUrl>
</creative>

Flash Creative

Element	Attribute	Description
`contentServerId`		Flash creative's location on CDN.
`imageContentServerId`		Flash creative's back-up image location on CDN.
`source`		Complete URI to the Flash creative.
`imageSource`		Complete URI to the Flash creative's back-up image.
`description`		Description of the uploaded creative file.
`filename`		The file name of the creative uploaded.
`imageFilename`		The file name of a backup image for the Flash creative.
`spec`		The Image Creative Template specifications.
	`key`	This will be blank once Error rendering macro 'jira' : com.atlassian.confluence.macro.MacroExecutionException: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target is deployed into production.
	`height`	Height dimension of the creative.
	`width`	Width dimension of the creative.
	`maxFileSize`	Maximum upload file size [KB].
`flashVersion`		Contains version information about respective `swf` file uploaded.
	`key`	The lookup key for the version.
	`version`	The numeric version of Flash.
`frameRate`		Number of frames per second.
	`key`	The lookup key for the frameRate.
	`frameRate`	The numeric number of frames per second.

Flash Creative Template XML Format:

<creative type="" formatVersion="" id="">
    <contentServerId></contentServerId>
    <imageContentServerId></imageContentServerId>
    <source></source>
    <imageSource></imageSource> 
    <description></description>
    <filename></filename>
    <imageFilename></imageFilename>
    <destinationUrl></destinationUrl>
    <spec>
        <key></key>
        <height></height>
        <width></width>
        <maxFileSize></maxFileSize>
    </spec>
    <flashVersion>
        <key></key>
        <version></version>
    </flashVersion>
    <frameRate>
        <key></key>
        <frameRate></frameRate>
    </frameRate>
</creative>

Combo Creative

Element	1st Level Attribute	2nd Level Attribute	Description
`title`			The combo creative title
`content`			The sequence of content lines for the creative.
	`contentLine`		Content on a Text Creative template may have several content lines.
`images`			A container for each of the uploaded images.
	`image`		A container for each of the uploaded image's information.
	`image:key`		Name of the image.
		`contentServerId`	CDN location of the combo creative's image.
		`source`	Complete URI of the combo creative's image.
		`filename`	The file name of the uploaded images.
		`height`	Height dimension of the creative.
		`width`	Width dimension of the creative.

Combo Creative Template XML Format:

<creative type="" formatVersion="" id="">
    <title></title>
    <content>
        <contentLine key=""></contentLine>
    </content>
    <images>
        <image key="">
            <contentServerId></contentServerId>
            <source></source>
            <href></href>
            <filename></filename>
            <height></height>
            <width></width>
        </image>
    </images>
    <destinationUrl></destinationUrl>
</creative>

Example

http://adserver.cxad.cxense.com/adserver/search?media=html&k=white&asId=0000000000027f7a&lf-lc=gray&lf-am=10%2010%2010%2010&cat=0000000000002735

HTML Result payload:

<html>
<head>
<title>render</title>
<style type="text/css" media="all">
    body { overflow: hidden; }
    body, span, ul, li, a {
        background: #fff;
        padding: 0;
        margin: 0;
        font: 12px / 14px Verdana, Arial, Helvetica, sans-serif;
    }
    div.ads {
        padding: 0;
        margin: 0;
    }
    a.ad {
        color: #9c9c9c;
        float: left;
        text-decoration: none;
        line-height: 1.3em;
        overflow: hidden;
        margin: 10 10 10 10;
    }
    a.ad img {
        border: none;
    }
    a.ad span.title {
        color: #157dc4;
        display:block;
        font-weight: bold;
        line-height: 1.6em;
    }
    a.ad span.title em {
        color: #157dc4;
        font-style: normal;
    }
    a.ad span.url {
        color: gray;
        text-decoration: underline;
        line-height: 1.5em;
    }
    a.ad em {
        font-weight: bold;
        font-style: normal;
    }
</style>
</head>
<body>
<div class="ads">
        <a class="ad" rel="nofollow" href="http://adserver.cxad.cxense.com/adserver/click/AAAAAAACf3oAAAAAAAJ_tAAAAAAAAn_nVjSDkc4oTX*rZ0Tif_QnvQ4wHzAuMTAwMDAwH0FVRAAAAAEAAAEvB18*zw--" target="_top" style="height: 70px; width: 225px;">
    <span class="title">TestCPCAd</span>
    <span class="body">
                    <span>Content1</span><br />
                    <span>Content2</span><br />
            </span>
        <span class="url">www.cxense.com</span>
    </a>
    </div>
</body>
</html>

XML Result payload:

<?xml version="1.0" encoding="UTF-8"?>
<searchResult pageNumber="1">
    <contentBaseURL>http://adserver.cdn.cxense.com/content/_cid_</contentBaseURL>
        <previous />
            <next />
        <spaces>
                <space id="0000000000027f7a">
            <ads>
                                <ad id="0000000000027fb4">
                    <creative type="com.fastsearch.admomentum.plugins.textcreative.feature.TextCreativeFeature" formatVersion="1.0" id="0000000000027fe7">
    <title>TestCPCAd</title>
    <content>
            <contentLine>Content1</contentLine>
            <contentLine>Content2</contentLine>
        </content>
    <displayUrl>www.cxense.com</displayUrl>
    <destinationUrl>http://www.cxense.com</destinationUrl>
</creative>                    <clickUrl>http://adserver.cxad.cxense.com/adserver/click/AAAAAAACf3oAAAAAAAJ_tAAAAAAAAn_n1e2Ko1w6TaCcOUKHFVBfAw4wHzAuMTAwMDAwH0FVRAAAAAEAAAEvB17UuA--</clickUrl>
                </ad>
                            </ads>
        </space>
            </spaces>
</searchResult>

Third-Party Creative

Element	1st Level Attribute	2nd Level Attribute	Description
`title`			The third-party creative title
`contentServerId`			Complete URI of the first image found in a third-party creative (unlike for other creatives, this image will not be found on the CDN as it will be hosted by a third-party)
`source`			Complete URI of the first image found in a third-party creative.
`thirdPartyFields`			A container for the fields of data inputted for the third party.
	`field`		The field name and raw data inputted.
`extractedThirdPartyData`			A container for the third party data that has been extracted from the data inputted.
	`thirdPartyImage`		A container for each of the third-party images that have been extracted from the third party data.
		`imgSrc`	The third-party image's source.
		`imgWidth`	The third-party image's width.
		`imgHeight`	The third-party image's height.
		`imgAlt`	The third-party image's alt text.
		imgBorder	The third-party image's border.
`destinationUrl`			The URL for the click.

Third-Party Creative Template XML format:

<creative type="" formatVersion="" id="">
     <title></title>
     <contentServerId></contentServerId>
     <source></source> 
     <thirdPartyFields>
          <field key=""></field>
     </thirdPartyFields>
     <extractedThirdPartyData>
          <thirdPartyImage>
               <imgSrc></imgSrc>
               <imgWidth></imgWidth>
               <imgHeight></imgHeight>
               <imgAlt></imgAlt>
               <imgBorder></imgBorder>
          </thirdPartyImage>
     </extractedThirdPartyData>
     <destinationUrl></destinationUrl>
</creative>

JavaScript Cxense Advertising Search API

The JavaScript search API provides a method to make advertising search requests directly from content e.g. an HTML web page would have the JavaScript embedded into the appropriate location to render advertising content returned by the search.

The JavaScript search API makes an asynchronous call to the Cxense Advertising platform to optimize the experience of the user with the native content of the page.

The initial JavaScript code snippet to use can be obtained from the applicable Publishing space AdSpace Script tag. The script snippet has two script elements that:

loads the core cX JavaScript library; and
inserts an AdSpace into the host content.

The script works for both HTTP and HTTPS pages. The schema selection is automatic, so it does not need to be configured. Also refer to our Advanced javascript examples page for information on template-driven rendering for ad presentation.

The script which loads the Cxense Advertising JavaScript library of functions need not be changed and should be inserted into host content as is. An example of this script is as follows:

<!-- The cX library script is loaded -->
<script type="text/javascript">
  (function() { try { var scriptEl = document.createElement('script'); scriptEl.type = 'text/javascript'; scriptEl.async = 'async';
  scriptEl.src = ('https:' == document.location.protocol) ? 'https://scdn.cxense.com/cx.js' : 'http://cdn.cxense.com/cx.js';
  var targetEl = document.getElementsByTagName('script')[0]; targetEl.parentNode.insertBefore(scriptEl, targetEl); } catch (e) { }; } )();
</script>

Each snipped copied from the AdSpace definition from the Cxense Advertising UI will include the above script to load the cX JavaScript library. If multiple AdSpaces are inserted into host content, the above script snippet need only be inserted once; however, separation of the the load script is not required.

The code snippet obtained from the Cxense Advertising UI also includes the AdSpace insertion call insertAdSpace is shown below:

<!-- AdSpace insertion -->
<script id="scriptForAdSpace_0000000000004748" type="text/javascript">
  var cX = cX || {}; cX.callQueue = cX.callQueue || [];
  cX.callQueue.push(['insertAdSpace', {
    adSpaceId: '0000000000004748',
    adUnitWidth: 300, adUnitHeight: 250,
    initialHorizontalAdUnits: 1, initialVerticalAdUnits: 2
  }]);
</script>

The code above asynchronously executes the a call to search Cxense Advertising platform for advertising impressions. The result, should there be criterion matches for the AdSpace will be the default HTML result containing the ads. The advertising result format is defined in the Cxense Advertising REST API definition.

The insertAdSpace call in the AdSpace insertion script above contains the following parameters. None of the parameters require modification from the code snipped copied from the Cxense Advertising UI, but are as follows for reference:

Parameter	Description	Default
`adSpaceId`	The AdSpace identifier	n/a - obtain from the UI. Does not change.
`adUnitWidth`	(Optional) The width per ad unit in the result set	0
`adUnitHeight`	(Optional) The height per ad unit in the result set	0
`initialHorizontalAdUnits`	(Optional) Defines the anticipated number of units to receive on the dimension ¹	0
`initialVerticalAdUnits`	(Optional) Defines the anticipated number of units to receive on the dimension ¹	0
`width`	(Optional) Absolute sizing option. Use this if the adspace has a size that is not a multiple of the adUnitWidth	N/A
`height`	(Optional) Absolute sizing option. Use this if the adspace has a size that is not a multiple of the adUnitHeight	N/A
`backend`	(Otional) The Cxense Advertising platform backend to use. Can be either "production" or "sandbox".	"production"
`delayImpression`	(Optional) Delay the ad space impression and rendering until the ad space becomes visible (scrolled into view)	false
`appendToElementId`	(Optional) The id of any element to append the ads into in the DOM tree	N/A
`insertBeforeElementId`	(Optional) The id of any element to insert the ads before in the DOM tree²	Defaults to an element with id: 'insertAdSpaceBeforeThis_' + adSpaceId (used to be 'scriptForAdSpace_' + adSpaceId, and that will still work (backwards compatible))
`resizeToContentSize`	(Optional) Set to true to allow text content to overflow the ad unit size in the vertical direction.	false
`onImpressionResult`	(Optional) Reference to a function that will received a callback when receiving impressions results	N/A
`renderTemplateUrl`	(Optional) The URL of the render template to use for the layout of the ad space	N/A
`uhm`	(Optional) Use the URL hash fragment on IE6 and IE7 for cross-frame messaging	false
`useMappedRenderTemplate`	(Optional) Use the render template that has been mapped to this adSpaceId in the Render Template Mapper	false
`baseAdDeliveryUrl`	(Optional) The Cxense Advertising platform REST URL to use. If possible, use the "backend" paremeter instead.	The Cxense Advertising platform URL on which the space was created e.g. production/sandbox/dev/demo
`secureBaseAdDeliveryUrl`	(Optional) Same as above, but for HTTPS. If possible, use the "backend" paremeter instead.	The Cxense Advertising platform HTTPS URL on which the space was created e.g. production/sandbox/dev/demo

¹ The number of units will be constrained by the original AdSpace creation.

² The adspace is inserted before the element (not inside) to avoid size contraint problems with elements that have default styles specifying margins and padding.

Specifying Cxense Advertising search API Parameters

The default AdSpace insertion JavaScript snippet obtained from the UI can be modified to include additional Cxense Advertising REST API parameters. Parameters can be added:

Globally; or
To individual AdSpace insertion requests.

The example AdSpace insertion above does not include REST API parameters: an AdSpace associated to a CPM product need not have parameters for example. However, REST API parameters can be added to the JavaScript executed request. The following example shows global parameters set using the variable cx_props.

Targeting parameters
- k, keyword
- cat, category
Look and Feel parameters
- lf-am, ad margin
- lf-ac, ad color

Whether an lf- parameter is set globally or by individual space insertion, the name of the lf- parameters used in the JavaScript API must be quoted. e.g.
'lf-lc':'red'

The effect of adding the cx_props variable is that all AdSpaces inserted into the host content by the JavaScript API will have the same parameters appliet to their Cxense Advertising REST API request i.e. Similar to

http://adserver.cxad.cxense.com/adserver/search?media=html&k=white&asId=0000000000027f7a&lf-lc=red&lf-am=10%2010%2010%2010&cat=0000000000002735

<script type="text/javascript">
  var cx_props = { k: 'volvo',
                   cat: '0000000000002735',
                   'lf-ac': 'red',
                   'lf-am': '10px 10px 10px 10px'};
</script>
 
<!-- AdSpace insertion -->
<script id="scriptForAdSpace_0000000000004748" type="text/javascript">
  var cX = cX || {}; cX.callQueue = cX.callQueue || [];
  cX.callQueue.push(['insertAdSpace', {
    adSpaceId: '0000000000004748', baseAdDeliveryUrl: 'http://cxad.cxense.com/adserver/search',
    adUnitWidth: 300, adUnitHeight: 250, initialHorizontalAdUnits: 1, initialVerticalAdUnits: 2,
    parentId: '00000000000001e7'}]);
</script>

Alternatively, parameters can be added directly to an individual AdSpace insertion script as follows:

<!-- AdSpace insertion -->
<script id="scriptForAdSpace_0000000000004748" type="text/javascript">
  var cX = cX || {}; cX.callQueue = cX.callQueue || [];
  cX.callQueue.push(['insertAdSpace', {
    adSpaceId: '0000000000004748', baseAdDeliveryUrl: 'http://cxad.cxense.com/adserver/search',
    adUnitWidth: 300, adUnitHeight: 250, initialHorizontalAdUnits: 1, initialVerticalAdUnits: 2,
    parentId: '00000000000001e7',
    k: 'volvo',
    cat: '0000000000002735',
    'lf-ac': 'red',
    'lf-am': '10px 10px 10px 10px'}]);
</script>

Specifying keywords

Keywords can be added to the ad search request by setting the 'k' property:

<script type="text/javascript">
  var cx_props = { k: 'volvo' };
</script>
  
 
<!-- Normal loading of the cX script -->
<script type="text/javascript">
  (function() { try { var scriptEl = document.createElement('script'); scriptEl.type = 'text/javascript'; scriptEl.async = 'async';
  scriptEl.src = ('https:' == document.location.protocol) ? 'https://scdn.cxense.com/cx.js' : 'http://cdn.cxense.com/cx.js';
  var targetEl = document.getElementsByTagName('script')[0]; targetEl.parentNode.insertBefore(scriptEl, targetEl); } catch (e) { }; } )();
</script>
  
<!-- Normal AdSpace insertion -->
<script id="scriptForAdSpace_0000000000004748" type="text/javascript">
  var cX = cX || {}; cX.callQueue = cX.callQueue || [];
  cX.callQueue.push(['insertAdSpace', {
    adSpaceId: '0000000000004748', baseAdDeliveryUrl: 'http://sandbox.cxad.cxense.com/adserver/search',
    adUnitWidth: 300, adUnitHeight: 250, initialHorizontalAdUnits: 1, initialVerticalAdUnits: 2,
    parentId: '00000000000001e7'}]);
</script>

The keywords property can also be set on each AdSpace individually:

<!-- Normal loading of the cX script -->
<script type="text/javascript">
  (function() { try { var scriptEl = document.createElement('script'); scriptEl.type = 'text/javascript'; scriptEl.async = 'async';
  scriptEl.src = ('https:' == document.location.protocol) ? 'https://scdn.cxense.com/cx.js' : 'http://cdn.cxense.com/cx.js';
  var targetEl = document.getElementsByTagName('script')[0]; targetEl.parentNode.insertBefore(scriptEl, targetEl); } catch (e) { }; } )();
</script>
  
<!-- AdSpace insertion -->
<script id="scriptForAdSpace_0000000000004748" type="text/javascript">
  var cX = cX || {}; cX.callQueue = cX.callQueue || [];
  cX.callQueue.push(['insertAdSpace', {
    adSpaceId: '0000000000004748', baseAdDeliveryUrl: 'http://sandbox.cxad.cxense.com/adserver/search',
    adUnitWidth: 300, adUnitHeight: 250, initialHorizontalAdUnits: 1, initialVerticalAdUnits: 2,
    k: 'volvo',
    parentId: '00000000000001e7'}]);
</script>

Customising the look and feel of results.

Customising the look and feel of search results is done by adding parameters to the request for ads. The actual parameter names/details are outlined in ImpressionRequest. The actual provision of these parameters is done through the JavaScript code currently inserted into the publishers page. The code snippet below shows how these parameters can be supplied. All of these parameters are optional as we have our default colour scheme that is used, however if the publisher wishes to change the presentation they can feel free to do so.

Parameters are prefixed with "lf-" for "look and feel" to hopefully prevent any clashes with ActionConstant values used by search. Basic details are listed below for each of the current parameters however the JavaDoc for ImpressionRequest should be consulted for the most up-to-date information.

lf-ac: the ad colour. Standard text colour for text ads.
lf-am: the ad margin. This contains the margin to place around each ad being presented. Defaults to 0 if nothing is supplied.
lf-bg: the background colour for the presentation. Useful for setting a "site specific" colour so the ad presentation blends with the publisher's site.
lf-lc: the link colour. This is the colour applied to the destination/display URL for the ad.
lf-tc: the title colour for the ad. This is the first line of a text creative.
lf-tmc: the link title emphasis colour. This is invoked for matching criteria highlighting within an ads content. It has to be a different colour as the title is set to bold and there is no other way to define differentiate between matching criteria substitutions and the standard title text.

<script type="text/javascript">
    var cx_props = {
        "lf-ac": "white",
        "lf-am": "10px 3em",
        "lf-bg": "rgb(0,0,0)",
        "lf-lc": "white",
        "lf-tmc": "orange"
    };
</script>
  
<!-- Loading of the cX script -->
<script type="text/javascript">
  (function() { try { var scriptEl = document.createElement('script'); scriptEl.type = 'text/javascript'; scriptEl.async = 'async';
  scriptEl.src = ('https:' == document.location.protocol) ? 'https://scdn.cxense.com/cx.js' : 'http://cdn.cxense.com/cx.js';
  var targetEl = document.getElementsByTagName('script')[0]; targetEl.parentNode.insertBefore(scriptEl, targetEl); } catch (e) { }; } )();
</script>
  
<!-- AdSpace insertion -->
<script id="scriptForAdSpace_0000000000004748" type="text/javascript">
  var cX = cX || {}; cX.callQueue = cX.callQueue || [];
  cX.callQueue.push(['insertAdSpace', {
    adSpaceId: '0000000000004748', baseAdDeliveryUrl: 'http://sandbox.cxad.cxense.com/adserver/search',
    adUnitWidth: 300, adUnitHeight: 250, initialHorizontalAdUnits: 1, initialVerticalAdUnits: 2,
    parentId: '00000000000001e7'}]);
</script>

The look and feel can also be set on each AdSpace individually:

<!-- Loading of the cX script -->
<script type="text/javascript">
  (function() { try { var scriptEl = document.createElement('script'); scriptEl.type = 'text/javascript'; scriptEl.async = 'async';
  scriptEl.src = ('https:' == document.location.protocol) ? 'https://scdn.cxense.com/cx.js' : 'http://cdn.cxense.com/cx.js';
  var targetEl = document.getElementsByTagName('script')[0]; targetEl.parentNode.insertBefore(scriptEl, targetEl); } catch (e) { }; } )();
</script>
 
<!-- AdSpace insertion -->
<script id="scriptForAdSpace_0000000000004748" type="text/javascript">
  var cX = cX || {}; cX.callQueue = cX.callQueue || [];
  cX.callQueue.push(['insertAdSpace', {
    adSpaceId: '0000000000004748', baseAdDeliveryUrl: 'http://sandbox.cxad.cxense.com/adserver/search',
    adUnitWidth: 300, adUnitHeight: 250, initialHorizontalAdUnits: 1, initialVerticalAdUnits: 2,
    "lf-ac": "white",
    "lf-am": "10px 3em",
    "lf-bg": "rgb(0,0,0)",
    "lf-lc": "white",
    "lf-tmc": "orange",
    parentId: '00000000000001e7'}]);
</script>

Setting query parameter from URL parameter

In a setting where you are adding ads to a search page, you might want to pass on the query that the user has typed in to the adserver.

You can pass the query in the 'k' parameter. If you have the user's query in a URL parameter, it can be read out and passed along to the adserver like this:

// Read a page's GET URL variables and return them as an associative array
function getUrlVars() {
    var vars = [], hash;
    var hashes = window.location.href.slice(window.location.href.indexOf('?') + 1).split('&');
    for(var i = 0; i < hashes.length; i++) {
        hash = hashes[i].split('=');
        vars[decodeURIComponent(hash[0])] = decodeURIComponent(hash[1].replace(/\+/g, ' '));
    }
    return vars;
}
 
// Read the query input string from the 'q' URL parameter, as in a URL like:
// http://my.site.com/search?q=cars
   
var cx_props = { k: getUrlVars()['q'] };

Controlling ad space resizing

In the normal case, the ad space is rendered in an IFrame with an initial size, and after the ad impression results have been received from the ad server, the iframe is resized to fit the number of ads returned.

You can control the resizing of an iframe by two methods:

The "resizeToContentSize" parameter
In a custom onImpressionResult handler function

The iframe is always resized. The difference is the method used to resize it.

Normal resizing

In the normal case, it is the number of ads returned that controls the resizing. The size is calculated from the number of ads like this:

If the adspace is horzontal, calculate new width:

new width = number of ads returned * (adUnitWidth + marginLeft + marginRight)

If the adSpace is vertical, calculate new height.

new height = number of ads returned * (adUnitHeight + marginTop + marginBottom)

And so the adSpace resizes to a new size that is a multiple of the ad unit height or width + margins.

The "resizeToContentSize" flag

But in some cases, the returned ads have different heights. This can happen if one ad has just one line of text, but the second ad has three lines of text.

The "resizeToContentSize" flag specifies that:

Each ad unit is sized with a minimum height of adUnitHeight (and not a fixed height)
The new height is the sum (not the multiple) of the ad heights for the individual ads

E.g, if I have two ads returned, and the first has one line of text and the second ad has three lines of text:

Ad1: 1 line of text, height: 40px;
Ad2: 3 lines of text, height: 62px;

Then, when the "resizeToContentSize" is set to true, the adSpace is resized to the size of the actual content, and not the number of ads,
and in this case that becomes:

new height = height of ad1 + height of ad2 = 40px + 62px = 102px

Custom resizing

If you do not want the resizing to happen at all, you can do like this:

function myOnImpressionResult(event) {
    return false; // Cancel this event to prevent automatic resizing
}
cX.callQueue.push(['insertAdSpace', {
    adSpaceId: '<adSpaceId>',
    adUnitWidth: 300, adUnitHeight: 250,
    initialHorizontalAdUnits: 1, initialVerticalAdUnits: 1,
    onImpressionResult: myOnImpressionResult
} ]);

Also, you can do any other type of resizing in this handler, like:

Resize the content in a different way
Resize other element (like outer frames or border objects) as well as the iframe (return true or no return to keep default sizing of the iframe).

Specifying the target window / frame for ad clicks

This function is now available within the Adspace configuration page (Publishing > Folder > AdSpace > Configuration), as such, this functionality is no longer required to manually set.

The target of an ad click can be set with the clickTargetFrame parameter. As describe above, it can be set globally or on an individual AdSpace.

The value can be any of the standard HTML special names (e.g. "_blank", "_top", etc.) or any name of a frame, iframe or window.

The default value is "_top".

<script type="text/javascript">
  var cx_props = { clickTargetFrame: '_blank'}; // Ad click opens in a new window.
</script>

Opening a custom-styled window in the onclick handler

Sometimes it's desirable to let an ad open the destination URL in a custom-styles window / popup when clicked.

That can be set by providing the wanted styling in the following parameter:

var cx_props = { onclickWindowOpenParams: '<windowName>|<openSpecs>' };

The windowName and openSpecs parts are the same as with any normal call top window.open(..):

Adding some sample values, gives something like:

var cx_props = { onclickWindowOpenParams: 'myWindowName|width=480,height=635,left=50,top=50,screenX=50,screenY=50,toolbar=no,location=no,directories=no,status=no,menubar=no,scrollbars=no,resizable=yes,copyhistory=no' };

Note that this will work only on text and image creatives. Flash will take the click event and it's up to the Flash ad how to deal with the click.

Adding custom publisher click tracking

A custom click tracker can be added by setting the "destinationUrlPrefix" parameter (or the short-form "dup").

The value if this parameter will be prepended to the destination URL. The concatenation is done by just putting the one string in front of the other. No escaping is performed.

<script type="text/javascript">
  var cx_props = { destinationUrlPrefix: 'http://a.com/trackClick?url=' };
</script>

If the original destination URL is "http://advertiser1.com/" then the browser will be redirected to the URL:

http://a.com/trackClick?url=http://advertiser1.com/

The click tracker must extract the real destination URL, and finally redirect the browser to this URL.

Passing custom variables from publisher page through to destination URL

Custom parameters can be passed through to the destination URL by setting the "destinationUrlParameters" property:

<script type="text/javascript">
  var cx_props = { destinationUrlParameters: { site: '01', article: '271', link: '487', image: '489' } };
</script>

<!-- AdSpace insertion --><script id="scriptForAdSpace_0000000000004748" type="text/javascript">
 var cX = cX || {}; cX.callQueue = cX.callQueue || [];
 cX.callQueue.push(['insertAdSpace', {
 adSpaceId: '0000000000004748', baseAdDeliveryUrl: 'http://cxad.cxense.com/adserver/search',
 adUnitWidth: 300, adUnitHeight: 250, initialHorizontalAdUnits: 1, initialVerticalAdUnits: 2,
 parentId: '00000000000001e7', destinationUrlParameters: { site: '01', article: '271', link: '487', image: '489' }}]);
</script>

The custom parameters are added to the configured destination URL, and the resulting request will look like this:

http://www.somesite.com/page.html?site=01&article=271&link=487&image=489

The system automatically handles whether it should use "?" or "&" for the first parameter.

NB! In the current release, the destination URL cannot have it's URL path component completely missing (to make sure that a valid URL is constructed). The URL path can be as short as just "/", but is must be present.

Examples:

Good: "http://a.com/", "http://a.com/a", "http://a.com/a.html", "http://a.com/a.jsp?b=1&c=2"
The only bad: "http://a.com" (URL path component completely missing)

Last updated: January 19, 2022