Three commonly used integration options are available to you, which can support minor variations to suit your individual needs. It's important to note that CitrusAd is integrated via the retailer’s backend.

Standard Integration

CitrusAd's standard integration ensures the best end-user experience, as the results are delivered to the customer’s browser quickly.

📘
Listings are not shown to the end user until they have been merged.

Workflow

Before ads are served:

You synchronise your product catalog with CitrusAd via either API or a daily file sync
(Optional) you synchronise your customer data with CitrusAd via either API or a daily file sync.

When ads are served:

Your customer loads the website, then navigates to a page with a CitrusAd integration
Your website requests data from your backend server according to the internal context of the page; in this case, a category page (customerId, sessionId, productFilters)
Your backend server calls the CitrusAd API and requests ads for the 'context' of the customer’s page and ad placement
CitrusAd returns the most relevant ads for the request to your backend in the form of a product code and URL for banner ads
Your backend merges CitrusAd’s response with organic content
Your server sends the ad's organic content to the website in one response
Your website serves all content to the customer at once.

After ads are served:

When the customer sees an ad in their browser’s viewport, an impression is reported to CitrusAd for the individual adId
When the customer clicks an ad, a click is reported to CitrusAd for the individual adId
When the customer checks out their order, the order is reported to CitrusAd with order items, prices and quantities, and the customer’s customerId and sessionId.

Variation 1: individual browser requests

In this variation, you individually call your backend server for organic products, and implement a new backend service to query the CitrusAd server before merging the result in the browser. This may reduce development resources, as less changes will need to be made to existing requests by ensuring the CitrusAd request is separate.

📘
Listings are not shown to the end user until they have been merged, even though two separate calls have been made to your backend server and CitrusAd prior to merging.
You are still required to fetch all relevant product information for the product codes returned in the CitrusAd response.

Workflow variations (1)

When ads are served:

Instead of your existing backend service making a request to CitrusAd, a new request is made to a new retailer service that makes the backend call to CitrusAd with the relevant placement information
The browser merges the organic listings and the CitrusAd, and then serves content to the customer.

Variation 2: merging after displaying to the customer

In this variation, you follow a similar workflow as above; however, you will be serving the organic product results to the customer when they are available. After this, you will merge and reorder the results after you have received content from CitrusAd. This integration method is likely to take the least time to integrate, as minimal development resources are required.

📘
Organic listings will show intermittently to the end user before the product ads are merged and reordered.
You are still required to fetch all relevant product information for the product codes returned in the CitrusAd response.

Workflow variations (2)

When ads are served:

Organic listings are shown, and the CitrusAd response is merged in once the browser has received them.