# inventory.json

The ad placements and ad servers of a Tenant have to be configured in its inventory.json. This file is located in the resources folder in each Tenant's repository.

TIP

If there's no need for any ad configuration this file should not be present.

For example, the inventory.json of a Tenant using DFP and Taboola could look like:

{
  "placements" : {
    "inline_mosaic" : {
      "adServer" : "dfp",
      "params" : { }
    },
    "inline_details" : {
      "adServer" : "dfp_1",
      "params" : { }
    },
    "bottom_details_1" : {
      "adServer" : "taboola",
      "params" : { }
    },
  "adServers" : {
    "dfp" : {
      "type" : "doubleclick",
      "slot" : "/123456/medium_rectangle_sidebar_300_250",
      "json" : { }
    },
    "dfp_1" : {
      "type" : "doubleclick",
      "slot" : "/123333/half_page_ad_300_600",
      "json" : { }
    },
    "taboola" : {
      "type": "taboola",
      "layout":"responsive",
      "heights": "(min-width:1636px) 284%, (min-width:955px) 296%, (min-width:604px) 317%, (min-width:441px) 350%, 396%",
      "publisher": "examplepubliser",
      "mode": "alternating-thumbnails-a",
      "placement": "Below Article Thumbnails",
      "target_type": "mix",
      "article": "auto",
      "container": "taboola-below-article-thumbnails"
      }
    }
  }
}

# Inventory json schema

The inventory json schema (opens new window) lists all the available placements and providers that are supported by Marfeel.

The master json schema references sub-schemas for placements (opens new window) and for each ad server (opens new window).

Marfeel ad server (opens new window) has its own sub-schema.

TIP

The schema details of all ad servers can be found in the ad servers catalog documentation.

# Ad Placements

The ad placements in an inventory.json define which types of ads will be shown on the Tenant's site, and where those ads will be shown. Each placement is an object with as many values as necessary. The object key determines the placement's location. As for value, each placement must declare at least one ad server, and can contain several additional parameters.

# Ad Servers

Every ad server is an object in the inventory.json and its key is what placement configurations reference to.

For example, if a placement has adServer defined as "adServer": "dblclick", the key for the ad server object will be "dblclick".

{
  "placements" : {
    "inline_food" : {
      "adServer" : "dblclick"
    }
  },
  "adServers" : {
    "dblclick" : {
      "type" : "doubleclick",
      "slot" : "/1234567/TM-12334567",
      "json" : { }
    }

# Ad server attributes

Following Marfeel's multichannel strategy ad servers should be configured with the attributes that an amp-ad requires (opens new window). All channels adapt and use the same configuration.

To see which attributes are accepted for a specific ad server see the ad servers catalog

An example of a Taboola ad server configuration looks like this:

{
    "taboola": {
        "type": "taboola",
        "publisher": "supernewss-network",
        "heights": "(min-width:1565px) 73%, (min-width:1106px) 79%, (min-width:788px) 88%",
        "article": "auto",
        "mode": "alternating-thumbnails-b",
        "placement": "Mobile Below Article Thumbnails AMP",
        "another_attribute": "val"
    }
}

And will result in the following amp ad:

<amp-ad class="mrf-adv mad mrf-preInsertedMad sRoba mrf-madLoaded"
        type="taboola"
        width="300"
        height="250"
        heights="(min-width:1565px) 73%, (min-width:1106px) 79%, (min-width:788px) 88%"
        data-article="auto"
        data-mode="alternating-thumbnails-b"
        data-placement="Mobile Below Article Thumbnails AMP"
        data-another-attribute="val">
</amp-ad>

AMP transformations

AMP prefixes all attributes with data-. For instance, an article attribute is rendered as data-article.

AMP replaces snake-case by kebab-case. For instance, another_attribute is rendered as data-another-attribute.

# Placeholders

In the placement configuration, placeholders can be used to parametrize the ad server configuration with the following form: ${PARAM_NAME}, which will be replaced by the corresponding value. These are the available placeholders:

TENANT_NAME: Tenant's name (e.g: www.examplesite.com)
TENANT_ID: Tenant's ID (e.g: www.examplesite.com)
INSIGHT_TENANT_ID: Tenant's ID without the leading www. (e.g examplesite.com )
SECTION_NAME: Section name if the add is for a specific section.
VIRTUAL_PAGE: Ad position number on the current page.
CLIENT_VP: Ad position number of tenant ads (Marfeel ads are skipped)
POSITION: Ad position number on the current page, capped at 10.
NAVIGATION_LEVEL: Navigation level from the placement (MOSAIC, DETAILS).
RUNTIME_ENVIRONMENT: (e.g browser)
MAD_TYPE: Ad type defined in the placement (inline, nativeAd)
CONTENT_GROUP: Content group from the placement
BUILDNUMBER: Marfeel build number
CUSTOM_BUILDNUMBER: Custom plugin build number
LAYOUT: Layout of the ad (e.g. nativeAdvInDetails, layoutRoba_s, ...)
DEVICE_TYPE: Device type (e.g: s,m,l xl)
THEME_NAME: Marfeel technology used (e.g: Touch, AMP )
MARFEEL_NAME: e.g: index
USER_CHANNEL: Channel where the user came from (e.g amp, push, direct)
SECTIONS_LIST: Objects array-like {id: "home"}
SECTION_ID: Ad section ID (e.g. "food")

For example, the following inventory.json has a DFP ad server with the "slot" /102345/EN_${SLOT_NAME}_${SLOT_NAMESIZE}_${SLOT_NAMEPOSITION}, which includes the variables SLOT_NAME, SLOT_NAMESIZE and SLOT_NAMEPOSITION. These variables are added as params in each placement:

{
  "placements": {
    "top_mosaic_portada": {
      "adServer": "dfp",
      "params": {
        "SLOT_NAME": "Home",
        "SLOT_NAMESIZE": "970x90",
        "SLOT_NAMEPOSITION": "1",
        "SLOT_SIZE": "320x50,728x90,970x90,970x250"
      }
    },
    "inline_mosaic_portada_1": {
      "adServer": "dfp",
      "params": {
        "SLOT_NAME": "Portada",
        "SLOT_NAMESIZE": "728x90",
        "SLOT_NAMEPOSITION": "3",
        "SLOT_SIZE": "320x50,728x90"
      }
    }
  },
  "adServers": {
    "dfp": {
      "type": "doubleclick",
      "slot": "/102345/EN_${SLOT_NAME}_${SLOT_NAMESIZE}_${SLOT_NAMEPOSITION}",
      "multi-size": "${SLOT_SIZE}",
      "multi-size-validation": false,
      "json": {
        "targeting": {
          "tenant": "examplesite.com",
          "platform": "marfeel",
          "section": "${SECTION_NAME}",
          "position": "${VIRTUAL_PAGE}",
          "virtualPage": "${VIRTUAL_PAGE}",
          "level": "${NAVIGATION_LEVEL}",
          "mrfEnv": "browser"
        }
      }
    }
  }
}

# Blacklisted Placeholders

Marfeel Inventory (opens new window) uses placeholders too. The names of those placeholders are forbidden in tenants' inventories, to avoid overwriting important information. This is the list of forbidden placeholders:

MULTI_SIZE
INSIGHT_TENANT_ID
AD_NETWORKS
SELLER_ID
CURRENCY_EXCHANGE

# EmptyAdServer

Sometimes Tenants don't want to show ads in certain positions. In this case, use an emptyAdServer using the key emptyAd.

Example:

{
  "placements" : {
    "inline_food": {
      "adServer": "emptyAd"
    }
  },
  "adServers" : {
    "emptyAd": {
      "type": "emptyAd"
    },
  }
}

# Layout attribute

The layout attribute has a specific behavior to fulfill the requirement described in the AMP documentation (opens new window).

Here are the three use cases:

Layout requires width and height (fixed, responsive ...), then width and height will be set to a default value of 300x250.
Layout does not require width and height (fill, container), then they won't appear.
Width and height attributes are set manually, then they will appear as-is.

# Fluid sizes

You can specify fluid as a value of layout and height attributes to send fluid size to the ad server.

# Header Bidding

Ad servers which rely on header bidding can be implemented with the inventory.json.

Marfeel uses Prebid for its own positions, but others are available, such as Yandex. Check the guide to implement header bidding in the inventory.json.

# Inheritance

inventory.json follows Marfeel's inheritance rules.

← Business models Ad server providers →