Content settings object

• Common Settings for all Types
• Specific Settings for Types
  • Basic Types (must exist at least once)
    • "fixed"
    • "recs"
      • Details for minAge, maxTimeLeft or minTimeLeft
      • Details for "reporting"
      • Details for matchingMode
        • Period specification
      • Details for resultFields
      • Details for pageviewCapping
      • Time period specification
    • "import"
    • "creative"
  • Composition Types
    • "combined"
    • "conditional"
    • "randomized"
    • "shuffled"
    • "uniquified"
    • "budget"
  • Best Practice Types
    • "defaults"
  • Miscellaneous Types
    • "schemeAdjusted"
• Example of very basic content widget settings
• Example of complex content widget settings

A content settings object is a part of a content configuration object or of another content settings object (since some settings contain internal (sub)settings or branches).

Each content settings is defined by a field type. The type of settings determines what other setting fields are valid. Observe that at this level, if a field is not specified in an update, it is interpreted as null. In other words, any existing value will be lost.

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 (must exist 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](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 DMP impression or click event.

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

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": "https://www.cxense.com",
 "title": "Cxense",
 "description": "Extraordinary insight",
 "dominantthumbnail": "https:///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: July 30, 2024