Ad events

Retail events

Models

Collect API

Connector Schema Management

Connector Management​

Connect API

Organisation

User

Permissions

Roles

Invitations

Media API

Catalogs

Products

Place

Override

Search API

Channels and Features of ALL Potential Integration Methods


Steps to Lowest Technical Lift Integration Method

Grant Zitcha access to Meta Product Catalogs

Grant Zitcha access to Google Tag Manager

Steps to provide Zitcha with META Catalogs Access

For Zitcha to create Facebook and Sponsored Product Ads on behalf of your business, your assets (Business Page, Ad Account, Instagram & Catalogs) must be shared with the Zitcha Facebook Business Manager and granted ‘Full Control’. *Please only share your main Business Page (usually at a national level).

To do this please follow the below steps:

Select Give a partner access to your assets.

On this screen, you can add partners to multiple assets.a. Choose a type of asset in the first column (Page, Ad Account, Instagram & Catalogs.)b. Select the assets you want to add your partner to in the second column.c. Assign the Admin role/Full control for your partner in the third column. Repeat these steps until you've chosen roles for all of the assets you want to assign.

Steps to provide Zitcha with Google Tag Manager Access

In order for Zitcha to generate and run ads on your website the below users will require standard access to your Google Tag Manager on your production site. Additionally, please grant the same Zitcha users ‘admin’ access to the GTM account linked to your staging environment:

please contact your solutions lead for these email addresses.

To grant access to the users, follow these steps:

In the Account column, select User Management.

Click Invite. Each invited user will receive an invitation to use the container.

Credit Lines: Single line of credit in the Facebook account is required.

Facebook Feeds are required for product related campaigns used in Meta.

Facebook Products that aren't split by brand may delay onboarding

Keep this guide at hand for a smooth integration. We're here to help every step of the way!

This Onsite guide ensures a smooth integration with all offsite assets, covering all essential steps from account setup to understanding integration challenges for a successful partnership.

Onsite 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.

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:

: 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.

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

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

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

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

: 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.

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

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

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

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

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

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

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

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

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

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.

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.

 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.

 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.

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.

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

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.

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.

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.

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.

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.

Onsite guide

Articles

Onsite Integration Guide

Sponsored Product Integration Guide

onsite-guide-topic - Articles Page

Onsite guide

Articles

Onsite Integration Guide

Sponsored Product Integration Guide