Ads returned from ad generation endpoints should not be cached unless absolutely necessary, regardless of adtype. Every time a page is loaded on a retailer's website, a new ad generation request should be sent to CitrusAd with the correct context to generate a fresh set of ads.

In the event the retailer cannot support this, CitrusAd does offer a caching capability wherein a retailer can serve an ad to multiple customers repeat times.

🚧

Any impression and click that meets CitrusAd's criteria for a valid click will be charged accordingly. Because of this, CitrusAd strongly advises minimising the cache timeframe to within a reasonable bound of minutes to reduce overspend possibilities.

Integration requirements

sessionId is no longer required in the ad request, as the ad can be served to multiple sessions.

Any retailer wishing to cache ads needs to:

• Send a new parameter in the ad request to CitrusAd of “cached”: true in the options section.

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "placement": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "options": {
                         "filterMode": "AndOr",
                         "cached": true
                             },
    "maxNumberOfAds": 3    
}

• Be integrated with the sessionId attribution method when reporting orders.
• Be sending the sessionId encoded in the impression and click reports.
• Send an event timestamp in the impression and click reports. Timezones between events should be consistent, but which timezone is used is up to the retailer. Formatted in ISO-8601 format.

https://integration.<ENV>.citrusad.com/v1/resource/second-c/<AD_ID>?sessionId=<SESSION_ID>&event_ts=20220127152500

Once that is operational, the relevant processing on CitrusAd’s side will occur. There is no additional configuration required by CitrusAd.

How Caching Works

For cached ads, there is a configurable property named a "window". This window applies to all ad types. Additionally, there is the "expiry" property already passed in the response by CitrusAd
We use these properties to determine how we treat impressions and clicks. In certain cases, CitrusAd create a new AdId and process an impression/click accordingly.
This is how CitrusAd ensures attribution is fully functional across multiple customer sessions.

Scenario 1

For any ad for the same sessionId within the “window”, they will be treated as the same adId.

Scenario 2

For any ad with different sessionIds, we will create a new AdId, and process it as a new impression/click

Scenario 3

Any impression/click outside of the ad expiry will be logged but not charged or reported.

Scenario 4

Any clicks that occur in a window where there is no impression reported, CitrusAd infers a click, which is the current system wide behaviour.

This can be mitigated by increasing the window, and the retailer reducing their cache.

Each scenario can be expected to occur independently in production if ads are served to multiple customers.

🚧

Overspend Risk

This feature allows a retailer to serve an ad to multiple customers, multiple times without needing to request ads from CitrusAd.

This feature has not implemented any changes to how campaigns/wallets are changed. The longer an ad is cached, the higher chance of serving an ad for a campaign or wallet that is now out of funds.

CitrusAd will still process and charge for an impression/click for a campaign/wallet that is out of available funds for an ad that was served when a wallet had funds.

There are three ways to mitigate overspend in these scenarios.

• Reduce caching to the minimum possible timeframe (preferred)
  The longer an ad can be served, the larger the risk of serving an ad that is from a campaign/wallet that has since been depleted.

• CitrusAd reduce the “expiry” of all ads
  CitrusAd can reduce the timeframe in which ads are considered “valid” after serving. Any impressions/clicks after this expiry are invalidated.

• CitrusAd expand the “window” of all ads
  A larger window will reduce the volume of new impressions/clicks. However, this reduces the number of impressions/clicks reported