Share via


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.

See Also

Other Resources

Pipeline Component Reference