We’ve migrated our documentation to a new site, which means some URLs have changed.
Audience
Audience
Breadcrumbs

Content Widget: configuration settingsオブジェクト

Content セッティングオブジェクトは   Content コンフィグレーションオブジェクト の一部です。
またContent セッティングオブジェクトは入れ子構造を取ることができるので、一つのオブジェクト内に複数のサブセッティングを含むこともあります。

各Contentセッティングは "type" フィールドによって定義されます。 "type" の設定によって、他の設定フィールドも有効になるかが決まります。 更新時に指定されなかったフィールドは、null値として判断されます。つまり、フィールドを明示的に指定しない限り、更新前に指定されていた値も失われます。

全ての type に共通のフィールド

すべての Content セッティングオブジェクトは、その type によらず以下のフィールドを含むことができます：

名前

タイプ

説明

comment

String

このフィールドはその設定内容や理由を記載するためのものです。動作には影響を与えません。

tag

String

以下にて、10桁以内の小文字(a-z)を指定できます。

  • Cxense Content の 「Widget Performance Report」内の「Paths」

  • Cxense Content API /widget/report  の "paths"

コンテントセッティングオブジェクト内に指定できる tags は最大10個までです。

weight

Integer

この設定による結果が使用される相対的頻度。
"combined"または"randomized"の設定の場合に使用します。
"weight"のデフォルトブランチ数は 10 です。 

boost

Integer

このブランチからの結果を優先します（"uniquified"設定でさらなるブランチの場合に使用）。

condition

Object

"条件付き" type のContentセッティング内で分岐する条件を設定します。
詳細は Content settings conditions をご確認ください。

itemDefaults

Object

サブセッティングに共通で使用されるデフォルト値を指定します。文字列値のみが使用可能です。"itemDefaults" を使用して、事前に定義された追加の "resultFields" のレスポンスデータとして、"items" フィールドに追加の key/value の組み合わせを付加することができます。これらはウィジェットのタイトルの設定やレイアウトやカラーの変更など "Templates" での応用が可能です。値はプレースホルダに含めることもできます。

 "tagging" recs clicks for Cxense Insight にて利用例をご紹介しています。

type ごと個別の設定

基本の type（少なくとも1つの指定が必須）

"fixed"

0以上の事前定義されたリストを返します。
Cxense Content のターゲティングで管理されるテストの際やユーザーメッセージに有効です。

名前

タイプ

説明

items

Array of Objects

このウィジェット（またはブランチ）に返される事前定義されたレコメンデーションの内容です。トップレベルのアイテムをプレースホルダに含めることもできます。

reporting

Array of Objects

key/valueの組み合わせ値をもつオブジェクトです。 
詳しくはこちらをご確認ください。

"recs"

システムからレコメンデーションを取得します。特有の項目は以下の通りです
（項目によってはデフォルト値がありますのでご注意ください）

名前

タイプ

説明

siteIds

Array of String

レコメンデーションを実施するサイトのIDを指定します。
ここで指定されるサイトの全ては Content コンフィグレーションで指定されるサイトグループに属している必要があります。
各サイトIDはプレースホルダにすることができます。 

matchingMode

Object

下記参照

resultFields

Array of String

レコメンド結果として返すフィールドです。
（"Template"で入力される、表示に必要な "title" "url"など。下記参照）

maxAge

Integer

廃止予定。ここで指定した分数よりも古い記事やアイテムが表示されなくなります。
デフォルトは無作為の古い記事やアイテムを返します。
"recs-publishtime"というフィールドで計算されます。 

maxAge

String

ここで指定した時間（period で表記）よりも古い記事は表示されなくなります。デフォルトは無作為の古い記事やアイテムを返します。"recs-publishtime"のフィールドで計算されます。

minAge

Integer

廃止予定。全ての記事がここで指定した分数よりも古い記事やアイテムになります。"recs-publishtime"のフィールドで計算されます。 

minAge

String

全ての記事がここで指定した時間（period で表記）よりも古い記事やアイテムになります。"recs-publishtime"のフィールドで計算されます。

maxTimeLeft

Integer

廃止予定。記事やアイテムの有効期限までの時間が指定値（分単位）以下のものに絞ります。"recs-expirationtime"のフィールドで計算されます（フィールドが存在する場合）。 

maxTimeLeft

String

記事やアイテムの有効期限までの時間が指定値（period で表記）以下のものに絞ります。"recs-expirationtime"のフィールドで計算されます（フィールドが存在する場合）。

minTimeLeft

Integer

廃止予定。記事やアイテムの有効期限まで少なくとも指定値（分単位）以上残っているものに絞ります。"recs-expirationtime"のフィールドで計算されます（フィールドが存在する場合）。 

minTimeLeft

String

記事やアイテムの有効期限まで少なくとも指定値（period で表記）以上残っているものに絞ります。"recs-expirationtime"のフィールドで計算されます（フィールドが存在する場合）。 

query

String

検索実施する際のカスタムクエリ句 ( 詳しくは /document/search を確認ください ) の指定に使われます。
クエリは Insight からの結果セットに対して適用され、その中から不要なものを除くために使用されます。 

filter

String

カスタムフィルタ句 (詳しくは /document/search を確認ください )

overrideMapping

String

コンテンツマッチに使用する検索クエリの挙動のカスタマイズ。

duplicateRemovalKey

String

重複削除に使用するキーのカスタム指定（※重複排除はブランチ毎でのみ行われます）

categoryType

String

/public/widget/data リクエストのlikes/dislikesと共に使用される

enableKeywords

Boolean

リクエストに含まれるキーワードによって
結果をブーストするかどうかの指定 ( /public/widget/data 参照 ).

null は false と解釈される

ignoreUser

Boolean

true の場合レコメンデーションをパーソナライズしない
全てのマッチングモードで意味を持つわけではない

ignoreUserLikes

Boolean

If true, do not respect user categories preferences passed in the request for these recommendations.

ignoreContext

Boolean

true の場合、コンテキスト（例えば参照中のページ）によってレコメンデーションを調整しない
全てのmatchingModeで意味を持つわけではない

trafficFilter

Object

トラフィッククエリに使用される Traffic filter 。 'trend' モードのみで使用される。

rank

String

レコメンデーションのランキング（結果順位）に記事の新しさがどの程度影響するかを指定します。

"norank", "publishfreshhigh", "publishfreshmed"の３種類が指定可能です。
例えばエバーグリーンコンテンツに関連する/関心を持つようなレコメンドをするには適しています。
※エバーグリーンコンテンツとは長期にわたって顧客を引きつけてくれるコンテンツのこと。 

reporting

Array of Objects

key/valueの対の値をもつオブジェクトです。 詳しくはこちらをご確認ください。

deboost

String

どのインプレッションがデブーストのインプレッションでカウントされるかの期間を指定します。
デブーストとはユーザーがすでにレコメンドされた（あるいは読んだ）ドキュメントの
ランクを下げるために使われます。

macthingMode が "recent" の場合、デブーストは実行されません。

pageviewCapping

Object

pageviewCappingについての詳細はこちらをご確認ください。

noBackfill

Boolean

true に設定すると、backfill の結果が配信されません。backfill は通常、結果が返ってこない（記事が出ない）よりは望ましいため、デフォルトは false です。
minAge, maxTimeLeft, minTimeLeftに関する詳細

"minAge":0m, 0d または 0w  とすると、未来日付の発行日の記事はレコメンドされません。
minAgeは負の値を取ることが可能です。
多くのタイムゾーンからアクセスされるサイトではminAgeを -1d に設定することをお勧めします。

maxTimeLeft や minTimeLeft を設定した場合、有効期限を設定したアイテムしかレコメンドされないことに注意してください。
有効期限はメタタグ "cXenseParse:recs:expirationtime" で指定します（ Cxense Content - Review and Refinement 参照）。

minTimeLeftが指定されない場合、有効期限を過ぎたものは表示されません。

"reporting" に関する詳細

"reporting" オブジェクトは key と value の対を含みます。key の長さは最大30文字で、valueの長さは最大40文字です。 

key と value は プレースホルダ に置き換えることができます。

"reporting" のパラメーターは DMPインプレッションやクリックイベントのカスタムパラメータを追加できるようになります。

"reporting": [{"key" : "segment", "value" : "32gfdeyt244r"},{ "key" : "mode", "value" : "contextual"}]
matchingModeに関する詳細

matchingMode オブジェクトには以下のモードがあります：

名前

タイプ

説明

trend

Object / Integer

最もアクセスの多い記事（periodで指定される直近の期間で評価）

contextual

Object / Integer

今読んでいる記事に似ている記事

behavioral

Object / Integer

これまで読んだ記事に似ている記事

collabctx

Object / Integer

この記事を読んだ人がほかに読んだ記事

collabusr

Object / Integer

似たユーザたちがほかに読んだ記事

explicit

Object / Integer

クエリー、フィルター、およびランクのみを使用して抽出した記事

⚠廃止予定。searchを使用してください。

search

Object / Integer

クエリー、フィルター、およびランクのみを使用して抽出した記事

recent

Object

そのユーザーが直近に読んだ記事
（ページビューまたはイベント項目に応じたDMPイベント）

レコメンデーションは直近からのソート順になります。
"deboost" と "pageviewCapping" でこのマッチングモードは実行されません。

rate

Object

コンテンツウィジェットに表示された時にクリック率が高い記事

⚠試用版: このmatchingMode は試用版です。アルゴリズムは将来、変更されたり削除される可能性があります。

整数 n はオブジェクト { "weight": n} として解釈されます。
各 matchingMode のオブジェクトでは少なくとも一つのmodeフィールドと0でないweightが指定されなければなりません。

matchingMode セッティングオブジェクトには以下のフィールドを含みます：

名前

タイプ

説明

weight

Integer

相対的な重み（正数）。必須の設定項目です。

period

Integer

廃止予定。指定期間（秒）内にトラフィック（ページビュー）があったページのみをレコメンドの対象とします。
"trend", "collabctx", "collabusr" ,"rate" にのみ有効です。

最大値： 604800　秒（＝7日）

period

String

指定期間（秒）内にトラフィック（ページビュー）があったページのみをレコメンドの対象とします。
"trend", "collabctx", "collabusr" ,"rate" にのみ有効です。

指定可能な期間の最大値： 7日

sort

Array of sort objects

query と filter でレコメンドされるドキュメントはこのソート仕様によって決まります。

"search" のみで使用可能です。 

スコアによる降順ソートがデフォルトです。

sort オブジェクトは /document/search で指定されます。

プレースホルダ は以下のフィールドで利用可能です: order, field, longitude, latitude

sort はいくつかのマッチングモードやバックフィルの組み合わせで使われ、
ウィジェットに表示されている記事のソート順を決めるのに使われないことにご注意ください。

event

Object

"pageview"を指定する際に、現在のユーザーが直近に見た記事をレコメンドします。

DMPイベントの type と origin を指定する際に、そのようなイベントが発生した、
現在のユーザーが直近に見た記事をレコメンドします。

"recent" でのみ有効です。

例:

  • "trend": {"weight": 1, "period": "1h"}} という指定は「直近1時間に最も読まれた記事」を意味します。

  • "search": {"weight": 1, "sort": [{"type": "string", "field": "xyz-myfield", "order": "ascending"}]} という指定をすると、query/filterの指定にマッチしたページを "xyz-myfield" がアルファベット順にソートして返すという意味になります。

  • "recent": {"weight": 1, "event": {"type": "buy", "origin": "xyz-shop"}} という指定はそのユーザーが最も最近に行った購入（DMPの"buy"イベントが発生した記事)を意味します。

期間の仕様

期間は "1000s"(過去1000秒以内) や "2w"(過去2週間以内)のような、ある期間として指定されます。可能な単位は s（seconds,秒）、m（minutes,分）、h（hours,時間）、d（days,日）、w（weeks,週）、M（Months,月）、y（years,年）です。

"resultFields" に関する詳細

"resultFields" では各アイテムに対して返されるフィールドを指定します。
しかしこれは結果セットを制限することにはなりません。
指定フィールドが含まれているアイテムのみが返されるようにするには"filter"を用いてください。
もし"resultFields"が指定されない場合にはデフォルト値が使用されます。

"resultFields" に指定できるフィールド名：
contenthash, description, dominantimage, dominantimagedimensions, dominantthumbnail, dominantthumbnaildimensions, 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
"url" が指定された場合、結果には "click_url" も併せて返されます（ render templates 参照）。

"pageviewCapping" に関する詳細

ユーザが period で指定された期間内に少なくとも count で指定された回数以上訪問したドキュメントを結果から除外します。matchingMode が "recent" の場合、"pageviewCapping" は実行されません。

名前

タイプ

説明

period

String

どのページビューがカウントされたかを示す期間の指定をします

count

Positive integer

任意項目、デフォルト値は1
期間の指定

期間はどのイベントを含めるかを以下のように指定します。

  • "published" – 全てのイベントをカウントします。デフォルト値です。

  • "modified" – ドキュメントが最後に修正されてからのイベントのみをカウントします。

  • "never" – イベントはカウントされません。

  • "1000s"（直近1000秒のイベントのみをカウント）や"2w"（直近2週間のイベントのみをカウント）
     のようなオフセット。
    可能な単位は秒(s),分(m),時間(h),日(d),週(w),月(M),年(y)です。

例:

  • ページビューキャッピングなし: "pageviewCapping": {"period": "never"}

periodに指定できる期間に上限はありませんが、以下の制約があります：

  • ページビューイベントが評価されるのは最長でもお客様のご契約のデータ保持期間内です。すなわち、例えば period がデフォルトの published の場合、記事の発行日が2年前でもデータ保持期間が13ヶ月の場合は13ヶ月前までのページビューが評価されます。すなわちユーザがその記事を見たのが13ヶ月以上前の場合はレコメンドから除外されません。

  • 評価されるページビューイベントはそのユーザの直近1000件までです。データ保持期間内であっても直近1000件より前のイベントは評価されませんので、例えばあるユーザが直近1週間に1000件アクセスしていたとすると、そのユーザが2週間前に読んだ記事はレコメンドされる可能性があります。

"import"

存在している content settings object をこのノードの子ブランチとしてインポートします。

import は各データリクエストに対して解決され、親の設定をコピーしたり格納したりしません。したがって、インポートされた content の変更は親の設定に影響します。親の設定に基づくの defaults はインポートした設定に適用されます。親の設定を作成や更新したりする時にインポートされた content は同じサイトグループのものである必要があります。インポートされた content が失われた場合、インポートしているノードは結果を返さなくなります（エラーにはなりません）。

名前

タイプ

説明

contentId

String

インポートする別の content object のID

"creative"

クリエイティブからフィールドを返します。

名前

タイプ

説明

creative

String

クリエイティブID

reporting

Array of Objects

キーと値を含むオブジェクト。詳しくはこちらをご覧ください。

クリエイティブはフィールド内にその要素を含むアイテムとして返され、レコメンド設定の結果のフォーマットと似ています。

例えば、要素を含むクリエイティブは以下のようになります。

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

次のようなフィールドを含む単一アイテムを取得することもあります。

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


組み合わせのtype

"combined"

複数のブランチからの結果を結合します。
ブランチごとに異なる"weight"を付与することで、各ブランチからの取得件数を制御できます。
ブランチから返される記事が不足する可能性がある際は、そのブランチに"bufferElements"で0より大きい値を持たせることができます。

それぞれのcombinedのコンテントセッティングオブジェクトは通常 uniquified オブジェクトでラップします。
これにより、ブランチの内容に関係なく、記事の重複を避け、最高の結果をもたらします。

名前

タイプ

説明

branches

Array of Object

コンテントセッティングオブジェクトの配列

bufferElements

Integer

非推奨：影響はありません

ordering

Array of Integer

レコメンドが表示される順序

例: "ordering" が [0, 2, 2, 2, 1] の時に意味することは、1件は最初のブランチ（0番目のブランチ）から、3件は2番のブランチから、1件は1番のブランチから取得します。 

 ブランチ間で重複する結果が発生する場合にはuniquifiedオブジェクトでラップする必要があります（上述の通り）。

これらのブランチは並列に処理されるため、"combined"内のブランチの数には制限があります。
"recs"でキーワードが有効化されている場合や複数のサイトIDが指定されている場合には2ブランチ以上にカウントされます。

"conditional"

複数のブランチの中から条件（例として現在時刻やユーザ、ページなど）にマッチするものを選択して処理します。

名前

タイプ

説明

branches

Array of Object

Content 設定オブジェクトの空ではない配列

オプションでブランチに condition フィールドを指定することができます。条件の満たされた最初のブランチが選択されます。condition フィールドのないブランチはフォールバックブランチと呼ばれます。少なくとも1つのフォールバックブランチが必要で、フォールバックブランチの後にあるブランチに条件は指定できません。ブランチが条件を持つ必要がないことにご注意下さい。

条件を満たすブランチがない場合、フォールバックブランチの中から重み付けをしたランダムなブランチが選択されます。各フォールバックブランチは（他のブランチと比較して）これらのサブ設定で使用される頻度を指定する weight フィールドを設定できます。デフォルトのブランチ weight は 10です。

"randomized"

廃止予定。"conditional" をご利用ください。

"shuffled"

結果順序をシャッフルします。

名前

タイプ

説明

innerSettings

Object

コンテントセッティングオブジェクト

level

Integer

シャッフルするレベル：

0 - シャッフルしない （順序を変更しない）
100 - ランダム（デフォルト） 

"uniquified"

結果から重複するアイテムを排除します。

名前

タイプ

説明

innerSettings

Object

コンテントセッティングオブジェクト

margin

Integer

「オーバーブッキング」のレベルを指定。下記参照。

preference

String

"best"（デフォルト）または"unmodified"を指定。
今後他のオプションが追加される可能性があります。

"best" の場合、結果がスコアの高い順にソートされます。
サブセッティングに"boost"フィールドの設定があれば、
スコアにその設定も加味されます（通常-200から200の間の値を設定）

重複を排除後にも十分な数の結果件数が残るように、innerSettingsからある程度の予備を返すようにしておきます。"margin"フィールドではそのレベルを指定します：

0 - オーバーブッキングしない（重複排除が起こった場合結果件数が少なくなる場合がある）
100 - 100%（すなわち2倍）の数のアイテムを要求
200 - 200%を要求

"budget"

インプレッション数/クリック数/ページビュー数が指定した予算を超えている記事はレコメンドしません。
イベントはウィジェットのサイト内でカウントされ、同じサイトに属する2つのウィジェットでは予算が共有されます。

予算の制約は1日ごとお客様ごと100記事まで適用されます。

特別なフィールド:

名前

タイプ

説明

innerSettings

Object

予算によって制限される Content セッティングオブジェクト。

maxImpressions

Number

このインプレッション数を超えるURLは削除します

maxClicks

Number

このクリック数を超えるURLは削除します。

maxPageviews

Number

このページビュー数を超えるURLは削除します。maxImpressions または maxClicks と一緒に指定することはできません。

period

String

この期間内のイベントのみを含みます。1ヶ月以上は指定できません。デフォルトは使用可能な全ての期間がカウントされます。

利用を推奨するタイプ

"defaults"

"recs"コンテントセッティングのデフォルトを定義します。

名前

タイプ

説明

innerSettings

Object

ここで指定するデフォルト値が適用されるコンテントセッティングオブジェクト

importFromContentId

String

追加の defaults をインポートするための別のコンテンツID

[any field]

...

デフォルト値を指定するフィールドとその値

多くのブランチを含むセッティングオブジェクトでは各ブランチそれぞれに同じパラメータを指定することになります（例えば resultFields の指定はどのブランチでも同じ）。defaults の目的はこれを簡素化するものです。すなわち、ここで指定されたパラメータはinnerSettingsの内部では繰り返す必要がありません（上書きすることも可能です）。

defaults がネストされた場合、最も内側の default の値が使われます。共通のフィールド（tag、weight、conditionなど）はデフォルト値として解釈されませんのでご注意ください。

importFromContentId を使って参照された Content 設定は innerSettings を持たない単一の defaults ノードで構成しなければなりません。指定したフィールドはインポートされたContent設定のフィールドを上書きします。インポートは各データリクエストに対して解決され、親の設定をコピーせず、保存もしません。したがってインポートされたContent への変更は現在の設定に反映されてしまいます。設定を作成または更新する時はインポートされるContentは存在し、同じサイトグループ内のContentでなければなりません。インポートされた Content オブジェクトが削除されると importFromContentId は無効になります。

例）

{ "type": "defaults",
　　　　　　　　　　　　　"siteIds":[ "01234" ],
　　　　　　　　　　　　　　　　　"innerSettings":{
　　　　　　　　　　　　　　　　　　　　　"type": "recs",
　　　　　　　　　　　　　　　　　　　　　[ここでのsiteIdsの指定は不要] 

　　　　　　　　　　　　　　　　　　}
　　　　　　　　　　...
　　　　　　　　}

その他のタイプ

"schemeAdjusted"

この設定は、参照中のページがhttpsの場合にURLの書き換えを行うために使用します。これは"mixed content"（混在コンテンツ）の警告を避けるために使用します。

名前

タイプ

説明

innerSettings

Object

コンテントセッティングオブジェクト

fields

Array of String

書き換えを行うURLを含んだフィールドのリスト

基本的な Content widget setting の例

複数のレコメンデーションのロジックをミックスした例です：

  • 直近24時間で最もポピュラーな記事（"trend"および"period"）

  •  参照中のページ（ウィジェットが設置されたページ）に似ている記事（"contextual"）

  •  ユーザの興味にマッチするもの（"behavioral"）

  • どの場合も7日以上前の記事は表示しない設定（"maxAge"）

  • 記事に画像があることが必須（"query(dominantthumnail:\"*\")")

{
  "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(dominantthumbnaildimensions:\"*\")"
}


複雑な Content widget setting

この例は現実的な設定ではないかもしれませんが、上記で説明した各設定値の使用法の解説のために作成してあります：

{
    "type": "schemeAdjusted",
    "fields": [ "dominantthumbnail" ],
    "innerSettings": {
        "type": "combined",
        "ordering": [1, 1, 0],
        "bufferElements": 1,
        "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": 3600 }
                            },
                            "query": "query(dominantthumbnaildimensions:\"*x*\")",
                            "siteIds": [ "9222300729399686919" ]
                        }
                    },
                    {
                        "type": "uniquified",
                        "weight": 5,
                        "margin": 150,
                        "urlUniquenessRegex": ".*-([0-9]+)\\.html$",
                        "innerSettings": {
                            "type": "recs",
                            "matchingMode": {
                                "trend": { "weight": 50 },
                                "behavioral": { "weight": 50 }
                            },
                            "resultFields": [ "url", "title", "description", "dominantthumbnail" ],
                            "siteIds": [
                                "9222300729399686919",
                                "9222311772423575900"
                            ]
                        }
                    }
                ]
            }
        ]
    }
}


Last updated: