Skip to main content

Boosting Promoted Items

Recommendation carousels and search results are prime real estate. Naturally, businesses often need to strategically promote specific items within these spaces – perhaps a new product launch, a sponsored listing, items from a marketing campaign, or high-margin inventory. However, crudely injecting promotions without considering the user's context or personal preferences can backfire spectacularly. Showing irrelevant promoted items alongside otherwise personalized suggestions can feel jarring, degrade the user experience, and ultimately harm engagement and trust.

The challenge lies in finding the right balance: how do you give specific items the visibility they need for business reasons, while still maintaining a high degree of personalization and relevance for the user? Simply inserting items manually or using basic rules often leads to suboptimal experiences. A truly intelligent system should be able to weave promotions into personalized rankings naturally and effectively.

The Shaped Approach: Integrated, Controlled Boosting​

Shaped avoids these disjointed approaches by building promotion capabilities directly into its ranking engine. This allows for a seamless interleaving of promoted items within personalized results, giving you fine-grained control over the process.

How Shaped Handles Item Boosting:

  1. Flagging Items for Promotion (boost column): You designate items to be considered for promotion simply by adding a reserved boost column to your item data and setting the value to 1 for the desired boosted items. For more control, different boost values can be set per item, and the relative values are used to perform a weighted boosting. This is typically done within the fetch.items SQL query in your model definition.
  2. Controlling Promotion Magnitude (boosting_factor): A parameter called boosting_factor (ranging from 0 to 1) controls the strength or proportion of boosting.
    • 0: Ignores the boost column entirely; results are purely personalized.
    • 1: Maximizes boosting, pushing all boosted items to the top.
    • Values between 0 and 1 allow you to tune the balance. Shaped uses an Epsilon-Greedy approach, meaning boosting_factor relates to the probability of selecting a boosted item vs. a personalized one at each ranking step, leading to natural interleaving.
  3. Limiting and Personalizing Boosted Items (retriever_k_override.boosted): Often, you have a large pool of potentially promotable items (e.g., all items of a specific brand), but you don't want to flood the user with all of them. The retriever_k_override.boosted setting lets you specify the maximum number (k) of boosted items to consider for promotion per user request. Shaped then intelligently selects the most relevant k items from the boosted pool for that specific user, effectively delivering personalized promotion.
  4. Flexible Configuration: You can set default boosting behavior (boosting_factor, retriever_k_override) in the model's YAML definition (inference_config) and/or override these settings dynamically for specific requests via the rank API's config parameter.

Implementing Personalized Boosting with Shaped​

Let's illustrate promoting items of a specific brand ('SuperBrand') within personalized recommendations.

Goal: Give 'SuperBrand' items increased visibility, but ensure the experience remains personalized, perhaps showing only the 5 most relevant 'SuperBrand' items to each user from the available pool.

1. Prepare Data with boost Column: Modify the fetch.items query in your model definition to add the boost column based on your promotion criteria.

boosting_model.yaml
connectors:
  - type: Dataset
    name: item_data_with_brand
    id: items
fetch:
  items: |
  SELECT
    item_id,
    title,
    brand, -- Use brand to determine promotion
    category,
    price,
    -- Add the boost column based on brand
    CASE
      WHEN brand = 'SuperBrand' THEN 1 -- Flag SuperBrand items for boosting
      ELSE 0                           -- Other items get 0
    END AS boost
  FROM
    items

2. Define Model with Default Boosting Config (YAML): Configure the desired default behavior in the model YAML.

boosting_model.yaml
model:
  name: personalized_promoter_v1
  inference_config:
    # Default boosting strength (e.g., moderate boost)
    boosting_factor: 0.2 # ~20% chance favoring boosted items per slot
    # Default limit on boosted candidates per request + personalized selection
    retriever_k_override:
        boosted: 5 # Consider only the top 5 most relevant boosted SuperBrand items for this user
connectors:
  - type: Dataset
    name: item_data_with_brand
    id: items
  - type: Dataset
    name: user_events
    id: interactions
fetch:
  items: |
    SELECT
      item_id, title, brand, category, price,
      CASE WHEN brand = 'SuperBrand' THEN 1 ELSE 0 END AS boost
    FROM items
  events: |
    SELECT user_id, item_id, timestamp AS created_at, event_type FROM interactions

3. Create the Model:

shaped create-model --file boosting_model.yaml

4. Rank Items (Defaults and Overrides):

  • Using Defaults: A standard rank call will use the boosting_factor: 0.2 and retriever_k_override.boosted: 5 set in the YAML. The results will be a personalized list, with up to 5 relevant 'SuperBrand' items intelligently interleaved based on the 0.2 factor.
  shaped rank --model-name personalized_promoter_v1 --user-id USER_XYZ --limit 20
  • Overriding at Inference Time: You can change the behavior for specific requests using the config parameter. 
const { ShapedClient } = require('@shapedai/shaped');

const apiKey = process.env.SHAPED_API_KEY; // Assumes this is set
const shapedClient = new ShapedClient({ apiKey: apiKey });
const response = await shapedClient.rank({  
    modelName: 'personalized_promoter_v1',  
    userId: 'USER_XYZ',  
    limit: 20,  
    config: { // Pass overrides here  
        boostingFactor: 0.5,
        retrieverKOverride: {  
            boosted: 10  
        }  
    },  
    returnMetadata: true  
});

5. Expected Outcome: The API responses will contain a single list of item IDs, seamlessly blending highly relevant personalized items with the promoted ('SuperBrand') items. The frequency and position of promoted items are controlled by boosting_factor, and the retriever_k_override ensures that even within the promotion, the most relevant boosted items for that user are prioritized, up to the specified limit (k).

Conclusion: Promote Intelligently, Not Intrusively​

Promoting items is a business necessity, but it shouldn't come at the cost of user experience. Traditional methods often force a trade-off between visibility and relevance. Shaped's integrated boosting capability offers a sophisticated alternative.

By simply tagging items with a boost column and using parameters like boosting_factor and retriever_k_override, you can seamlessly interleave promoted items within personalized rankings. This approach provides fine-grained control, allows for personalized selection even among promoted items, and maintains a high-quality, relevant experience for your users. Stop treating promotions as intrusive insertions and start blending them intelligently with Shaped.

Ready to integrate promotions seamlessly into your personalized experiences?

Request a demo of Shaped today to learn more about item boosting. Or, start exploring immediately with our free trial sandbox.