SelectWinners
Use this component to choose items based on their final scores in the Content Selection pipeline.
Although the component appears as SelectWinners in the Pipeline Editor, its ProgID is Commerce.CSFSelectWinners.
Intended use: Content Selection pipeline, Select stage.
Configuration Values
You can determine when the SelectWinners 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 SelectWinners component reads the following values from the indicated dictionaries.
| Key | Dictionary | Description |
_Content |
Order | A reference to the ContentList object. Multiple fields are read. For more information, see the Remarks section. |
NumRequested |
Order | Optional. The number of content items that should be selected for return. The default is 1 (one). |
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. |
The SelectWinners component reads the following values for each item in the ContentList referred to by the _content key.
| Key | Description |
Score |
The final scores of the various content items. |
Industry |
The industry tag used to prevent two content items from same industry from being selected. |
need_of_delivery |
The contract requirements for delivering the ad. |
ad_type |
A paid (1) versus house (2) ad type. |
customer_id |
This key is used to prevent competing ads. |
ad_weight |
This key is used for house ads to allow some to be displayed more frequently. |
The Score key is required. Other keys are required only for ad selection.
Values Written
The SelectWinners component writes the following values to the indicated dictionaries.
| Key | Dictionary | Description |
_event |
Order | This key is set to the string "REQUEST", unless it is already set. |
PageHistory |
Context | The new page history, now including items selected in the current request. The PageHistory key is in the ContextProfile dictionary in the Context dictionary. |
_winnerindexes |
Order | A reference to a SimpleList object containing the ContentList object indexes of selected content items. |
Remarks
To communicate the winners, the SelectWinners component builds a new SimpleList object that contains the ContentList object indexes up to the requested number of winning content items.
The SelectWinners component performs the following additional actions:
Sets the
_eventkey to the string "REQUEST", unless it is already set.Uses the
PageHistorykey 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.
This 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
PageHistorykey 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
PageHistorykey, 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
PageHistorykey 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.