Content: Content Settings Object

Common settings for all types

Every "branch" of a content settings object, regardless of type, may contain the following settings:

Specific settings for types

Basic types (present at least once)

"fixed"

Return a list of (zero or more) predefined results. Useful for testing or user-messages controlled by Cxense Content targeting.

"recs"

Fetch content recommendations. Special fields (some fields have default values):

Details for minAge, maxTimeLeft or minTimeLeft

Setting minAge: 0m, 0d or 0w means that results with future publish dates are not allowed. This value is also allowed to be negative. For sites read in many time zones, it is recommended to set this to -1d when used.

Observe that setting maxTimeLeft or minTimeLeft has the effect that only elements that have an expiration time will be recommended.The expiration time can be set using a meta tag cXenseParse: recs:expirationtime as described on the page Cxense Content - Review and Refinement.

If minTimeLeft is not specified, then no article will be recommended that has an expiration time that has passed.

Details for "reporting"

The reporting object contains a key-value pair. The key has a maximum length of 30 characters. The value has a maximum length of 40 characters.

The value and key can be replaced with placeholders.

The reporting parameters will be added to the custom parameters on the Audience impression or click event.

"reporting": [{"key" : "segment", "value" : "32gfdeyt244r"},{ "key" : "mode", "value" : "contextual"}]

Details for "deboost"

The content deboost feature ensures users are shown fresher, more engaging articles by lowering the priority of content they have already consumed. Whenever a user visits an article or clicks it in a recommendation widget, the system records a tracked event and marks that item as "read". From that point on, the article receives a lower relevancy score in subsequent recommendation calls and is automatically pushed to the back of the list. Deboosting is designed to highlight new or unread content first, but if a user eventually consumes every article in a collection, previously read items will resurface since no fresh options remain.

This behavior is enabled by default and cannot be turned off or adjusted through the UI. To override it, such as showing a static set of recommendations or fully disabling deboosting, you need to call the Piano Content API (e.g., /public/widget/data) and handle caching on your end. Note that any UI edits to a recommendation module will reset deboosting to its default state, so you’ll need to reapply the API override afterward.

In private browsing contexts, where cookies are not persisted, there may be too little behavioral data to trigger deboosting effectively. In these cases, the recommendation engine relies more heavily on trending or contextual signals to deliver results.

Details for matchingMode

A matchingMode object may contain the following fields:

An integer n is interpreted as the object { "weight": n }. At least one mode field with non-zero weight must be specified.

An individual matchingMode settings object may contain the following fields:

Examples:

• "trend": {"weight": 1, "period": "1h"}} means: Give me the most read articles of the last hour.

• "search": {"weight": 1, "sort": [{"type": "string", "field": "xyz-myfield", "order": "ascending"}]} means: Give me the articles matching the query/filter where xyz-myfield is first alphabetically.

• "recent": {"weight": 1, "event": {"type": "buy", "origin": "xyz-shop"}} means: Give me the user's most recent purchases (articles where DMP "buy" event occurred).

Period specification

A time period specified as an offset such as "1000s" (within last 1000 seconds) or "2w" (within last two weeks). Possible units are seconds,minutes,hours,days,weeks,Months,years.

Details for resultFields

In the field resultFields you specify the fields returned for each article. However, this does not restrict the result set in any way. If you want to make sure that every article returned has certain fields, then this must be specified using filter. If resultFields is not specified, then it is given a default initial value.

Possible result fields include contenthash, description, dominantimage, dominantimagedimensions, dominantthumbnail, dominantthumbnaildimensions, id, keywords, kw-category, og-description, og-image, og-title, og-type, og-url, publishtime, recs-publishtime, recs-rawtitle, siteid, thumbnail, thumbnailfullheightdimensions, timestamp, title, wordcount, charactercount, url. The url result field will automatically include the result field click_url as well.

Details for pageviewCapping

Recommended documents for which the user has at least count number of pageviews in the last period are excluded (capped) from the result. No pageview capping is performed for results from matching mode "recent".

Time period specification

A time period specifying which events to be included, specified as one of:

• published – all events are counted. This is the default value.

• modified – only events since the document was last modified are counted.

• never – no events are counted.

• An offset such as "1000s" (only count events from last 1000 seconds) or "2w" (only count events from last two weeks). Possible units are seconds,minutes,hours,days,weeks,Months,years.

Example:

• No pageview capping: pageviewCapping": {"period": "never"}

"import"

Import existing content settings object as a child branch of this node.

The import is resolved for each data request, not copied into and stored with the parent configuration. Thus, any change to the imported content will be reflected in the parent configuration. Defaults from the parent configuration will be applied to the imported configuration. When creating or updating the parent configuration, the imported content must exist and come from the exact same site group. If the imported content is missing, the importing node will silently return no results.

"creative"

Return the fields from a creative.

The creative is returned as an item with its elements in fields, similar in format to results from the recs settings.

For example, the creative with elements

[
    {"type": "text", "name": "header", "text": "My header"},
    {"type": "image", "name": "header_image", "filename": "my_image_100_by_200.png"}
]

Might yield a single item with the following fields:

{
    "header": "My header",
    "header_image": "https://content.cxpublic.com/creatives/12345678910.png",
    "header_imagedimensions": "100x200"
}

Composition types

"combined"

Combine results from several branches for the same request. By giving the branches different weight, you can get more results from some branches than others.

Each combined content settings object should normally be wrapped in a uniquified object. This serves two purposes: Avoid duplicates and keep the best results, regardless of branch.

Example: The ordering [0, 2, 2, 2, 1] means: Take one recommendation from the first branch, three from the third branch and one from the second branch. After that, we take any remaining recommendations from the first branch, then from the second branch, and so forth.

If the branches can return overlapping results, you should wrap this in a uniquified object.

Since these branches are computed in parallel, there is a limit on the number of (combined) branches allowed. Observe that recs settings with keywords enabled or many site IDs may count as more than one branch.

"conditional"

Distribute the content requests between several branches based on facts about the current time, user and/or page.

The field condition can optionally be specified on the branches. The first branch whose condition is satisfied will be chosen. The branches without a condition field are called fallback branches. There must be at least one fallback branch, and no branch after a fallback branch can specify a condition. Note that it is not required for any branch to have a condition.

If no branch has its condition satisfied, a weighted random branch will be chosen among the fallback branches. Each fallback branch can have a field weight which specifies how often these sub-settings should be used (relative to the other branches). The default branch weight is 10.

"randomized"

Deprecated. Use "conditional".

"shuffled"

Shuffle the order of results from the inner content provider. Special fields:

"uniquified"

Remove duplicate results. Special fields:

To make sure we have enough results left after deduplication, we must ask the inner content provider for some extra results.  Margin:

• 0 - no over-booking (results in too few results when there are duplicates)

• 100 - ask for 100% more (twice as many) articles

• 200 - ask for 200% more...

"budget"

Don't recommend articles where number of impressions/clicks/page views are over a specified budget. Events are counted within the site of the widget, so two widgets belonging to the same site will share a budget.

Budget restrictions only apply for up to 100 articles per customer per day.

Special fields:

Best practice types

"defaults"

It is a best-practice to define defaults for any kind of content settings.

In a settings object with many branches you may end up specifying the same parameters over and over (e.g. resultFields will typically be the same everywhere). The purpose of defaults is to simplify this: A property specified in the defaults does not have to be repeated in the innerSettings, but it can be overridden.

If defaults are nested, the innermost default value is used.  Observe that the common fields (such as tag, weight or condition) are not interpreted as default values.

The content settings referenced using importFromContentId must consist of a single defaults node without innerSettings. The specified fields override any fields from the imported content settings. The import is resolved for each data request, not copied into and stored with the parent configuration. Thus, any change to the imported content will be reflected in the current configuration. When creating or updating the configuration, the imported content must exist and come from the exact same site group. If the imported content object is deleted, importFromContentId will have no effect.

Example: { "type": "defaults", "siteIds":[ "01234" ], "innerSettings": ... { "type": "recs", [settings that do not have to specify siteIds] } ... }

Miscellaneous types

"schemeAdjusted"

The effect of this type of settings is that certain URLs are rewritten if the current page is secure (https). This is done in order to avoid "mixed content" warnings.

Example of very basic content widget settings

Serves as an illustration of a starting point how to mix a recommendation based on

• the most popular articles of the last 24h (=>trend and period)

• the articles which fits best the context of the page the recommendation widget is placed on (=>contextual)

• the articles which fits best the users interest  (=>behavioral)

• no article should be published more then 7 days ago (=>maxAge)

• article must contain some image (=>"query for domaintthumnail")

{
  "type": "recs",
  "siteIds": [
    "your_siteid_goes_here"
  ],
  "matchingMode": {
    "trend": {
      "weight": 10,
      "period": "1d"
    },
    "behavioral": {
      "weight": 5
    },
    "contextual": {
      "weight": 5
    }
  },
  "resultFields": [
    "dominantimage",
    "title",
    "teaser",
    "url",
  ],
  "maxAge": "7d",
  "query": "query(dominanthumbnaildimensions:\"*\")"
}

Example of complex content widget settings

Observe that this example is rather far-fetched.

{
    "type": "schemeAdjusted",
    "fields": [ "dominantthumbnail" ],
    "innerSettings": {
        "type": "combined",
        "ordering": [1, 1, 0],
        "branches": [
            {
                "type": "fixed",
                "comment": "This is a random comment",
                "weight": 1,
                "items": [
                    {
                        "url": "http://www.cxense.com",
                        "title": "Cxense",
                        "description": "Extraordinary insight",
                        "dominantthumbnail": "http://www.cxense.com/wp-content/themes/cxense/css/img/cxense_logo.png"
                    }
                ]
            },
            {
                "type": "randomized",
                "weight": 9,
                "branches": [
                    {
                        "type": "shuffled",
                        "level": 50,
                        "innerSettings": {
                            "type": "recs",
                            "weight": 95,
                            "matchingMode": {
                                "trend": { "weight": 1, "period": "1h" }
                            },
                            "query": "query(dominantthumbnaildimensions:\"*x*\")",
                            "siteIds": [ "9222300729399686919" ]
                        }
                    },
                    {
                        "type": "uniquified",
                        "weight": 5,
                        "margin": 150,
                        "innerSettings": {
                            "type": "recs",
                            "matchingMode": {
                                "trend": { "weight": 50 },
                                "behavioral": { "weight": 50 }
                            },
                            "resultFields": [ "url", "title", "description", "dominantthumbnail" ],
                            "siteIds": [
                                "9222300729399686919",
                                "9222311772423575900"
                            ]
                        }
                    }
                ]
            }
        ]
    }
}

Last updated: June 24, 2026