Personalize on-site ads with your 1st party input. Use your own customer or scoring data to influence auctions for sponsored products.

Personalized, relevant ads are a better customer experience, are more likely to be clicked, and subsequently purchased; driving up your revenue, and platform ROI.

This gives you the opportunity to improve the personalization of ads by providing additional information to CitrusAd, either directly in the ad request, or through a file synchronization. We recommend to review each integration capability to understand which is best for you.

🚧

Under Development!

This feature is in active development, therefore please be aware the below is subject to change at CitrusAd's discretion.

🚧

Please be aware this capability only applies to product ads.

High level integration

Providing scoring data

With this feature, you will need to provide scoring to CitrusAd. We have two methods to provide scoring. Please ensure you diligently read the benefits and scope in further detail in each method's section.

• Ad request input: The request input method allows you to provide product scoring directly in the ad request to CitrusAd. This product scoring provided by you is then considered as an additional factor to CitrusAd's relevancy algorithm.
• File input: This method allows retailers (or 3rd party partners) to send CitrusAd customer+product scores via file to influence the relevancy scoring. These scores are updated periodically and referenced when generating ads

Understanding active products (advised)

To ensure your product scoring is efficient, and only sending product scoring to CitrusAd if there are active campaigns, we recommend to use CitrusAd's Reporting API to periodically check once per day which products are currently advertised, and optimise scoring information from there.

🚧

Selected availability

CitrusAd's reporting API is currently only rolled out to selected partners, this capability may not currently be available to you, and you may not be able to use this advised method at this point in time.

SELECT
campaign_catalog_products
FROM
  <PROJECT>.<NODE>.campaign 
 where is_current is true and active_state='ACTIVE'

This will provide you a basic list of product codes that you will need to unnest and consume into your personalisation/scoring processes.

👍

This is a starter query

You might be after more information, such as the team, campaign, or even if the campaign has spent money recently. You may be able to enhance your query further by joining other tables available to you, for your specific business needs.

Scoring input method 1: ad request input (recommended)

The request input method allows you to provide product scoring directly in the ad request to CitrusAd. This product scoring provided by you is then considered as an additional factor to CitrusAd's relevancy algorithm.

Benefits

• Does not strictly require customer information to activate (you can pre-process this and only provide productBias, not customerId)
• Real-time influence over the auction, you are able to update your scoring as option as you require.
• Retailers can start with basic product-scoring and enhance with personalization at a later stage
• Can negatively score products by providing a score of -1, removing them from the auction

Scope

• Maximum of 100 product scores per ad request
  • Please note this is subject to change as the feature is developed
• Retailers will have additional work required to define which products are active. Retailers that have integrated CitrusAd's reporting API (additional fee) can determine active products via the available tables, once per day.
• Invalid requests where the product id or score has invalid formatting will result in an error response
• The below apply to both synchronization methods
  • If no score is provided for a product that is advertised, CitrusAd will score it according to the standard relevancy scoring.
  • The product-scoring supplied by the retailer will remain as a factor in the relevancy auction, and is not the only source of scoring
  • Solution applies to product ads only, Banner ads are out of scope
  • Final ​price calculations are defined by CitrusAd

Integration requirements

When sending ad requests to CitrusAd, you can use a new productBias array to indicate relevancy scoring per-product. The format is 5 decimal points, ranging from 0 to 1. Each product code has a standalone score. An example is below:

    "productBias": {
        "48596":"0.05223",
        "7781":"0.5",
        "102774":"0.09111",
        "79693":"-1”
    }

A full example ad request is below:

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9", 
    "placement": "category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
     	 ["category:Cupboard/Snacks"]
    ],
    "options": {
   							 "filterMode": "AndOr"
 							 },
    "productBias": {
        "48596":"0.05223",
        "7781":"0.5",
        "102774":"0.09111",
        "79693":"-1”
    },
    "maxNumberOfAds": 3
}

The ad response will have no change to format, and does not include the final scoring.

As mentioned in the scope, if there is any invalid formatting, you will receive a 400 error response with a message informing you of an issue with the productBias.

Scoring input method 2: data file input

This method allows retailers to send CitrusAd customer+product scores via file to influence the relevancy scoring. These scores are updated periodically and referenced when generating ads

Benefits

• You are able to enhance the algorithm by providing your product relevancy scores per customer
• By incorporating your data, the algorithm can better predict which ads are likely to be of interest to the user and therefore improve the overall effectiveness of the ad serving.

Scope

• Maximum of 1,000 product scores per customer
• Maximum of 1,450,000,000 rows synchronized
  • If you expect to exceed this volume, we recommend to implement via the request input option
• The below apply to both synchronization methods
  • If no score is provided for a product that is advertised, CitrusAd will score it according to the standard relevancy scoring.
  • The product-scoring supplied by the retailer will remain as a factor in the relevancy auction, and is not the only source of scoring
  • Solution applies to product ads only, Banner ads are out of scope
  • Final ​price calculations are defined by CitrusAd

📘

Customer ID

Please note a customer ID is required in this method. Customer ID can be obfuscated, as long as the Customer ID in the ad request reflects the customer ID in the file synchronized.

Integration requirements

Synchronizing your scoring file

You will need to produce and manage a file that is pushed to a Google Cloud Storage bucket provided and managed by CitrusAd. The format is strictly CSV. An example is below:

The data type for the scores to be stored with least 32 bits. It can be of type floating point, fixed-
point decimal, or integer. However, it’s important to support floating point arithmetic at the point of
calculating the combination with bid price as described below (e. g. multiplication with floating point
bid price, mathematical power operation).

Requesting ads

When requesting ads, you also need to ensure you are sending a customerId in the request to CitrusAd. This must be an identical value to the value for the customer synchronized in the file. These two steps can be implemented in isolation of each other.

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

When an ad request is received with a customerId, CitrusAd considers the customer-product score combinations for any scores that match the product IDs and customer ID (from the ad request) pair. For any matches, the provided score is factored into the relevancy algorithm.

Frequently asked questions

What happens if I send a product score and there's no campaign active for it?

This is fine, as there is no active ads for the product code, it will be ignored

Should I send scoring at a parent product level, or child product?

If you are integrated with CitrusAd's parent product capability, you should still send scoring at a child product level, as this is the product code in the CitrusAd system, the parent is the product collection.