Express Ads

Express Ads provides a lightweight simple way to deliver ads in an Express-based web site. It works with any template engine and provides a nice admin interface.

Live demo

Visit demo.eas.rocks . The full source code of the live demo site is available from github. It may be useful to better understand how to implement express-ads in your web site.

Features

Multiple concurrent campaigns
Multiple banners per campaign
Multiple creatives per banner
Several campaign types:
- Number of prints within a period
- Number of click within a period
- Recurrent prints (like 10000 prints per day)
- Recurrent clicks (like 100 clicks per day)
- Background (weighted display on available inventory)
Ads are distributed evenly over the period
Page and session capping per banner and/or campaign
Country/OS/Browser filtering
Campaign optional start/end dates
Real time prints and clicks statistics
Full admin interface integrable to the site's existing admin
Not relying on a specific database
Robust to ad-blockers (ads served from the site itself)
Extensible via add-ons to serve ads for external platforms

Screenshots

Using Express Ads (short version)

App setup

var app = express();
...
require('express-ads')(app,{});
...
app.get('/content-path', function (req, res) {
    res.render(someTemplate, { 
        ad: req.deliverAd,
    });
});
app.listen(3000);

Requesting an ad

Using Jade as template engine

p
  | Ipsum lorem ...
| !{ ad('area-name') }
p
  | Ipsum lorem ...

Using EJS as template engine

<p>Ipsum lorem ...</p>
<%- ad('area-name') %>
<p>Ipsum lorem ...</p>

From the admin interface

Open `http://your-domain.com/eas/admin'
Create an area specifying the size
Create a banner
Add the area to the banner
Setup the banner link
Add one or more images to the banner with same size
Create a campaign
Add the banner to the campaign
Reload the content page, ads should be displayed

Using Express Ads (detailed version)

Setting up in your web site

Setup express-ads in your application using:

var app = express();
...
require('express-ads')(app,options);

after doing so, the req object will contain the following new fields:

deliverAd: a function that returns the HTML code to display (or not) an ad
expressAds: access to global express-ads service

deliverAd takes 2 parameters: areaName and an optional adParams and returns immediately the HTML code for the ad to display. Note that it might be an empty string if the module decided that no ad should be displayed.

areaName is the human name of an area that must have been created from the admin interface
adParams an object with the following fields:

Param	Default	Description
`styles`	`null`	an object containing CSS styles and values to display the ad container
`classes`	`null`	an array of classes (as strings) to be applied to the ad container
`tag`	`null`	if set, the HTML element to be used for the ad container. By default, `<p>` is used for text inventory areas, `<div>` for other inventory types

Note that those parameters (styles, classes, tags) can also be set tuned from the admin interface. It's up to you to choose whatever styling method you want to use.

expressAds is an object that provides access to a number of services:

Param	Description
`adminUI`	a function that returns the entire admin interface HTML code
`styles`	an array of strings representing the stylesheets to be included in the admin page
`stylesHTML`	like `styles` formatted as a single HTML string that loads the stylesheets
`scripts`	an array of strings representing the scripts to be included in the admin page
`scriptsHTML`	like `scripts` formatted as a single HTML string that loads the scripts
`saveStats`	a function to save manually the current stats. It takes a callback as parameter that is called when the save operation is done. Note that stats are automatically saved every minute, so this function is only useful when doing a shutdown of the application if you don't want to lose the last minute of stats

When doing require('express-ads')(app,options), options is an object that can contain the following fields:

Param	Default	Description
`path`	`"/eas"`	the base URL path where express-ads services are attached to
`adminPath`	`null`	by default (`null`), the express-ads admin interface can be accessed from `path`+`/admin` (if you did not change `path`, it is `/eas/admin`). You can set `adminPath` to any other path value, like `"/admin/eas`"
`auth`	passthrough function	a `function(req,res,next)` to authenticate the access to the express-ads admin interface. By default, this function is a passthrough (it calls `next()` directly). You can implement your own authenticator here (using passport for instance) or rely on your site's default security system to protect the path to the admin page. For instance, many sites protect globally everything under `/admin`, so if you define `adminPath` to `"/admin/eas"`, you are safe and you can set the `auth` function to `function(req,res,next) { next(); }`
`staticMaxAge`	`"1h"`	the cache duration for static resources
`rollBacklog`	`1000`	the service maintains a cache for the last events, so it can determine a statistical event rate used to serve ads evenly over a period
`rollExpire`	`172800000`	default corresponds to 2 days. Older entries are removed from the roll cache
`adblockerDetection`	`true`	whether the adblocker detection is activated. You can filter banners based on whether the user has an adblocker or not
`files`		an object containing various data pathes (see below)
`files.ads`	`"ads.json"`	file where ads configuration data are kept
`files.stats`	`"stats.json"`	file where stats are kept
`files.images`	`"ads/images"`	directory where banner images are stored
`files.tmp`	`"ads/tmp"`	directory where banner images are temporarily stored
`debugDeliver`	`false`	if set to `true`, traces are printed to the console when an ad is to be picked for delivery
`debugData`	`false`	if set to `true`, the admin interface will display an additional containing the raw JSON data for ads config and stats
`debugLiveTemplate`	`false`	if set to `true`, it won't be necessary to restart the server app to see changes in the admin user interface
`imageMagick`	`false`	use ImageMagik to manipulate banner images. On Ubuntu, you can install ImageMagick with `apt-get install imagemagick`
`addons`	`null`	an array of add-on modules. See below Extending express-ads
`allowedSizes`	see below	an object describing the available inventory areas sizes. A new size can be added by specifying a corresponding entry in `allowedSizes`, for instance `"123x456":1`. An existing size can be removed by setting its value to 0: `"468x60":0`
`allowUpload`	`true`	is uploading local image files allowed

plus a number of parameters dedicated to integrating the express-ads admin interface to the site's admin (see below).

The default value for allowedSizes is:

        allowedSizes: {
            "120x240": 1,
            "120x600": 1,
            "120x60": 1,
            "120x90": 1,
            "125x125": 1,
            "160x600": 1,
            "180x150": 1,
            "234-60": 1,
            "240x400": 1,
            "250x250": 1,
            "300x250": 1,
            "336x280": 1,
            "468x60": 1,
            "728x90": 1,
            "88x31": 1,
        }

Note that additional sizes declared by addons are automatically made available.

Display an ad in the template

Whether you use Jade, EJS or any other templating system, you need to have access from your template to the express-ads deliverAd function:

app.get('/content-path', function (req, res) {
    res.render(someTemplate, { 
        ad: req.deliverAd,
    });
});

You can then request the ad display doing !{ ad('area-name') } (Jade) or <%- ad('area-name') %> (EJS).

It is a better practice to pass the styling options to the express-ads API <%- ad('area-name',{classes:['ad-wrapper']}) %>, rather than providing your own externally <div class='ad-wrapper'><%- ad('area-name') %></div> because if no ad is to be displayed (ad() returning an empty string) you might be left with unwanted paddings, margins, borders, ...

Express-ads admin interface integration

By default, once express-ads is setup in your site, you can access the admin interface on http://mysite.com/eas/admin, however, since your site is likely to have its own admin user interface, you may want to integrate express-ads into it to keep a common look and feel.

The idea is to provide your own admin template and layout and insert it into your page:

app.get('/admin/ads-management', function (req, res) {
    res.render('ads-management-template, { 
        expressAds: req.expressAds,
    });
});

and in the template (Jade version):

  ...
  body
    ...
    | !{ expressAds.adminUI() }
    ...
    | !{ expressAds.scriptsHTML }
    | !{ expressAds.stylesHTML }

or (EJS version):

  ...
  <body>
    ...
    <%- expressAds.adminUI() %>
    ...
    <%- expressAds.scriptsHTML %>
    <%- expressAds.stylesHTML %>
  </body>
</html>

expressAds.adminUI() returns as a single string the whole required HTML to build the user interface, expressAds.scriptsHTML and expressAds.stylesHTML contains the scripts and styles for this page to run.

The express-ads admin page makes use of several common libraries that you may already have setup in your site template. You can prevent the scripts and styles to be loaded twice by specifying parameters adminScripts and adminStyles into options when calling require('express-ads')(app,options).

The admin UI integration specific option parameters are:

Param	Default	Description
`standaloneAdminUI`	`true`	if set to `false` a default admin page is not provided
`adminScripts`	see below	an object to change or remove loaded scripts
`adminStyles`	see below	an object to change or remove loaded styles

For instance, calling require('express-ads')(app,{adminScripts:{jquery:null}) ensures expressAds.scriptsHTML does not contain the code to load jquery, assuming it is loaded by your own means.

The default list of scripts libraries is:

Library	value
`jquery`	`https://cdnjs.cloudflare.com/ajax/libs/jquery/2.1.4/jquery.min.js`
`angular`	`https://cdnjs.cloudflare.com/ajax/libs/angular.js/1.4.8/angular.min.js`
`angularSanitize`	`https://cdnjs.cloudflare.com/ajax/libs/angular.js/1.4.8/angular-sanitize.min.js`
`bootstrap`	`https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.6/js/bootstrap.min.js`
`moment`	`https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.10.6/moment.min.js`
`bootstrapDateTimePicker`	`https://cdnjs.cloudflare.com/ajax/libs/bootstrap-datetimepicker/4.17.37/js/bootstrap-datetimepicker.min.js`
`uiSelect`	`https://cdnjs.cloudflare.com/ajax/libs/angular-ui-select/0.13.2/select.min.js`

For styles:

Library	value
`fontAwesome`	`https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.5.0/css/font-awesome.min.css`
`bootstrap`	`https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.6/css/bootstrap.min.css`
`bootstrapDateTimePicker`	`https://cdnjs.cloudflare.com/ajax/libs/bootstrap-datetimepicker/4.17.37/css/bootstrap-datetimepicker.min.css`
`uiSelect`	`https://cdnjs.cloudflare.com/ajax/libs/angular-ui-select/0.13.2/select.min.css`

You can see an example of express-ads admin page integration in the exskel (a skeleton for Express-based web sites).

Using the admin interface

This is pretty straight forward.

Basically you create an inventory area, specifying a size. Then, you create a banner, specifying type Image, fill-in details, including a target link, indicate which areas this banner can be displayed to, add images to the banner (only images with a size that fit an inventory area will be used), specify filters if you want to. Next, create a campaign, specifying a type, for instance, Background, the banners you want to use for this campaign and you are all set, express-ads should start delivering ads.

There are a few things that may not be obvious though.

When using a Text banner, that may contain several texts to be chosen randomly, if you simply specify a text like This is the text of my ad, the whole sentence will appear as a link. If you do This is the [[text]] of [[my ad]], text and my ad will appear as links (to the target link you specified for the banner), while the remaining words will show up as normal text.

When specifying a target link for a banner, you can use the following placeholders:

Placeholder	Replaced with
`{{INV}}`	the inventory area id
`{{CAM}}`	the campaign id
`{{BAN}}`	the banner id
`{{IMA}}`	the creative (specific image or text) id
`{{ALL}}`	equivalent to `{{INV}}.{{CAM}}.{{BAN}}.{{IMA}}`

Extending express-ads

Express-ads can be extended using add-ons. There are currently 2 add-ons modules:

express-ads-adsense for serving ads from AdSense
express-ads-chitika for serving ads from Chitika

Using an express-ads add-on

When calling require('express-ads')(app,options), options must contain fields addons with an array of add-on modules as value. For instance:

require('express-ads')(app,{
    ...
    addons: [ require('express-ads-adsense'), require('express-ads-chitika') ] 
});

When creating a new banner, additional types will be available, in this case AdSense and Chitika. Depending on the add-on requirement, you may have to setup addtional configuration from the admin interface, like the publisher ID and slot ID, either globally from the Express Ads tab, or per banner in the banner settings panel.

Developing an add-on

If you want to develop an add-on for another platform, the good news is that it is very simple. The best way is to start from an exiting add-on like the one for AdSense.

Rename adsense.js to something more appropriate, and edit the file to match your needs. exports.settings and exports.bannerSettings define the settings for the add-on, repectively globally and per-banner. There are 3 parameter types you can use:

Parameter	Description
`text`	a single line text parameter
`longtext`	a text over several lines
`checkbox`	a checkbox parameter

The file template.ejs describes (in EJS templating language) the HTML code that will be generated.

When you define a parameter with name, say myparam in settings, it's value is available from the template using <%= settings.myparam %>. If defined in bannerSettings, you can read it as <%= banner.addon.myparam %>.

Other variables are also available in the template:

Parameter	Description
`size`	an object with field `width` and `height` corresponding to the current area
`campaign`	the full campaign object
`banner`	the full banner object
`inventory`	the full inventory object

Limitations

Express Ads is not intended to support multiple users editing ads from the admin interface at the same time
In this early version, only plain images and text ads are supported, not videos. Add-ons allow serving ads from external platforms

Supporting Express Ads

This code is free for you to use. However, in order to ensure we can maintain it, we display an ad from us with a 1% probability on your non-text inventory. We ensure that the ads we display are clean and safe for any environment. Contact us contact at eas.rocks if you have a problem with that.

express-ads

Express Ads

Live demo

Features

Screenshots

Using Express Ads (short version)

App setup

Requesting an ad

Using Jade as template engine

Using EJS as template engine

From the admin interface

Using Express Ads (detailed version)

Setting up in your web site

Display an ad in the template

Express-ads admin interface integration

Using the admin interface

Extending express-ads

Using an express-ads add-on

Developing an add-on

Limitations

Supporting Express Ads

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

Weekly Downloads

Version

License

Last publish

Collaborators

express-ads

Express Ads

Live demo

Features

Screenshots

Using Express Ads (short version)

App setup

Requesting an ad

Using Jade as template engine

Using EJS as template engine

From the admin interface

Using Express Ads (detailed version)

Setting up in your web site

Display an ad in the template

Express-ads admin interface integration

Using the admin interface

Extending express-ads

Using an express-ads add-on

Developing an add-on

Limitations

Supporting Express Ads

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Last publish

Collaborators

Weekly Downloads