Sponsored Product Integration Guide

The Zitcha Search API is designed to enhance product search capabilities, offering a comprehensive way to search, filter, and sort through products based on various attributes. Below is a detailed overview of the product fields, the type of data stored in each, and how these fields interact with the search endpoint and query method.

Product Fields and Data Types

The product data schema is designed to be flexible and versatile, allowing for a wide range of product types and attributes. The schema is based on Meta’s Data Catalog and includes the following fields:

default_rank: An int32 integer. This field can be used to rank products in search results by default, which is useful for prioritising products based on metrics like popularity or relevance.

store_id: An int32 integer. This identifies the specific store or location associated with the product, allowing for filtering and sorting by store.

product_id: A string. Acts as a unique identifier for each product, critical for search operations and unique product retrieval.

title: A string. The name or title of the product, is searchable and can be used to display in search results.

description: A string. Offers a detailed description of the product, useful for full-text search to match on product features or specifications.

price: A string. Indicates the product's price, including currency symbols or additional text, making it versatile for various formats but may require parsing for numerical comparison.

image_link: A string. URL pointing to the product's image, useful for visual representation in search results.

link: A string. A direct URL to the product's page on the website, enabling direct access to the product's detailed page.

availability: A string. Shows whether the product is in stock, out of stock, or available for pre-order, essential for filtering based on availability.

product_type: A string. Describes categories or types the product belongs to, allowing for categorization in search.

condition: A string with faceting enabled. Specifies the product's condition (new, used, refurbished, etc.), useful for filtering search results based on condition.

brand: A string with faceting enabled. The brand or manufacturer of the product, important for brand-specific searches.

color: A string with faceting enabled. Describes the product's color(s), offering a way to filter search results by color.

size: A string. The size of the product, which could vary in meaning (e.g., clothing size, bottle size), important for searches requiring size specificity.

bid: A float. Represents a bidding amount for sponsored products or ads, influencing their position in search results based on the bid amount.

Endpoint and Query Method

The Zitcha Search API provides a specific endpoint for a retail domain for querying these product fields, allowing for a flexible and powerful search experience. The endpoint supports complex queries against one or more text fields (e.g., title, description) and allows filtering against numerical or facet fields (e.g., store_id, brand, condition). The results can be sorted and faceted to provide a highly customised search experience.

To search for products, the API could be queried with parameters like q for the search query, query_by to specify which fields to search against, filter_by to apply filters such as availability or store_id, and sort_by to define the order of the results, using _text_match

,bidto prioritise by text match quality and bid amount for sponsored products.

The search query method involves sending these parameters to the Zitcha Search API's search endpoint will look like this:

GET /api/products/search/?q=panadol&query_by=brand:_text_match

,bid&query_by=title,description,bid&page=1

The exact syntax for the query would depend on the implementation details of the Zitcha Search API and the programming language or framework being used to make the request.

This approach ensures that users can find products that closely match their search terms while also allowing brands to promote certain products through bidding.

Implementation Overview

Search Request Modification: Modify the search request logic to include calls to both the existing search API and the Zitcha Search API. This dual request approach ensures that both regular and sponsored products are retrieved during a search query.

Combining Results: Implement logic to merge the results from the existing search API and the Zitcha Search API. Since the Zitcha Search API can return either just the promoted product IDs or the entire product details, ensure this logic can handle both response types seamlessly.

Sorting Logic: Apply a sorting mechanism that incorporates the bid value for sponsored products. Use the sort_by parameter with the value "_text_match

,bid" to prioritize sponsored products in the search results based on their bid amounts.

Display Logic: Ensure the front-end logic can differentiate between regular and sponsored products, perhaps by highlighting sponsored products or marking them with a "Sponsored" label to maintain user transparency.

Pagination and Filters: Adjust the pagination and filter logic to accommodate the inclusion of sponsored products in the search results. This may involve recalculating the number of pages or adjusting filters to include or exclude sponsored products as needed.

Testing and Optimization: Conduct thorough testing to ensure that sponsored products are correctly integrated and displayed as expected. This includes testing for various search queries, filter combinations, and pagination scenarios. Optimisation may be required to ensure the performance of the search feature remains high.

Detailed Steps

Modifying Search Requests

When a search query is initiated, make simultaneous requests to the existing search API and the Zitcha Search API.

For the Zitcha Search API, construct the search request similar to the existing search but include the sort_by parameter with "_text_match

,bid" to prioritise sponsored products.

Handling Zitcha Search API Responses

Parse the response from the Zitcha Search API to extract either the product IDs or the full product details of sponsored products.

If only product IDs are returned, retrieve the full product details from the existing product database or API as needed.

Merging and Sorting Results

Merge the results from the existing search API and the Zitcha Search API. Ensure sponsored products are correctly interleaved within the search results based on the sort_by logic.

Sponsored products with higher bids should appear higher in the search results, followed by regular products sorted by relevance to the search query.

Front-End Integration

Update the UI to distinguish sponsored products from regular products. This could involve adding a special badge, changing the background color, or using any other visual indicator.

Ensure that the UI updates dynamically to reflect the correct mixture of sponsored and regular products based on the search query and filters applied.

Testing and Quality Assurance

Test the integrated search feature extensively to ensure that sponsored products are displayed correctly and do not disrupt the user experience.

Monitor the performance impact of adding sponsored products to the search results and optimize as necessary.

Additional Considerations

Monitoring and Analytics: Implement tracking for interactions with sponsored products to gauge their performance and adjust bidding strategies accordingly. The recommended approach on client-side is to implement Zitcha's Collect API to track user interactions with sponsored products.

Feedback Loop: Establish a feedback mechanism to refine the display and ranking of sponsored products based on user engagement and conversion rates.

By following these implementation notes, the engineering team can effectively integrate sponsored products into the pharmacy's website search feature, enhancing the visibility of sponsored products and the overall search experience for users.