In search and native ads delivery, Allocation is the process of deciding whether and where to insert each potential listing into the search, feed, or discovery results. Promoted's comprehensive allocation system is called Blender. This document details the components of Blender and shows an example Blender code configuration.

Unified configuration system. Blender unifies search, feed, and native ads allocation to achieve optimal placement of listings. Blender allows Promoted to blend content, control diversity, and achieve custom business goals (e.g., new seller traction). All allocation rules and decisions are combined into this unified configuration system.

Marketplace-specific controls. Promoted works collaboratively with each marketplace to configure Blender, no matter whether the marketplace needs search, ads, or unified search and ads.

Components of Blender

Each component of Blender factors into the ordering of the listings in allocation. This list is not exhaustive; Promoted implements custom features on a per-client basis.

Quality score

The quality score, calculated from Promoted's model-generated probabilities, contributes to the ranking of listings. These probabilities are generated for every query, for every potential listing, specific to this user and context.

User actions

Some of these probabilities represent the likelihood of the user performing specific actions, like click or purchase.

Long-term revenue optimization

Promoted also generates probabilities and expected values to represent long-term revenue optimization.

Combined formula

These probabilities are combined into a formula to generate the score. The formula is refined over time, and could be as simple as p(click) * p(purchase | click), or may contain additional variables, weights, and filters.

📘

The quality score is just one part of a comprehensive allocation system.

Blender does not use a single, preset "goodness" score to rank listings. The quality score is dynamic and unique to each user, context, and query, and is used in combination with marketplace-specific ranking techniques. This may include keyword matching, distance, semantic relevancy, and business goals.

Custom slots in search results

Promoted offers the ability to customize specific positions in the ranking order. Each position in the results may use a different allocation "rule" that determines which listing will be chosen for that particular slot. The positioning may be determined deterministically or probabilistically.

👍

For each customizable slot, Promoted selects the best listings out of a group of eligible listings.

If multiple items are eligible to be placed in boosted, pined, challenger, or maximizer slots, Promoted will default to the standard search ranking to choose the best within that group (based on click/conversion predictions, keyword match, distance, and other marketplace-specific features).

If no eligible items exist (e.g., they were filtered out by retrieval or by Promoted's system), then the slot will be bypassed and Promoted will default to standard search ranking.

Example configuration

An example Blender configuration is shown below, with some constants and variables obfuscated for confidentiality. The actual ranking is decided by the SORT() allocation rules. Each rule is followed in order until the LIMIT() is reached, if applicable. This means the first few listings ranked may follow a different rule from the following ones.

// Values are calculated to be used in allocation rules
// Based on the features in each listing
"clean_long_quote_match = IF(FEATURE(CLEAN_QUERY_TITLE_MATCH) > 3, IF(FEATURE(CLEAN_QUERY_NUM_WORDS) > 3, 1, IF(FEATURE(QUERY_HAS_QUOTES) > 0, 1, 0)), 0);",  
"title_query_substring = IF(FEATURE(\"titleQueryWordsSubstring\") > 2, 1, 0);", 

// Model predictions
"p_click = FEATURE(PREDICTION_NAVIGATE);",
"p_purchase = FEATURE(PREDICTION_POST_CLICK_PURCHASE);",

"score = p_purchase * p_click",

// Allocation rules combine the above values to sort the listings
// In the ranking, prioritize substring match then score (in case of ties)
"SORT(clean_long_quote_match, title_query_substring, score);"  

Boosted (sponsored) listings

Using Promoted for both organic search and native ads unifies and simplifies your system, ensuring results are relevant and optimal. When native ads are implemented with organic search and feed, Promoted calls them boosted listings. In the rules, Promoted first filters out listings that are not eligible to be a native ad (some listings may only be eligible for organic search). Eligibility is determined by the seller and sent to Promoted via the Delivery request, just like other associated metrics.

// New boosted value and score
"boosted = IF(FEATURE(\"adsEnabled=true\") == 1, IF(FEATURE(\"boosted_profile_config.is_boosted\") == 1, 1, 0), 0), 0), 0);",
"boosted_score = IF(boosted == 1, p_click * FEATURE(\"boosted_profile_config.bid_value\"), 0);",

"SELECT<BOOSTED> WHERE(boosted > 0) SORT(clean_long_quote_match, title_query_substring, boosted_score, score) ABSOLUTE_POSITION(1);",

After filtering, the SELECT<BOOSTED> rule uses a boosted_score that combines model-generated probabilities with ad-specific features like the bid value. In the example, the SELECT<BOOSTED> rule places an ad into the second slot of the results (as long as an eligible listing exists). Otherwise, the listings are sorted as described previously.

Pinned listings (optional)

Marketplaces may want to "pin" a particular item (not an ad) at the top of results — or select from a group of eligible (or "pinnable") items. This can be useful for bumping up an item the customer "liked" or "favorited" earlier. This can be performed by setting an eligibility value as a feature in the content item (e.g., pin_to_front). Promoted will then filter the retrieval items that have this value set to true, and select the best one.

// If listing is eligible to be pinned, set pinned to true
"pinned = IF(FEATURE(\"pin_to_front\") > 0, 1, 0);"

// The third search result is the challenger, if one exists
"SELECT<PINNED> WHERE(pinned == 1) SORT(clean_long_quote_match, title_query_substring, score) ABSOLUTE_POSITION(0)"

// All results except for the challenger slot follow the standard rule
// In the ranking, prioritize substring match then score (in case of ties)
"SORT(clean_long_quote_match, title_query_substring, score);" 

Challenger slots (optional)

The challenger slot is a position in the ranking that enforces a particular rule. Whereas boosted slots are paid native ads, challenger slots achieve particular business objectives. Marketplaces can use this to promote, for example, new sellers or new items on the platform to gain initial traction. The example below shows the challenger slot prioritized for items with fewer purchases to help gain traction and avoid being buried in the results due to a lack of data, reviews, etc.

Here's a Blender rule for emphasizing items with few purchases (< 10):

// If listing was purchased fewer than 10 times, set challenger to true
"challenger = IF(FEATURE(\"total_purchases\") \< 10, 1, 0);", 

// The third search result is the challenger, if one exists
"SELECT<CHALLENGER> WHERE(challenger == 1) SORT(clean_long_quote_match, title_query_substring, score) RELATIVE_POSITION(3);"

// All results except for the challenger slot follow the standard rule
// In the ranking, prioritize substring match then score (in case of ties)
"SORT(clean_long_quote_match, title_query_substring, score);" 

Maximizer slots (optional)

The maximizer slot is similar to the challenger, except it maximizes a quantitative objective, such as revenue. See below for an example of a revenue maximizer that forces the listing in slot 4 to be above a price threshold, such as $150.

// If country is US, set threshold to 150. If not, set to 100
"price_threshold = IF(FEATURE(\"search.filter_country_code=US\") == 1, 150, 100)));"

// Set maximizer to true if price is above threshold
"maximizer = IF(FEATURE(\"average_price\") > price_threshold, 1, 0), 0);"

// The third search result prioritizes the maximizer value first, then others if tied
"SELECT<MAXIMIZER> WHERE(maximizer == 1) SORT(clean_long_quote_match, title_query_substring, score) RELATIVE_POSITION(5);"
// All results except for the maximizer follow the standard rule
"SORT(clean_long_quote_match, title_query_substring, score);" 

Putting it all together

Let's put the Blender rules for both search and ads together in a single code block:

/***** Same rules and predictions as before *****/
"clean_long_quote_match = IF(FEATURE(CLEAN_QUERY_TITLE_MATCH) > 3, IF(FEATURE(CLEAN_QUERY_NUM_WORDS) > 3, 1, IF(FEATURE(QUERY_HAS_QUOTES) > 0, 1, 0)), 0);",  
"title_query_substring = IF(FEATURE(\"titleQueryWordsSubstring\") > 2, 1, 0);", 

"p_click = FEATURE(PREDICTION_NAVIGATE);",
"p_purchase = FEATURE(PREDICTION_POST_CLICK_PURCHASE);",

// The boosted score already handles native ads, so this is the regular search score
"score = p_purchase * p_click;"

// "challenger" rule
"challenger = IF(FEATURE(\"total_purchases\") \< 10, 1, 0);", 

// "maximizer" rule
"maximizer = IF(FEATURE(\"average_price\") > price_threshold, 1, 0), 0);"

// "boosted" value and score to account for native ads within organic results
"boosted = IF(FEATURE(\"adsEnabled=true\") == 1, IF(FEATURE(\"boosted_profile_config.is_boosted\") == 1, IF(FEATURE(1327178) == 0, 1, 0), 0), 0), 0);",
"boosted_score = IF(boosted == 1, p_click * FEATURE(\"boosted_profile_config.bid_value\"), 0);",

// Allocation rules combine the above values to sort the listings
// Assign native ads to absolute positions (e.g., the first and third search results)
// Use multiple rules to customize ordering of remaining results
"SELECT<BOOSTED> WHERE(boosted > 0) SORT(clean_long_quote_match, title_query_substring, boosted_score, score) ABSOLUTE_POSITION(0);",
"SELECT<CHALLENGER> WHERE(challenger == 1) SORT(clean_long_quote_match, title_query_substring, score) RELATIVE_POSITION(3);"
"SELECT<MAXIMIZER> WHERE(maximizer == 1) SORT(clean_long_quote_match, title_query_substring, score) RELATIVE_POSITION(5);"

"SORT(clean_long_quote_match, title_query_substring, score);"  

Each item is either inserted at a particular position in the ranking order or not ranked at all; only a small percentage of all items in retrieval will be ranked and shown to the user initially. Promoted supplies high-quality results and dynamic ranking of items when the user refreshes the page or loads additional items. This also applies to geolocation-based marketplaces with a map view — as long as geolocation data is being sent to Promoted in real-time, the list will update immediately when the user adjusts the map or filters.