CSFSelectWinners
Use the CSFSelectWinners pipeline component to choose items based on their final scores in the Content Selection pipeline.
Intended use: Content Selection pipeline, Select stage.
Configuration Values
You can determine when the CSFSelectWinners pipeline component displays house ads by setting component properties. Use the following box on the Select Winners tab of the Component Properties dialog box to determine this information.
Box |
Description |
|---|---|
Switch to house ads |
The threshold at which house ads will be selected over paid ads. When the maximum Need of Delivery (NOD) for paid ads drops below this value, house ads are selected. The default is 0.95. |
Values Read
The CSFSelectWinners pipeline component reads the following values from the indicated dictionaries.
Key |
Dictionary |
Description |
|---|---|---|
_content.score |
Order |
The final scores of the various content items. |
NumRequested |
Order |
Optional. The number of content items that should be selected for return. The default is 1 (one). |
_content.industry |
Order |
Optional. The industry tag used to prevent two content items from same industry from being selected. |
_content.need_of_delivery |
Order |
Optional. The contract requirements for delivering the ad. |
_content.ad_type |
Order |
Optional. A paid (1) versus house (2) ad type. |
_content.ad_weight |
Order |
Optional. This key is used for house ads to allow some to be displayed more frequently. |
_content.customer_id |
Order |
Optional. This key is used to prevent competing ads. |
ContextProfile.PageHistory |
Context |
Optional. A reference to the page-level history string. The reference allows the history to be passed between requests for content that are on the same page (can be used cross-page as well). This key is retrieved from the ContextProfile dictionary in the Context dictionary. It contains the item_ids of content items already selected on the page. |
Values Written
The CSFSelectWinners pipeline component writes the following values to the indicated dictionaries.
Key |
Dictionary |
Description |
|---|---|---|
_winnerindexes |
Order |
A reference to a SimpleList Object containing the ContentList Object indexes of selected content items. |
_event |
Order |
This key is set to the string "REQUEST", unless it is already set. |
context.ContextProfile.PageHistory |
Context |
Optional. The new page history, now including items selected in the current request. The PageHistory key is in the ContextProfile dictionary in the Context dictionary. |
Remarks
To communicate the winners, the CSFSelectWinners pipeline component builds a new SimpleList object that contains the ContentList object indexes up to the requested number of winning content items.
The CSFSelectWinners pipeline component performs the following additional actions:
Sets the _event key to the string "REQUEST", unless it is already set.
Uses the PageHistory key to prevent showing the same ad more than once on a page. This is most useful in network ad models where multiple selection requests are made from the same page.
Prevents competing ads from appearing on the same page. This is based on the industry setting of each ad, combined with a user identifier.
The CSFSelectWinners pipeline component looks at the NumRequested key in the Order dictionary to determine how many content items to select. If that key is missing, one content item is selected. It is not considered an error to return fewer than NumRequested content items. The caller must handle this condition.
The PageHistory key is a string containing a list of IDs for content items already selected for the current page. The caller defines what constitutes a "page," and the caller is responsible for saving the PageHistory key across calls to the same page. The item_id keys from the content items in the ContentList object are written to this string in decimal form and are separated by commas. If the same ContentSelector Object is used for multiple content requests on the same page, then the PageHistory key will automatically be passed between the calls.
The following list describes the selection algorithm for ads:
Items appearing in the PageHistory key are not eligible for selection.
Paid ads with a Need of Delivery (NOD) value greater than the house ad threshold will always be selected over house ads.
Ads that compete with another ad that was already selected, including ads in the PageHistory key, are not eligible for selection. Competing ads are defined as ads in the same industry but from different users.
Selection proceeds are based on score, returning higher scores first. If multiple paid ads have the same score, selection between them is random.
The following list describes the selection algorithm for content types other than ads:
Items appearing in the PageHistory key are not eligible for selection.
Selection proceeds are based on score, returning higher scores first. If multiple items have the same score, selection between them is random.