OX Display deprecated

OX Display allows the insertion of banner/creatives into the web UI of OX App Suite.

The framework defines common areas (banner spaces) to serve creatives in different forms and includes an API to refresh those banners on different events (e.g. module change, etc.).

Configuration

Configuration for the io.ox/ads framework must be provided by a plugin in the namespace io.ox/ads.

All registered plugins for io.ox/ads will get loaded and the return values of their modules will be handed as parameters for invocation of the inject method (with this being bound to $('head')) as well as the config method of the extension point io.ox/ads. It is therefore possible to customize this functionality by extending io.ox/ads.

When using the default implementation, custom modules should return an object containing two keys:

  • inject - a String with valid HTML code which is to be appended to the head element
  • config - the configuration is simply stored internally

The config object can contain arbitrary data. The changeModule and appReady method of the io.ox/ads extension point will be invoked with the app name as first parameter and a Baton containing a reference to the app and the config object.

The default implementation expects the config object to contain one key for each banner space. Values for these keys used in the default implementation should be an object defining:

  • space - a String which defines the desired target space
  • html - a String which is appended to the corresponding space
  • reloadAfter - a number value, representing the time until the next refresh operation for an area is invoked
  • showInModules - falsy value (always active) OR an array with app names to match against (e.g. 'io.ox/mail', …)

For every defined area, the cleanup method of the corresponding extension point will be invoked. Active spaces are determined by filtering using showInModules options in the area configuration. By extending io.ox/ads extension point implementing the filter method, the filtering behaviour can be customized. For every active area, the draw method of the extension point will be invoked (see Banner spaces). The reload method of the area extension point will be invoked in a regular interval defined by the value of reloadAfter. The configuration object will be passed to each method invocation.

Configuration provided by middleware API

The configuration for banner spaces can be stored via middleware API. Beginning with the 1.3.0 release, configuration is requested via this API by default. When running against versions of OX App Suite which don't support this API, this will result in 404 errors logged during user login.

To deactivate this feature, the setting io.ox/ads//features/useMiddlewareConfig=false needs to be configured on the server.

API

Easy access to the gathered configuration is possible via the io.ox/ads/config module. The provided methods are:

  • load: store a given configuration. No need to call this manually, the framework uses this internally. In case you need to add configuration later, this function can be used.
  • get: get all configuration values in an Array
  • forSpace: only return configuration for a given space

Utility API

Most campaigns share common needs regarding functionality. The io.ox/ads framework provides a set of tools to simplify custom implementations.

Ad tags

The io.ox/ads API natively supports ad tags either automatically as a Doubleclick GPT configuration by simply configuring the unit ID or injects other (non-Google) ad partner/publisher tags through the initialization configuration by adding their JavaScript tag.

Implementing a banner should be possible without any JavaScript code, by just providing configuration for the desired space. This is achieved by using the default values.

A minimal configuration for the io.ox/ads/leaderboard banner space might look like this:

[{
    "space": "io.ox/ads/leaderboard",
    "gpt": {
        "adUnitPath": "/1234567/test_ads"
    },
    "cooldown": 5000,
    "reloadAfter": 30000
}]

This will setup an automatic reload after 30s and installing a cool down timer to not refresh before 5s have passed since the last reload event. Banners will be served from the ad unit /1234567/test_ads which needs to be defined within GPT.

Customization

The default behavior can be completely customized using well-known methods, extension points. Despite the special points for the banner spaces, it is possible to extend the general point io.ox/ads. The API for this point looks like this:

ext.point('io.ox/ads').extend({
    changeModule: function (baton) { /* do something if user opens a new app/module */ },
    filter: function (baton) { /* result is expected in baton.activeAds, apply your filter function here */ },
    config: function (baton) { /* do something with the configuration */ },
    inject: function (baton) { /* inject the global JS from ad provider, this variable is bound to $('head') */ }
});

As a reference implementation and a starting point, this project can be used. The implementation is used to demonstrate the integration of a few banner spaces using a little more than just a minimal configuration.