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.