# twister.json

The twister.json file defines the placements and customizations of the Marfeel ad server like multi-size, header bidders and load methods.

This file allows to have strict control of certain ads configuration that needs the approval of monetization teams, and because of this, the configuration is not in inventory.json.

For example, when a Tenant with Enterprise business model needs to serve direct campaigns, all the configuration is done in twister.json file and has to have special approval. The same happens for Tenants with OAP business model that want to serve direct campaigns in the second position.

This file is located in the root folder in each Tenant's repository.

WARNING

This file must be in the tenant folder to monetize.

For the new tenants, this file is created via scaffolding but, for the old tenants which are reactivating, it has to be added manually.

This is an example of the twister.json of a Tenant with Enterprise business model that changes the load strategy on a specific placement:

{
  "hostname" : "example.com",
  "businessModel" : "ENTERPRISE",
  "extraHeaderBidders" : [ ],
  "adNetworkProfileStrategy" : "AGGRESSIVE",
  "paidImpressions" : { },
  "placements" : {
    "bottom_details_1" : {
      "adServer" : "exampleWEB",
      "loadStrategy" : "onInteraction"
    }
  },
  "sellerId" : "12345678987"
 }

# Twister json schema

Like other JSON extensions at Marfeel, Twister has a json schema (opens new window) cataloguing all its possible keys and values.

# `hostname`

The URL of the tenant as kept in MarfeelInsight UI. This should never be changed.

# `businessModel`

Tenant's business model. It should be changed in the local environment only for testing purposes. In the production repository, this value is managed exclusively by monetization teams from MarfeelInsight UI. See Business Models to know more about it.

OAP
ENTERPRISE
FIXED_FEE
VARIABLE_FEE

# `sellerId`

It contains the seller id of the Media Group of the Tenant as is in the sellers.json (opens new window) file. Although it is not strictly mandatory, some DSPs may refuse to bid if this id is not available, so its value is important to guarantee the maximum revenue. In general, this attribute is set automatically when the tenant is created.

TIP

This should be added in twister.json by default, if it's not though, it can be obtained following these steps:

From Gutenberg's root and replacing the mediaGroupId with the id in the URL of the tenant's media group in Insight, run the following command:

$ mvn exec:java -Dexec.mainClass="com.marfeel.insight.supplychain.app.SellerIdCalculatorApp" -Dexec.args="mediaGroupId" -pl MarfeelInsightBase/MarfeelSupplyChain/

# expected output
[INFO] --- exec-maven-plugin:1.6.0:java (default-cli) @ MarfeelSupplyChain ---
sellerId of the media group with id 5c9b6dd68b0afb08fd9ab198: 604262422

Note that the id is a hexadecimal string of 24 chars, and it is the same for a whole media group, it does not vary by tenant.

# `extraHeaderBidders`

It contains the extra SSPs and their parameters that can be added to specific tenants to make some tests. For the long term, this has to be configured through MarfeelInsight UI.

# `adDealer`

Container for new configurations of AdDealer.

reservedBlocks: CSS selectors that Boilerpipe should mark with a special class that AdDealer is going to consider as a reserved block. Such reserved blocks are not going to be split by any ad unless they contain more than 300 words. Some tenants may have to adapt their mark-up so that they can take advantage of reserved blocks (see example below).

WARNING

Use reservedBlocks in moderation: abusing it can lead to an excessive reduction in the number of ads. Its only purpose is to avoid breaking certain blocks that contain special content.

TIP

Example of adDealer configuration to prevent AdDealer from inserting ads inside the author box (in this example, marked in the original mark-up with the author-box class) and short lists that come after h3 titles:

"reservedBlocks": ".author-box, h3 + ul"

# `adNetworkProfileStrategy`

Defines the ad network profile strategy, which describes the level of aggressiveness of AdDealer while adding ads to pages.

DEFAULT: 90 words between ad.
LOOSE: 110 words between ad
AGGRESSIVE: 70 words between ad.

# `multisizeStrategy`

Modifies the ratio of requests with big ads.

INFO

Big Ads refer to any ad with a size larger than 336x280

DISABLED: No big ads will be requested.
SOFT: 20% of ad requests are for big ads.
DEFAULT: All sizes available.
RATIO: Allows further customization beyond the previous values. It requires the multisizeStrategyRatio attribute.

# `multisizeStrategyRatio:`

Its value is an integer between 0 and 100, the percentage of ad requests that can request big sizes.

It's only active if the multisizeStrategy is set to RATIO.

TIP

Notice that,

"multisizeStrategy": "RATIO",
"multisizeStrategyRatio": 20

is equivalent to

"multisizeStrategy": "SOFT"

In this case, out of all the requests, only 20% will request ads larger than 336x280.

# `densometer`

Allows to provide an object to set up the ad density of a Tenant.

enabled: Can be either ACTIVE or INACTIVE to specify if the density has to be limited or not
densityFactor: If the densometer is enabled, this is the number of the maximum percentage of the page that ads should cover. Minimum value is 20. The maximum value for Mosaic is 50.

WARNING

The densometer tool is deactivated in all tenants.

# `mosaicDensometer`

Allows providing an object to set up the ad density only in Mosaic.

enabled: Can be either ACTIVE or INACTIVE to specify if the density has to be limited or not in Mosaic.
densityFactor: If the densometer is enabled, this is the number of the maximum percentage of the page that ads should cover. The maximum value for Mosaic is 50.

# `paidImpressions`

Defines de configuration to serve direct campaigns in Tenants with Enterprise business model or for OAP tenants that want to serve direct campaigns in the second position. Within it, you can define positions as you would do within the inventory.json file. This configuration will override the one defined in the inventory.json.

See how to implement direct campaigns.

# `placements`

Placements with extra configuration to be added to the inventory.json configuration. See Ad Placements.

loadStrategy: The way an ad is loaded can be changed in the placements with this attribute, it can be onScreen, onScroll and onInteraction. See ads load strategy to know more.

TIP

Unless disabled by feature toggle, Taboola, Outbrain, Mgid, and Revcontent providers have onInteraction strategy active by default, so defining it in twister.json would be redundant. A feature toggle also exists to make inter placements load on interaction.

This an example of a Tenant OAP, that has direct campaigns and also changed the load strategy for certain placements.

{
  "hostname" : "example.com",
  "businessModel" : "OAP",
  "paidImpressions" : {
    "!inline_mosaic_portada_2" : {
      "adServer" : "homeDFP",
      "params" : {
        "SIZE" : "320x100,300x100,300x50,320x50",
        "ECPOS" : "mega1",
        "FORMATID": 666667,
        "ZONEID": 12345,
        "ZONEIDCRITEO": 12345,
        "PLACEMENTID": 12345
      }
    },
    "!inline_mosaic_multimedia_2" : {
      "adServer" : "mosaicDFPMultimedia",
      "params" : {
        "SIZE" : "300x250,300x600,336x280",
        "ECPOS" : "roba1",
        "FORMATID": 55555,
        "ZONEID": 98765,
        "ZONEIDCRITEO": 98765,
        "PLACEMENTID": 98765
      }
  }
  },
  "placements" : {
    "bottom_details_2" : {
      "adServer" : "revcontent",
      "loadStrategy" : "onInteraction"
    }
  },
  "sellerId" : "123456789"
}

← Header bidding Trainings →

# twister.json

# Twister json schema

# hostname

# businessModel

# sellerId

# extraHeaderBidders

# adDealer

# adNetworkProfileStrategy

# multisizeStrategy

# multisizeStrategyRatio:

# densometer

# mosaicDensometer

# paidImpressions

# placements

# `hostname`

# `businessModel`

# `sellerId`

# `extraHeaderBidders`

# `adDealer`

# `adNetworkProfileStrategy`

# `multisizeStrategy`

# `multisizeStrategyRatio:`

# `densometer`

# `mosaicDensometer`

# `paidImpressions`

# `placements`