Minimum Viable Product Integration

How to get up and running with a minimum viable product version of Citrus.


The Minimum Viable Product Integration Guide explains to retailers the conditions that must be met in order to integrate with the Citrus API.

This guide describes the most basic integration possible that would permit a retailer to set up its e-commerce website and infrastructure to use the ad-placement services offered by Citrus. More complicated integrations than the one described here are possible.

"Integrating with the Citrus API" is another way of saying "setting things up to send your catalog data to Citrus in order to begin placing ads on your e-commerce website".

Capabilities Necessary for a Minimum Viable Integration

To integrate with the Citrus API, the retailer's e-commerce website must be capable of the following:

  • Requesting ads for the search result page and selected category pages.

  • Sending information about ads and purchases to Citrus.

  • Reporting impressions and clicks to Citrus from within the browser.

Conditions That Must Be Met to Achieve a Minimum Viable Integration

In order to achieve a minimum viable product integration, the following conditions must be met.

Ensure that API Authentication is Working

API authentication must be set up, as described in the "Creating an Account" section of the "Getting Started" Group.

Export and Synchronise your Catalog Storage

The catalog storage associated with the retailer's E-commerce site must be exported and synchronised with the Citrus API. This can be done as described in the "Creating a Catalog" and in the "Creating a Product" section of the "Getting Started" section. In this context, "creating a catalog" means creating a catalog in the Citrus API. It is assumed that your e-commerce website already has an associated catalog.

Ensure that You can Send a Context to Citrus

A simple "context" must be sent to Citrus. Here, "context" has a specific and technical meaning. A "context" is a bit of code that defines the conditions under which a product is shown to a customer (you might think of this as another way of saying "This defines the search terms that cause ads to appear to customers.").

Here is an example of a context for the pagetype "SEARCH":

"context": {
"pageType": "SEARCH",
"catalogId": "$$628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"searchTerm": "cheese",
"maxNumberOfAds": 5

And here is an example of a context for the pagetype "CATEGORY":

"context": {
"pageType": "CATEGORY",
"catalogId": "$$628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"productFilters": [
["RedWine", "Shiraz"]
"maxNumberOfAds": 5

No customer information or cart items are necessary in this simple context. The simple context consists only of search terms and necessary filters. A paradigm example of a context can be seen in the "Requesting Ads" section of "Getting Started". Sending a context to Citrus is a part of the process of requesting ads from Citrus.

Ensure that Unavailable Products Do Not Generate Ads

Products that are not available for purchase must be flagged so that Citrus does not generate ads for them. This can be achieved by making sure that the "inventory" field in the "CatalogProduct" object is zero (0) when a given product is not available.

Though it is important to keep track of the amount of inventory in stock so that unnecessary ads are not generated, in the case of a minimum viable product integration, retailers can just discard product codes that they don't have in stock. This means that if a retailer receives a product code from Citrus that is out of stock, no product information should be fetched from product storage to be sent to the frontend to show to the customer.

Retailers must ensure that Citrus-related search results are shown on the retailer's e-commerce website before regular (non-Citrus related) search results are shown. The "ad id" must be be attached to each of these search results. This does not require any changes to the database. This does not require any changes to storage.

Ensure that Impressions and Clickbacks are Reported to Citrus

The frontend of the retailer's e-commerce website must be configured so that impressions and clickbacks are reported to Citrus by means of a call to a function in the Citrus JavaScript Library. This Javascript SDK can be configured using the instructions in the "Javascript Library" page.

Ensure that Cart Items are Tracked

When items are added to the cart, each ad associated with an item must be tracked (by "ad id") in the "order item" field. This can require changes to the retailer's database or storage. These changes are likely nothing more than the addition of an "order item" column to a table in a relational database.

The "ad id" can be saved as a part of the "order item" table or can be stored otherwise as long as the relation between the ad id and the order item is preserved.

Ensure that Order Items Associated with Ad Ids are Reported to Citrus

All order items that have ad ids must be reported to Citrus when an order for those items is successfully placed. This is done by calling the "orders" endpoint.

If the above conditions are met, then your retailer catalog can be integrated seamlessly with the Citrus API.

Ways of Integrating

  • Provide Citrus with a TSV file of your catalog through SFTP.

  • Use Google Feed.

  • Contact Citrus to learn more about alternative methods of transferring catalog information.