JavaScript OX Instance Methods

Use this method to tell the tag library to fetch an ad for the specified ad unit when the fetchAds method is called. You can call this method multiple times using the same or different ad unit IDs (for example, for a multi-ad unit request).

If you call this method multiple times, ads are requested for each ad unit specified. If you specify the same ad unit multiple times, multiple ads are requested for the same ad unit.

Parameters

Example

OX_string.addAdUnit("auid");

Where 12345 is a random string and auid is the ad unit ID.

Use this method to indicate the ID of the node in the predefined content topic taxonomy that matches the content in the current page view. Frequently, it may be implemented dynamically by a content management system. The ID is included with each ad request made from the instance of the OX object, as the tid parameter.

You need to call this method before the fetchAds method is called.

Parameters

Example

OX_string.addContentTopic("51")

Where 51 is the node ID for the content topic of the current page.

This method adds OpenRTB data to the ad request so that it can be passed to buyers in the OpenX Ad Exchange. Specify OpenRTB values as a key path, such as app.ver, where app represents the App object of the BidRequest and ver is an App object field representing the version of the mobile app.

You must pass this method before the fetchAds and load methods.

Parameters

Example

OX_string.addOpenRTBParameter("imp[0].banner.w", 320);
OX_string.addOpenRTBParameter("imp[0].banner.h", 50);
OX_string.addOpenRTBParameter("app.ver", "1.0");
OX_string.addOpenRTBParameter("app.paid", 0);
OX_string.addOpenRTBParameter("app.keywords", "games");

Where:

• string: A random string.

• "imp[0].banner.w", 320: The path to the Imp object’s w field, which expresses the width of the ad unit in pixels.

• "imp[0].banner.h", 50: The path to the Imp object’s h field, which expresses the height of the ad unit in pixels.

• "app.ver", "1.0": The path to the App object’s ver field, which provides the mobile app’s version string.

• "app.paid", "0": The path to the App object’s paid field, where 0 means the app is free and 1 means the app is a paid version.

• "app.keywords", "games": The path to the App object’s keywords field, which provides a comma-delimited list of keywords for the app.

Set the user’s advertising ID and whether or not the user has requested for ad tracking to be limited.

Parameters

Example

OX_12345.setAdvertisingID("43043FE3-6BA9-4515-8209-6E0AC6AE1ADF", false);

This method is similar to the addAdUnit method, but instead of queuing a request for a single ad unit, it queues a request for all of the ad units referenced by the predefined ad unit group via its pgid (page ID) value.

The addPage method tells the OpenX JavaScript tag library to fetch ads for all of the ad units in the specified ad unit group when the fetchAds (for synchronous tags) or load method (for asynchronous tags) is called.

You can call addAdUnit multiple times to fetch ads for multiple ad units for a given pgid.

This method does not actually fetch ads, it queues a pgid to fetch ads for when fetchAds or load is finally called.

Parameters

Example

OX_12345.addPage("123");

Where 123 is the pgid for the predefined ad unit group that you want to request ads for.

Use this method to add a custom variable to the ad requests that come from the OX object instance. You must pass this method before the fetchAds method.

Parameters

Setting custom variables

A request to set a custom variable for the user’s gender might look like the following:

OX_12345.addVariable("gender","male");

Where gender is the custom key and male is the custom value.

addVariable in standalone tags

A standalone synchronous JavaScript ad tag with the addVariable method might look like the following:

<script type="text/javascript"
src="http://delivery_server_domain/w/1.0/jstag">
</script>

<script>
var OX_4d6552943f5a4 = OX();
OX_4d6552943f5a4.addAdUnit("54321");
OX_4d6552943f5a4.addVariable("gender", "male");
OX_4d6552943f5a4.fetchAds();
</script>

<script type="text/javascript">
OX_4d6552943f5a4.showAdUnit("54321");
</script>

Where:

• src="http://delivery_server_domain/w/1.0/jstag: A request to fetch the OpenX JavaScript tag library.

• var OX_4d6552943f5a4 = OX();: Create a new OX object and assign it to a global variable with a pseudo-random name.

• .>OX_string: A variable, which is included in some tags by the OpenX tag generator. You should replace this string with an identifier of your choosing.

• OX_4d6552943f5a4.addVariable("gender","male");: The addVariable method specifying a custom KVP.

• OX_4d6552943f5a4.fetchAds();: The fetchAds method, which must be passed after addVariable.

• OX_4d6552943f5a4.showAdUnit("54321");: The showAdUnit method, which shows the ads returned to the fetchAds method.

Setting multiple custom variables

You can set custom variables for an ad unit group request or a multi-ad unit request ad tag. To do this, repeat the addVariable method for each custom variable you want to set for the request. For example, to set custom variables for an ad unit group request ad tag (in this case, gender, age, and keyword), your request might look like the following:

...
OX_random_string.addVariable("gender","f");
OX_variable_string.addVariable("age","40");
OX_variable_string.addVariable("keyword","coupon");
...

Ad unit group requests

The header portion of an ad unit group request (using the addPage method) ad tag might look like the following:

<script type="text/javascript"
src="http://delivery_server_domain/w/1.0/jstag">
</script>

<script type="text/javascript">
var OX_12345 = OX();
OX_string.addPage("3");
OX_string.addVariable("gender","f");
OX_string.addVariable("age","40");
OX_string.addVariable("keyword","coupon");
OX_string.fetchAds();
</script>

Multi-ad unit requests

A multi-ad unit request ad tag might look like the following:

<script src="http://delivery_server_domain/w/1.0/jstag">
</script>

<script>
var OX_12345 = OX();
OX_string.addAdUnit("54321");
OX_string.addAdUnit("98765");
OX_string.addVariable("gender","f");
OX_string.addVariable("age","40");
OX_string.addVariable("keyword","coupon");
OX_string.fetchAds();
</script>

Multiple values for the same custom variable

You can use this format to set multiple values for the same custom variable:

OX_string.addVariable("keyword","coupon,discount,rebate");

Use this method to disable market (OpenX Ad Exchange) for the ad request. This allows you to opt out of the Ad Exchange on a per-impression basis.

Example

OX_string.disableMarket();

Use this method to disable audience segmentation for the ad request. This method sets the ns parameter of the requestAd method.

Example

OX_string.disableSegmentation();

Use this method to enable market (OpenX Ad Exchange) for the ad request.

Example

OX_string.enableMarket();

Use this method to enable audience segmentation for the ad request. This method sets the ns parameter of the requestAd method to null.

Example

OX_string.enableSegmentation();

For synchronous JavaScript ad tags, use the this method to invoke an ad request to OpenX using all inputs from other methods. The ads returned from OpenX are not immediately displayed, but are stored by the OpenX JavaScript tag library for display later.

Example

OX_string.fetchAds();

Use this method to enable framing (true) or disable it (false) for all creatives of an OX object instance. If not set, it defaults to that set for the instance.

If set at both the page and instance levels, the OpenX JavaScript tag library uses the instance setting. This affects all ad units associated with the instance.

These settings are overridden by features that automatically add iframes, such as auto-refresh.

Example

OX_string.frameCreatives(true);

For asynchronous ad tags, use this method to invoke and ad request to OpenX and to display the selected ads using all of the inputs set via other methods.

Call this method after all of the placeholder elements have loaded for the webpage. That is, the script block that contains this call cannot go in <head>.

Example

OX_string.load();

Use this method to set a fallback ad to serve for a specific ad unit, when OpenX has no ad to serve for an ad request.

For synchronous calls, you must call this method before showAdUnit. Otherwise, it will not work.

NOTE

Macro expansion is not supported in third-party fallback tags set in the ad tag.

Parameters

Example

OX_string.setAdUnitFallback("999999","<iframe src='http://www.mywebsite.com'></iframe>");

Use this method to set a third-party impression beacon for the ad request. The third-party impression beacon is only triggered when OpenX delivers an actual ad (that is, not a fallback ad).

You cannot pass undefined as a value for the imp_beacon parameter for this method, so you cannot remove a third-party impression beacon after it is set.

For synchronous calls, you must call this method before showAdUnit. Otherwise, it will not work. Furthermore, macro expansion is not supported in third-party impression beacons set in the ad tag.

Parameters

Example

OX_string.setAdUnitImpBeacon( "12345","<iframe src='example.com'></iframe>");

Use this method to set the aumf parameter of the ad request, which is a combination of the ad unit ID (auid) and the floor price. The aumf parameter can also be set via the ad request initialization object.

setAdUnitMarketFloor(auid, floor)

Parameters

Example

The following example sets the ad unit market floor for ad unit 538156269 to 1000 micros ($1.00 CPM).

OX_string.setAdUnitMarketFloor(538156269, 1000);

Use this method to set the floor for non-guaranteed line items for a specific ad unit. This method sets the aungf parameter of the ad request. When set, it filters out all other market floors as well as any non-guaranteed line items that do not meet this floor.

setAdUnitNGFloor(auid, floor)

Parameters

Example

The following example sets the ad unit non-guaranteed line floor for ad unit 538759143 to 12000 micros ($12.00 CPM).

OX_string.setAdUnitNGFloor(538759143, 12000);

Use this method to set the non-guaranteed market floor for a specific ad unit. This method sets the aungf parameter of the ad request.

OX_string.setAdUnitNGFloor();

For asynchronous ad tags, use this method to associate the ID for the placeholder element (<div>) with the ad unit.

Parameters

Example

OX_string.setAdUnitSlotId("98765","exampleAd1");

Use this method to set the desired browser window target for ad clicks in the page.

Parameters

Example

OX_string.setAnchorTarget("_blank");

Set the API frameworks supported by a mobile app, such as MRAID 2.0. This method supports an array of parameters representing the supported API frameworks.

Parameters

If you use this method, you must specify at least one of its supported parameters.

Examples

Setting the API frameworks supported by mobile app:

OX_string.setAPIFrameworks([3,5]);

Alternatively, you can use the following standalone JavaScript ad tag to set the af (API frameworks) parameter:

OX.requestAd({
    "auid":"12345",
    "af":[3,5]
});

Set the bundle (“package”) ID of the mobile app in which the tag is running.

Parameters

Examples

Setting mobile app bundle IDs:

OX_12345.setBundleID("com.openx.openxdemo");

Alternatively, you can use the following standalone JavaScript ad tag to set the appBundle parameter:

OX.requestAd({
    "auid":"12345",
    "appBundle":"com.openx.openxdemo"
});

Set the name of the mobile app in which the tag is running.

Parameters

Examples

Setting mobile app names:

OX_string.setAppName("OpenX Demo");

Alternatively, you can use a standalone requestAd JavaScript ad tag to set the appName parameter:

OX.requestAd({
    "auid":"12345",
    "appName":"OpenX Demo"
});

Set the app store URL from which the mobile app can be downloaded.

Parameters

Examples

Setting the app store URL for mobile apps:

OX_string.setAppStoreURL("http://itunes.apple.com/us/app/bee-leader/id580743157?mt=8");

Alternatively, you can use the following standalone JavaScript ad tag to set the appStoreURL parameter:

OX.requestAd({
    "auid":"12345",
    "appStoreURL":"http://itunes.apple.com/us/app/bee-leader/id580743157?mt=8"
});

Use this method to set the click redirect URL for an ad request. This method sets the r parameter of the ad request (which represents the click redirect URL).

Example

OX_string.setClickRedirectURL();

Set the geolocation for the ad request. This method is useful for mobile web or mobile apps, where the publisher may have access to accurate GPS location data.

Parameters

Examples

Setting geolocation for ad requests:

OX_string.setCoords({
	"latitude":"34.1496085",
	"longitude":"-118.1330328"
});

Alternatively, you can use the following standalone JavaScript ad tag to set the coords (API frameworks) parameter:

OX.requestAd({
    "auid":"12345",
    "coords":{
        "latitude":"34.1496085",
        "longitude":"-118.1330328"
    }
});

Use this method to set the base URL of the delivery gateway to use for this ad request. The OpenX JavaScript tag library will append the appropriate strings to this URL that are necessary to call the gateway. Typically, you do not have to call this method because the ad tags generated by the system will provide this configuration.

Parameters

Example

OX_string.setGateway("http://delivery_server_domain/w/1.0/");

Where:

• string: A random string.

• http: The protocol. If your ad space uses SSL/TLS, use https instead.

• delivery_server_domain: The hostname of your OpenX delivery server.

• /w: Indicates the web delivery medium.

• /1.0: Indicates version 1.0 of the OpenX JavaScript tag protocol.

This method specifies OpenRTB-compliant data passed to Ad Exchange buyers via the ad request. Depending on your use case, you can specify the data in a JavaScript object literal or as a JSON string. You must pass this method before the fetchAds and load methods.

Parameters

Examples

setOpenRTBParameter object literal:

OX_string.setOpenRTBParameters({
    auid: "12345",
    openrtb: {
        imp: [
            { banner:

{ w: 320, h: 50 } }
        ],
        app: {
            ver: "1.0",
            paid: 0,
            keywords: "games",
        }
    }
});

Where:

• string: A random string of your choosing.

• auid: The ad unit ID for the ad to be displayed.

• openrtb: Indicates OpenRTB parameters.

• imp: Corresponds to the OpenRTB Imp object.

• banner: Corresponds to the OpenRTB Banner object.

• { w: 320, h: 50 }: Specifies the width and height of the ad unit in pixels.

• app: Corresponds to the OpenRTB App object.

• ver: "1.0": The version string of the mobile app.

• paid: 0: The App object’s paid field, where 0 means the app is free and 1 means the app is a paid version.

• keywords: "games": The App object’s keywords field, which provides a comma-delimited list of keywords for the app.

setOpenRTBParameters JSON string

This string corresponds to the object literal above.

OX_12345.setOpenRTBParameters('{"auid":"12345","openrtb":{"imp":[{"banner":{"w":320,"h":50}}],"app":
{"ver":"1.0","paid":0,"keywords":"games"}}}');

OpenRTB parameters in a standalone tag

Alternatively, you can use the requestAd method to send OpenRTB parameters to Ad Exchange buyers.

Object literal:

OX.requestAd({
    auid: "12345",
    openrtb: {
        imp: [
            { banner:

{ w: 320, h: 50 } }
        ],
        app: {
            ver: "1.0",
            paid: 0,
            keywords: "games",
        }
    }
});

JSON string:

OX.requestAd({
    auid: "12345",
    openrtb: '{"auid":"12345","openrtb":{"imp":[{"banner":{"w":320,"h":50}}],"app":{"ver":"1.0","paid":0,"keywords":"games"}}}'
});

Use this method to indicate the referring URL of the page (HTTP referrer) if it is not normally detectable using JavaScript. In most cases, the OpenX JavaScript tag library detects the referring URL. However, you can call setRefererURL directly as necessary or use it as an override.

Parameters

Example

OX_string.setRefererURL("http://www.example.com?q=abc");

Set the interval (in seconds) at which to refresh ads.

This value must be an integer ≥ 1. If you explicitly pass this parameter in an ad tag, OpenX ignores any server-side refresh delay setting for this ad unit, as set when creating or editing the ad unit or its container site. This affects all ad units associated with the instance.

Parameters

Example

OX_string.setRefreshDelay(60);

Use this method to set the maximum number of refreshes for ads displayed through the ad tag. This must be a positive integer. For example, setting this parameter to a value of 5 results in the display of a total of 6 ads, including the initial display (non-refresh) and 5 subsequent displays (refreshes).

If you explicitly pass this parameter in an ad tag, OpenX ignores any server-side refresh max setting for this ad unit, as set when creating or editing the ad unit or its container site. This affects all ad units associated with the instance.

Parameters

Example

OX_string.setRefreshMax(5)

You may use this method to set a specific user ID for the request after reviewing your ID management strategy with OpenX.

Parameters

Example

OX_string.setUserID("ABC");

Use this method to show the ads returned to the fetchAds method. If you place an anchor tag in the correct location in your webpage and call showAdUnit, the ad rendering is initiated using document.write() to write the ad content into the browser document object model (DOM).

You must call this method after fetchAds. Otherwise, it will not work.

Parameters

Example

OX_string.showAdUnit("12345");