Use Case in Delivery
How and why to use the useCase
field in the Delivery request
The use case is a field in the Delivery request. Its purpose is to signal to Promoted which surface or interface the content is being served on.
Promoted's models use useCase
as a feature to better customize predictions for each surface. The most common use cases are SEARCH
, FEED
, and DISCOVER
, and some marketplaces may have additional surfaces that serve content to the user. Each of these surfaces should be mapped to a corresponding useCase
that most closely matches the function of the surface.
There is no special logic to each
useCase
value. The purpose is to serve as a unique label to Promoted's models, as well as a human-readable reference.Although there are no strict mapping rules, it is recommended to choose the use case most applicable to the surface. Guidance on enum mapping is below. For any special or unlisted use cases, please contact Promoted for additional guidance.
The CUSTOM
useCase
field is meant for the following scenarios:
- A surface is significantly different from the existing fields
- Mapping the surface to an existing field may create confusion (e.g., due to terminology)
- All other relevant fields are already in use
- Multiple surfaces are related to a single field (e.g., using custom fields for
SEARCH_RELATED_CONTENT
andFEED_RELATED_CONTENT
if there is related content for both search and feed)
The UNKNOWN_USE_CASE
is recommended for use as a default, to prevent data from new surfaces from mixing with other use cases until the new surface is labeled properly.
Enum values and examples
The useCase
is an enum that includes the following fields:
Enum Value | Example of interface |
---|---|
SEARCH | Search results (most common use case) |
SEARCH_SUGGESTIONS | Suggested searches that show up in a different view from standard results |
FEED | Custom feed, such as a homepage feed |
RELATED_CONTENT | Related items suggested on a product page |
CLOSE_UP | |
CATEGORY_CONTENT | Items in a common category or page, like "trending" or "home page" |
MY_CONTENT | General recommendations |
MY_SAVED_CONTENT | Saved wishlist recommendations |
SELLER_CONTENT | Order confirmation page |
DISCOVER | Results during browsing or discovery |
UNRECOGNIZED | |
UNKNOWN_USE_CASE | A signal for new use cases in testing or debugging, to prevent unknowingly mixing data from different surfaces. Not to be used long term. |
CUSTOM | Custom use case not able to be mapped to other fields |
See the delivery proto for more details on the use_case
field.
This document is a work in progress
Updated 21 days ago