EthicalAds Client

This is the client library used to add an ad placement from EthicalAds to your site. To get started, you will need to first become a publisher, and then you can configure your site.

_images/example.png

Usage

There are two pieces required to add an ad placement to your site. You will need to create an empty <div> element where you would like to place a new ad placement, and you will need to include the client library.

To start, add the following in your site’s <head>:

<script async src="https://media.ethicalads.io/media/client/ethicalads.min.js"></script>

To add the placement on your site, you will need to add an empty <div> with some added data attributes to configure the ad placement:

<div data-ea-publisher="..." data-ea-type="text"></div>

Configuration

The following data attributes are supported on the ad placement element:

data-ea-publisher
(Required) The EthicalAds publisher id for your account.
data-ea-type
The ad placement type. This value can be either image or text – the default is image.

Themes

The following themes are available on all ad placement types:

Raised theme

This is the default theme used if you do not specify a theme.

<div data-ea-publisher="..."></div>

Or you can also explicitly use the theme name:

<div class="raised" data-ea-publisher="..."></div>

There are also dark variants for all of the themes. The dark variants can be used with the dark class:

<div class="dark raised" data-ea-publisher="..."></div>

Ad Types

Image placement

The image ad placement type has two variants: horizontal and veritcal. Vertical image placements are the default ad type. To use the horizontal variant, use

Vertical image

<div data-ea-publisher="..." data-ea-type="image"></div>

Horizontal image

This variant can be used with the horizontal theme variant class:

<div class="horizontal" data-ea-publisher="..." data-ea-type="image"></div>

Customization

It’s possible to extend the ad client, even if you are loading the client in your browser through a request. After loading the script, there will be an ethicalads global/window instance that can be used to extend the ad client interface.

The easiest place to extend is the ethicalads.wait promise instance. This resolves to an array of placements that were successfully configured – if no placements were loaded successfully, this will be an empty array.

The ethicalads object needs to be instantiated first. If you aren’t loading the ad client library asynchronously, you can delay execution by loading your additional script after loading the ad client.

If you are loading the ad client library asynchronously, you should wait for a document ready event. For example, using jQuery:

$(document).ready(() => {
  ethicalads.wait.then((placements) => {
    console.log('Ads are loaded');
  });
});

Showing content when there isn’t an ad

The biggest use-case is to show backup content when we don’t have an ad to show. Many of our publishers prefer to serve EthicalAds, but while we’re still building the network we might not have a 100% fill rate.

You can show backup content with a code snippet like this:

<script src="https://media.ethicalads.io/media/client/ethicalads.min.js"></script>
<script>
ethicalads.wait.then((placements) => {
  if (!placements.length) {
    console.debug('Loading backup content');
    div = document.querySelector('[data-ea-publisher]')
    div.innerHTML = '<p>Check out our first-party ad content.</p>'
  } else {
    console.debug('EthicalAds are loaded');
  }
});
</script>

Warning

You need to have Allow house campaigns disabled in the ads dashboard, otherwise we will always return a house ad. Go to Settings > Control advertiser campaign types to disable it.

Becoming a Publisher

Visit EthicalAds to apply to be a publisher.