High-level overview
As part of this integration, you will need to do the below
- Implement an additional ad request for the cross-sell category placement.
- This includes the work to position and render ads on your site, as well as report clicks and impressions
- Orders need to be provided to CitrusAd as part of your standard integration
- If you synchronise category IDs with CitrusAd, you will need to use the filterMapping API to provide human readable values for the UI category selection
- This only applies if you are integrated with category IDs instead of names. (such as when you request ads, your filters is
category:123j-dsef-erinstead ofcategory:Milk
- This only applies if you are integrated with category IDs instead of names. (such as when you request ads, your filters is
- (Advised) - synchronise category cross-sell mappings, to automate approval and reduce campaign management load.
Ad request and site integration
Ad request
As category cross-sell requires a standalone placement, you will need to integrate an additional ad request per ad-type you are integrating category cross-sell for.
The format of your request should match the cross-sell category ad request as listed below
- Product ad - requesting category cross-sell ads
- Banner ad - requesting category cross-sell ads
- Banner X - requesting category cross-sell ads
Reporting impressions and clicks
Once you have integrated your ad request, you will also need to ensure you are reporting clicks and impressions correctly for each ad shown. Ensure you read Reporting impressions & clicks.
Reporting orders
Generally, most integrations report all order information to CitrusAd as per a standard integration. You need to ensure you are reporting all orders correctly to CitrusAd as per Order data.
Filter mappings
The filter mapping endpoint can be used to map your category IDs to human readable values. This is required if you synchronise category IDs as the UI shows the values to your users.
If you synchronise human readable categories in your product catalog with CitrusAd, this step will not be required.
Users will not understand what category:12345-abcde is. The filterMapping API can be used to map the value to the relevant category name on your site, such as category:Pantry.
There is no file based method to synchronise this information, it must be done via the filterMapping API.
As you create additional categories on your site, you will need to ensure the filterMapping API is used to update categories.
Category cross-sell mappings (advised)
It is strongly advised when integrating this type of placement, to provide a mapping of which categories are allowed to target each other. This can streamline your operations after the initial integration work. Advertiser experience is streamlined to only allow categories that are already allowed to be selected.
In addition, it is also possible to configure auto approval for cross-sell category campaigns, when cross-sell mappings are provided.
Integration methods
- You are able to use the crossSellCategory API to create and manage mappings as you require.
- Alternatively, you are able to provide a TSV file to a GCS bucket hosted by CitrusAd with the format listed below.
API integration
All required information can be seen in the crossSellCategory API reference.
File integration
If integrating by file, CitrusAd requires a file per catalog, of which categories are allowed to target between each other.
Each row in the file represents a single mapping of a category, and the category that it can target. Each mapping is single-directional (if you synchronise chocolate -> milk, chocolate products can appear on the milk category. If milk products need to be able to appear on chocolate, and additional row is required).
We need a data feed in TSV format aligning with the below specifications:
| column name | Required | Datatype | Description | Example |
|---|---|---|---|---|
category | Required | Text | This is a unique category ID identifying the category of the advertised product. | category:cookies |
cross_category_id | Required | Text | This is a unique category ID identifying an eligible category that products of category_id can be cross sold into. | category:milk |
Additional file specifications are below:
- TSV files are only supported
- TSV should be in LF not CRLF
- TSV should be UTF-8 encoded, any types will cause feed to fail
- Naming convention required:
^cross_sell_category.*.tsv$
An example snippet looks like the below:
| category | cross_category_id |
|---|---|
| category:cookies | category:milk |
| category:cookies | category:chocolate |
| category:milk | category:cookies |
This snippet above allows the cookies category to cross-sell into the milk and chocolate categories. The milk category can cross-sell into the cookies category. The chocolate category can be targeted, but cannot target any other categories.
Each row is a unique mapping combination
You need to synchronise unique rows for each unique cross-sell category mappings. Attempting to synchronise multiple cross_category_id in a single row, the file ingestion will fail.
Feature activation process
Once you are ready to start synchronising your suggested search term feed, CitrusAd will configure you a GCS bucket to drop your files into.
This capability is only supported on GCS buckets. External buckets such as AWS/Azure/other are not supported.
Your Technical Account Manager will be able to guide you through the activation of this feature. As CitrusAd's platform operations team are required to action a configuration, please be advised there is an additional turnaround time for activation.